bitwise-flag - v2.1.0
    Preparing search index...

    Class NumberFlagRegistry<TFlags, TBrand>

    Type Parameters

    • TFlags extends string
    • TBrand extends string | symbol = symbol

    Hierarchy

    • AbstractFlagRegistry<TFlags, number, TBrand>
      • NumberFlagRegistry
    Index

    Properties

    combinator repository MAX_SAFE_FLAG

    Accessors

    fullBits

    Methods

    coerce combine empty entries full get keys of parse values define findDuplicates from hasDuplicates

    Properties

    combinator: Combinator<number> = NUMBER_COMBINATOR

    The bitwise combinator used internally to perform AND, OR, NOT, and other operations on values of type TBit.

    repository: Repository<TFlags, number>

    The underlying read-only store that maps flag names to their bit values.

    MAX_SAFE_FLAG: 1073741824 = 0x40000000

    The largest bit value that can be safely used as a flag (0x40000000 = 2^30).

    JavaScript bitwise operators work on 32-bit signed integers internally. The most significant bit (bit 31) is the sign bit, so using it causes the result to become negative. MAX_SAFE_FLAG is therefore capped at 2^30, leaving the sign bit untouched and keeping all flag values positive. This limits a NumberFlagRegistry to at most 31 distinct flags.

    Accessors

    • get fullBits(): TBit

      A bitmask with every registered flag set — the bitwise OR of all flag values.

      Returns TBit

      // For a registry with READ=1, WRITE=2, EXEC=4:
      registry.fullBits; // 7

    Methods

    • Internal

      Converts a raw value or string representation into the registry's native bit type TBit.

      Parameters

      • value: string | number

        A native bit value or its string representation.

      Returns number

      The parsed value as TBit.

      ParseError if value cannot be converted to a valid non-negative TBit.

    • Creates a Flag from one or more flag names by combining their bit values with bitwise OR.

      Parameters

      • ...flags: TFlags[]

        The names of flags to combine.

      Returns Flag<TFlags, number, TBrand>

      A Flag whose Flag.bits is the OR of all given flags.

      UnknownFlagError if any name is not registered.

      // READ = 1, WRITE = 2
      registry.combine("READ", "WRITE").bits; // READ | WRITE = 1 | 2 = 3
      registry.combine().isEmpty();           // true

      Use FlagRegistry.of instead.

    • Returns all [name, bit] pairs for registered flags in registration order. Same as registry.repository.entries().

      Returns [TFlags, number][]

      registry.entries(); // [["READ", 1], ["WRITE", 2], ["EXEC", 4]]

    • Returns the raw bit value assigned to the given flag name. Same as registry.repository.get()

      Parameters

      • flagName: TFlags

        The registered flag name to look up.

      Returns number

      The bit value for flagName.

      UnknownFlagError if flagName is not registered.

      registry.get("READ"); // 1

    • Returns all registered flag names in registration order. Same as registry.repository.keys().

      Returns TFlags[]

      registry.keys(); // ["READ", "WRITE", "EXEC"]

    • Parses a raw bit value or string into a Flag.

      String values may use numeric prefixes: "0b" for binary, "0o" for octal, "0x" for hexadecimal, or a plain decimal string.

      Parameters

      • value: string | number

        The bit value or string representation to parse.

      Returns Flag<TFlags, number, TBrand>

      A Flag whose Flag.bits equal the parsed value.

      ParseError if value cannot be converted to TBit.

      UnknownBitsError if the parsed value contains bits not present in any registered flag.

      registry.parse(3);      // Flag with bits 3
      registry.parse("0b11"); // Flag with bits 3
      registry.parse("0x3");  // Flag with bits 3

    • Parameters

      • value: string | number
      • radix: unknown

      Returns Flag<TFlags, number, TBrand>

      Do not pass radix parameter. Use prefixes (0b, 0o or 0x) or parseInt explicitly instead

    • Returns all registered bit values in registration order. Same as registry.repository.values().

      Returns number[]

      registry.values(); // [1, 2, 4]

    • Creates a NumberFlagRegistry from an explicit name-to-bit mapping.

      Use this factory when you need precise control over bit values — for example, when values must match an external protocol, a database column, or a legacy enum.

      Type Parameters

      • TFlags extends string
      • TBrand extends string | symbol = symbol

      Parameters

      • flags: Record<TFlags, number>

        A plain object whose keys are flag names and values are the number bit values to assign to each flag.

      Returns FlagRegistry<TFlags, number, TBrand>

      A new FlagRegistry typed to the given flag names and branded with TBrand.

      NotPositiveError if any value is ≤ 0.

      OverflowError if any value exceeds MAX_SAFE_FLAG (2^30).

      DuplicateError if two flags share the same bit value.

      NotPowerOfTwoError if any value is not a power of two.

      const registry = NumberFlagRegistry.define({
        READ:    1,
        WRITE:   2,
        EXECUTE: 4,
      });

      registry.of("READ", "WRITE").bits; // 3
    • Internal

      Finds duplicates from the passed array.

      Parameters

      • flags: string[]

        array with flag names.

      Returns string[]

      array with all duplicates.

    • Creates a NumberFlagRegistry from a list of flag names, auto-assigning consecutive powers of two as bit values.

      The first name receives 2 ** 0 = 1, the second 2 ** 1 = 2, the third 2 ** 2 = 4, and so on. Because JS bitwise operators are limited to 32-bit signed integers, the registry supports at most 31 flags (up to 2 ** 30 = MAX_SAFE_FLAG). For more flags use BigIntFlagRegistry.from instead.

      Type Parameters

      • TFlags extends string
      • TBrand extends string | symbol = symbol

      Parameters

      • ...flags: TFlags[]

        Flag names in registration order. Each name must be unique.

      Returns FlagRegistry<TFlags, number, TBrand>

      A new FlagRegistry typed to the given flag names and branded with TBrand.

      DuplicateFlagsError if any name appears more than once.

      OverflowError if the number of flags exceeds 31.

      const registry = NumberFlagRegistry.from("READ", "WRITE", "EXECUTE");
      // READ = 1, WRITE = 2, EXECUTE = 4

      registry.of("READ", "EXECUTE").bits; // 5
    • Internal

      Checks whether the passed array has duplicate values.

      Parameters

      • flags: string[]

        array with flag names.

      Returns boolean

      true if the array has duplicates and false otherwise.

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods