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

    Class BigIntFlagRegistry<TFlags, TBrand>

    Type Parameters

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

    Hierarchy

    • AbstractFlagRegistry<TFlags, bigint, TBrand>
      • BigIntFlagRegistry
    Index

    Properties

    combinator repository

    Accessors

    fullBits

    Methods

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

    Properties

    combinator: Combinator<bigint> = BIGINT_COMBINATOR

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

    repository: Repository<TFlags, bigint>

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

    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 | bigint

        A native bit value or its string representation.

      Returns bigint

      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, bigint, 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, bigint][]

      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 bigint

      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 | bigint

        The bit value or string representation to parse.

      Returns Flag<TFlags, bigint, 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 | bigint
      • radix: unknown

      Returns Flag<TFlags, bigint, 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 bigint[]

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

    • Creates a BigIntFlagRegistry 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, bigint>

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

      Returns FlagRegistry<TFlags, bigint, TBrand>

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

      NotPositiveError if any value is ≤ 0n.

      DuplicateError if two flags share the same bit value.

      NotPowerOfTwoError if any value is not a power of two.

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

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

      Finds duplicates from the passed array.

      Parameters

      • flags: string[]

        array with flag names.

      Returns string[]

      array with all duplicates.

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

      The first name receives 2n ** 0n = 1n, the second 2n ** 1n = 2n, the third 2n ** 2n = 4n, and so on. Because bigint has no fixed width, the registry supports an unlimited number of flags.

      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, bigint, TBrand>

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

      DuplicateFlagsError if any name appears more than once.

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

      registry.of("READ", "EXECUTE").bits; // 5n
    • 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