Class Flag<TFlags>

constructor

• new Flag<TFlags extends string>(
      context: IFlagsRegistry<TFlags>,
      value: bigint,
  ): Flag<TFlags>

  Type Parameters

  • TFlags extends string

  Parameters

  • context: IFlagsRegistry<TFlags>

    The registry defining the valid flags and their bit positions.

  • value: bigint

    The raw BigInt bitmask representing the combined flags (e.g., 3n for bits 0 and 1 set).

  Returns Flag<TFlags>

  Throws

  If value is negative (e.g., Flag value cannot be negative: -1).

  Throws

  If value contains unknown bits (e.g., Flag value contains unknown flags).

Readonlyvalue

alias

• get alias(): string

  A computed, human-readable alias for the flag combination.

  • For empty flags (value 0n), returns "EMPTY_FLAG".
  • For single flags, returns e.g., "[READ]".
  • For multiple flags, returns e.g., "[READ+WRITE]".

  Returns string

  Example

  flag.alias; // "[READ+WRITE]" for a combined flag
  Copy

add

• add(...flagNames: TFlags[]): IFlag<TFlags>

  Adds one or more flag keys to this flag combination, creating a new instance with the updated bitmask.

  • Idempotent: If a flag is already set, it remains unchanged.
  • Only adds flags that exist in the registry; unknown keys throw an error.
  • Returns the current instance if no changes are made (e.g., all flags already present).

  Parameters

  • ...flagNames: TFlags[]

    One or more flag keys to add.

  Returns IFlag<TFlags>

  A new Flag instance with the added flags, or the current instance if unchanged.

  Throws

  If any flagName is not registered in the registry (e.g., Flag with key UNKNOWN is not found.).

  Example

  const base = registry.combine("READ");
  const extended = base.add("WRITE", "EXECUTE");
  extended.has("WRITE"); // true
  base.has("WRITE"); // false (immutable)
  Copy

has

• has(flagName: TFlags): boolean

  Tests whether a specific flag key is set in this flag combination.

  Performs a bitwise AND between the instance's value and the bitmask of the given flag key. Returns false if the key is not found in the registry.

  Parameters

  • flagName: TFlags

    The flag key to check (must be a valid key in the registry).

  Returns boolean

  true if the flag is set, false otherwise.

  Example

  const userFlag = registry.combine("READ", "EXECUTE");
  userFlag.has("READ"); // true
  userFlag.has("WRITE"); // false
  Copy

isEmpty

• isEmpty(): boolean

  Checks if this flag instance represents no set flags (i.e., the bitmask value is 0n).

  Returns boolean

  true if the flag is empty, false otherwise.

  Example

  const empty = registry.empty();
  empty.isEmpty(); // true
  
  const full = registry.combine("READ", "WRITE");
  full.isEmpty(); // false
  Copy

remove

• remove(...flagNames: TFlags[]): IFlag<TFlags>

  Removes one or more flag keys from this flag combination, creating a new instance with the updated bitmask.

  • Idempotent: If a flag is not set, it remains unchanged.
  • Only removes flags that exist in the registry; unknown keys throw an error.
  • Returns the current instance if no changes are made (e.g., none of the flags were present).

  Parameters

  • ...flagNames: TFlags[]

    One or more flag keys to remove.

  Returns IFlag<TFlags>

  A new Flag instance with the removed flags, or the current instance if unchanged.

  Throws

  If any flagName is not registered in the registry (e.g., Flag with key UNKNOWN is not found.).

  Example

  const full = registry.combine("READ", "WRITE");
  const reduced = full.remove("WRITE");
  reduced.has("WRITE"); // false
  full.has("WRITE"); // true (immutable)
  Copy

toString

• toString(): string

  Returns a human-readable string representation of this flag instance.

  The format is Flag(${alias}: ${value}), where alias is the computed alias (e.g., [READ+WRITE]) and value is the raw BigInt bitmask.

  Returns string

  A string like Flag([READ+WRITE]: 3).

  Example

  const flag = registry.combine("READ");
  flag.toString(); // "Flag([READ]: 1)"
  
  const empty = registry.empty();
  empty.toString(); // "Flag(EMPTY_FLAG: 0)"
  Copy