@piyawasin/byte-flags
Version:
A lightweight, type-safe utility library for efficiently storing and managing boolean flags in compact numeric values (8, 16, or 32 bits). Perfect for permission systems, feature flags, status tracking, and any scenario requiring compact boolean storage w
158 lines (157 loc) • 5.35 kB
TypeScript
/**
* Abstract base class for efficiently storing and managing boolean flags in a numeric value.
* This provides the common functionality for ByteFlags, ShortFlags, and LongFlags.
*/
export declare abstract class BaseFlags {
/** The internal value storing all flags */
protected value: number;
/** Current index for the next flag to be added */
protected nextIndex: number;
/** List of all flag names in order of creation */
protected readonly flagList: readonly string[];
/** Mapping of flag names to their bit positions */
protected readonly flagIndices: Map<string, number>;
/** Maximum number of flags that can be stored */
protected abstract readonly MAX_FLAGS: number;
/** Maximum value (based on storage size) */
protected abstract readonly MAX_VALUE: number;
/**
* Create a new flags instance with the specified flag names
* @param flagNames Names of flags to initialize
* @throws Error if no flag names are provided or if flag names are invalid
*/
constructor(...flagNames: string[]);
/**
* Add a new flag to this instance
* @param name Name of the flag to add
* @throws Error if more than maximum number of flags are added or if flag name is invalid
*/
protected addFlag(name: string): void;
/**
* Get the value of a bit at the specified position
* @param position Bit position
* @returns Boolean value of the bit
*/
protected getBit(position: number): boolean;
/**
* Set the value of a bit at the specified position
* @param position Bit position
* @param value Boolean value to set
*/
protected setBit(position: number, value: boolean): void;
/**
* Check if a flag exists in this instance
* @param name The name of the flag to check
* @returns True if the flag exists, false otherwise
*/
hasFlag(name: string): boolean;
/**
* Get the value of a flag by name
* @param name The name of the flag to get
* @returns The boolean value of the flag
* @throws Error if the flag doesn't exist
*/
getFlag(name: string): boolean;
/**
* Set the value of a flag by name
* @param name The name of the flag to set
* @param value The boolean value to set
* @returns This instance for chaining
* @throws Error if the flag doesn't exist
*/
setFlag(name: string, value: boolean): this;
/**
* Toggle a flag's value
* @param name The name of the flag to toggle
* @returns This instance for chaining
* @throws Error if the flag doesn't exist
*/
toggleFlag(name: string): this;
/**
* Set multiple flags at once
* @param flags Object with flag names as keys and boolean values
* @returns This instance for chaining
*/
setFlags(flags: Record<string, boolean>): this;
/**
* Toggle multiple flags at once
* @param names Names of the flags to toggle
* @returns This instance for chaining
*/
toggleFlags(...names: string[]): this;
/**
* Get the number of flags currently set to true
* @returns Count of set flags
*/
count(): number;
/**
* Check if any flag is set to true
* @returns True if any flag is true
*/
any(): boolean;
/**
* Check if no flags are set to true
* @returns True if all flags are false
*/
none(): boolean;
/**
* Convert the flags to a numeric value
* @returns Numeric representation of all flags
*/
toValue(): number;
/**
* Load flags from a numeric value
* @param v Value to load
* @returns This instance for chaining
* @throws Error if the value is invalid
*/
fromValue(v: number): this;
/**
* Convert the flags to a plain JavaScript object
* @returns Object with flag names as keys and boolean values
*/
toObject(): Record<string, boolean>;
/**
* Convert the flags to a JSON string
* @returns JSON string representation of the flags
*/
toJSON(): string;
/**
* Check if all specified flags are set to true
* @param flags Flag names to check
* @returns True if all specified flags are true
*/
all(...flags: string[]): boolean;
/**
* Check if any of the specified flags are set to true
* @param flags Flag names to check
* @returns True if any specified flag is true
*/
anyOf(...flags: string[]): boolean;
/**
* Check if none of the specified flags are set to true
* @param flags Flag names to check
* @returns True if no specified flags are true
*/
noneOf(...flags: string[]): boolean;
/**
* Get an array of all flag names
* @returns Array of all flag names in order of creation
*/
getFlagNames(): string[];
/**
* Get an iterator for all flags as [name, value] pairs
* @returns Iterator yielding [name, boolean] tuples
*/
[Symbol.iterator](): IterableIterator<[string, boolean]>;
/**
* Get a string representation of the flags
* @returns String in the format "FlagsType {flag1=true, flag2=false, ...}"
*/
toString(): string;
/**
* @deprecated Use getFlagNames() instead for better clarity
* @returns Array of all flag names
*/
getFlags(): string[];
}