flags

Functional utilities for bitwise flags.

Documentation

Example

import{pipe}from"@monstermann/dfdl";import{Flags}from"@monstermann/flags";// Define a schema for your flagsconstpermissions={read: 0,write: 1,execute: 2,delete: 3,}asconst;// Create a bitmask from the schemaletuserFlags=Flags.fromRecord(permissions);// 15 (0b1111 - all flags set)// Add and remove flagsuserFlags=pipe(userFlags,Flags.remove(permissions.delete),Flags.remove(permissions.execute),);// 3 (0b0011 - only read and write)// Check individual flagsFlags.has(userFlags,permissions.read);// trueFlags.has(userFlags,permissions.execute);// false// Check multiple flagsFlags.hasAll(userFlags,[permissions.read,permissions.write]);// trueFlags.hasAny(userFlags,[permissions.execute,permissions.delete]);// false// Convert to a recordFlags.toRecord(userFlags,permissions);// { read: true, write: true, execute: false, delete: false }// Set operationsconstadminFlags=Flags.fromRecord({read: 0,write: 1,execute: 2,delete: 3,});constguestFlags=Flags.fromRecord({read: 0});Flags.union(guestFlags,Flags.fromRecord({write: 1}));// 3 (0b011 - read and write)Flags.intersection(userFlags,adminFlags);// 3 (0b011 - common flags: read and write)Flags.isSubset(guestFlags,adminFlags);// trueFlags.isSuperset(adminFlags,guestFlags);// true

Installation

npm install @monstermann/flags

pnpm add @monstermann/flags

yarn add @monstermann/flags

bun add @monstermann/flags

Tree-shaking

Installation

npm install -D @monstermann/unplugin-flags

pnpm -D add @monstermann/unplugin-flags

yarn -D add @monstermann/unplugin-flags

bun -D add @monstermann/unplugin-flags

Usage

// vite.config.tsimportflagsfrom"@monstermann/unplugin-flags/vite";exportdefaultdefineConfig({plugins: [flags()],});

// rollup.config.jsimportflagsfrom"@monstermann/unplugin-flags/rollup";exportdefault{plugins: [flags()],};

// rolldown.config.jsimportflagsfrom"@monstermann/unplugin-flags/rolldown";exportdefault{plugins: [flags()],};

// webpack.config.jsconstflags=require("@monstermann/unplugin-flags/webpack");module.exports={plugins: [flags()],};

// rspack.config.jsconstflags=require("@monstermann/unplugin-flags/rspack");module.exports={plugins: [flags()],};

// esbuild.config.jsimport{build}from"esbuild";importflagsfrom"@monstermann/unplugin-flags/esbuild";build({plugins: [flags()],});

Flags

add

functionFlags.add(target: number,flag: Flag): number

Adds a flag to the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.add(0,0);// 1Flags.add(0,1);// 2Flags.add(5,1);// 7

import{Flags}from"@monstermann/flags";pipe(0,Flags.add(0));// 1pipe(0,Flags.add(1));// 2pipe(5,Flags.add(1));// 7

addAll

functionFlags.addAll(target: number,flags: Iterable<Flag>): number

Adds multiple flags to the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.addAll(0,[0,1,2]);// 7Flags.addAll(1,[2,3]);// 13

import{Flags}from"@monstermann/flags";pipe(0,Flags.addAll([0,1,2]));// 7pipe(1,Flags.addAll([2,3]));// 13

assert

functionFlags.assert(flag: unknown): asserts flag is Flag

Asserts that a value is a valid Flag (integer between 0 and 30), throwing an error if not.

Example

import{Flags}from"@monstermann/flags";Flags.assert(0);// okFlags.assert(15);// okFlags.assert(30);// okFlags.assert(31);// throws Error: flag must be >= 0 and <= 30Flags.assert(-1);// throws Error: flag must be >= 0 and <= 30Flags.assert(1.5);// throws Error: flag must be an integerFlags.assert("0");// throws Error: flag must be an integer

difference

functionFlags.difference(target: number,source: number): number

Returns a bitmask with flags that are in target but not in source (bitwise AND NOT).

Example

import{Flags}from"@monstermann/flags";Flags.difference(7,3);// 4Flags.difference(15,5);// 10

import{Flags}from"@monstermann/flags";pipe(7,Flags.difference(3));// 4pipe(15,Flags.difference(5));// 10

fromRecord

functionFlags.fromRecord(flags: Record<PropertyKey,Flag>): number

Converts a record of flag positions to a bitmask with all those flags set.

Example

import{Flags}from"@monstermann/flags";Flags.fromRecord({read: 0,write: 1,execute: 2});// 7Flags.fromRecord({read: 0,execute: 2});// 5Flags.fromRecord({});// 0

has

functionFlags.has(target: number,flag: Flag): boolean

Checks if a flag is set in the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.has(7,0);// trueFlags.has(7,1);// trueFlags.has(7,3);// false

import{Flags}from"@monstermann/flags";pipe(7,Flags.has(0));// truepipe(7,Flags.has(1));// truepipe(7,Flags.has(3));// false

hasAll

functionFlags.hasAll(target: number,flags: Iterable<Flag>): boolean

Checks if all specified flags are set in the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.hasAll(7,[0,1]);// trueFlags.hasAll(7,[0,3]);// false

import{Flags}from"@monstermann/flags";pipe(7,Flags.hasAll([0,1]));// truepipe(7,Flags.hasAll([0,3]));// false

hasAny

functionFlags.hasAny(target: number,flags: Iterable<Flag>): number

Checks if any of the specified flags are set in the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.hasAny(7,[0,3]);// trueFlags.hasAny(7,[3,4]);// false

import{Flags}from"@monstermann/flags";pipe(7,Flags.hasAny([0,3]));// truepipe(7,Flags.hasAny([3,4]));// false

hasNone

functionFlags.hasNone(target: number,flags: Iterable<Flag>): boolean

Checks if none of the specified flags are set in the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.hasNone(7,[3,4]);// trueFlags.hasNone(7,[0,3]);// false

import{Flags}from"@monstermann/flags";pipe(7,Flags.hasNone([3,4]));// truepipe(7,Flags.hasNone([0,3]));// false

intersection

functionFlags.intersection(target: number,source: number): number

Returns a bitmask with only flags that are set in both target and source (bitwise AND).

Example

import{Flags}from"@monstermann/flags";Flags.intersection(7,3);// 3Flags.intersection(12,10);// 8

import{Flags}from"@monstermann/flags";pipe(7,Flags.intersection(3));// 3pipe(12,Flags.intersection(10));// 8

invert

functionFlags.invert(target: number,flags: Record<PropertyKey,Flag>): number

Inverts (toggles) all flags specified in the record.

Example

import{Flags}from"@monstermann/flags";constschema={read: 0,write: 1,execute: 2};Flags.invert(7,schema);// 0Flags.invert(5,{read: 0,write: 1});// 6

import{Flags}from"@monstermann/flags";constschema={read: 0,write: 1,execute: 2};pipe(7,Flags.invert(schema));// 0pipe(5,Flags.invert({read: 0,write: 1}));// 6

isDisjointFrom

functionFlags.isDisjointFrom(target: number,source: number): boolean

Checks if target and source have no common flags.

Example

import{Flags}from"@monstermann/flags";Flags.isDisjointFrom(5,10);// trueFlags.isDisjointFrom(7,3);// falseFlags.isDisjointFrom(0,7);// true

import{Flags}from"@monstermann/flags";pipe(5,Flags.isDisjointFrom(10));// truepipe(7,Flags.isDisjointFrom(3));// falsepipe(0,Flags.isDisjointFrom(7));// true

isSubsetOf

functionFlags.isSubsetOf(target: number,source: number): boolean

Checks if target is a subset of source (all flags in target are also in source).

Example

import{Flags}from"@monstermann/flags";Flags.isSubsetOf(3,7);// trueFlags.isSubsetOf(7,3);// falseFlags.isSubsetOf(0,7);// true

import{Flags}from"@monstermann/flags";pipe(3,Flags.isSubsetOf(7));// truepipe(7,Flags.isSubsetOf(3));// falsepipe(0,Flags.isSubsetOf(7));// true

isSupersetOf

functionFlags.isSupersetOf(target: number,source: number): boolean

Checks if target is a superset of source (target contains all flags from source).

Example

import{Flags}from"@monstermann/flags";Flags.isSupersetOf(7,3);// trueFlags.isSupersetOf(3,7);// falseFlags.isSupersetOf(7,0);// true

import{Flags}from"@monstermann/flags";pipe(7,Flags.isSupersetOf(3));// truepipe(3,Flags.isSupersetOf(7));// falsepipe(7,Flags.isSupersetOf(0));// true

isValid

functionFlags.isValid(flag: unknown): flag is Flag

Type guard that checks if a value is a valid Flag (integer between 0 and 30).

Example

import{Flags}from"@monstermann/flags";Flags.isValid(0);// trueFlags.isValid(15);// trueFlags.isValid(30);// trueFlags.isValid(31);// false (out of range)Flags.isValid(-1);// false (negative)Flags.isValid(1.5);// false (not an integer)Flags.isValid("0");// false (not a number)

remove

functionFlags.remove(target: number,flag: Flag): number

Removes a flag from the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.remove(7,0);// 6Flags.remove(7,1);// 5

import{Flags}from"@monstermann/flags";pipe(7,Flags.remove(0));// 6pipe(7,Flags.remove(1));// 5

removeAll

functionFlags.removeAll(target: number,flags: Iterable<Flag>): number

Removes multiple flags from the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.removeAll(7,[0,1]);// 4Flags.removeAll(15,[1,3]);// 5

import{Flags}from"@monstermann/flags";pipe(7,Flags.removeAll([0,1]));// 4pipe(15,Flags.removeAll([1,3]));// 5

symmetricDifference

functionFlags.symmetricDifference(target: number,source: number): number

Returns a bitmask with flags that are in either target or source, but not both (bitwise XOR).

Example

import{Flags}from"@monstermann/flags";Flags.symmetricDifference(7,3);// 4Flags.symmetricDifference(12,10);// 6

import{Flags}from"@monstermann/flags";pipe(7,Flags.symmetricDifference(3));// 4pipe(12,Flags.symmetricDifference(10));// 6

toggle

functionFlags.toggle(target: number,flag: Flag): number

Toggles a flag in the bitmask (sets it if unset, unsets it if set).

Example

import{Flags}from"@monstermann/flags";Flags.toggle(7,0);// 6Flags.toggle(7,3);// 15Flags.toggle(0,2);// 4

import{Flags}from"@monstermann/flags";pipe(7,Flags.toggle(0));// 6pipe(7,Flags.toggle(3));// 15pipe(0,Flags.toggle(2));// 4

toggleAll

functionFlags.toggleAll(target: number,flags: Iterable<Flag>): number

Toggles multiple flags in the bitmask.

Example

import{Flags}from"@monstermann/flags";Flags.toggleAll(7,[0,3]);// 14Flags.toggleAll(5,[1,2]);// 1

import{Flags}from"@monstermann/flags";pipe(7,Flags.toggleAll([0,3]));// 14pipe(5,Flags.toggleAll([1,2]));// 1

toRecord

functionFlags.toRecord(target: number,flags: Record<T,Flag>): Record<T,boolean>

Converts a bitmask to a record of boolean values based on the provided flag schema.

Example

import{Flags}from"@monstermann/flags";constschema={read: 0,write: 1,execute: 2};Flags.toRecord(7,schema);// { read: true, write: true, execute: true }Flags.toRecord(5,schema);// { read: true, write: false, execute: true }

import{Flags}from"@monstermann/flags";constschema={read: 0,write: 1,execute: 2};pipe(7,Flags.toRecord(schema));// { read: true, write: true, execute: true }pipe(5,Flags.toRecord(schema));// { read: true, write: false, execute: true }

union

functionFlags.union(target: number,source: number): number

Returns a bitmask with all flags from either target or source (bitwise OR).

Example

import{Flags}from"@monstermann/flags";Flags.union(5,3);// 7Flags.union(12,10);// 14

import{Flags}from"@monstermann/flags";pipe(5,Flags.union(3));// 7pipe(12,Flags.union(10));// 14