Skip to content

John-Paul-R/bitflags-ts

Repository files navigation

bitflags-ts

An enum-like type for representing & using bit flags

build-status-badge npm bundle size

Usage

Note: I don't particularly recommend using this package! Bit flags are great, and can be created and used quite simply in TypeScript (demonstrated in fantastically concise fashion in this SO answer). This package abstracts away the bitwise operations, but is not without performance cost. As long as you're fine with seeing | and &, use native bit flag enums!

Also note: JS coerces numbers to 32 bits before performing any bitwise operations, so the maximum number of flags that can be represented by a bit flag type is 32!

bitFlag

const PermissionsFlag = bitFlag('Read', 'Write', 'Execute');

const userPermissions = PermissionsFlag.union(PermissionsFlag.Read, PermissionsFlag.Write);

const canRead = userPermissions.hasFlag(PermissionsFlag.Read); // true
const canExecute = userPermissions.hasFlag(PermissionsFlag.Execute); // false

createBitFlagsEnum

An alternative syntax that creates an 'enum' with object-valued (instead of Number-valued, as in bitFlag) members. While this has higher one-time allocation cost, there are more utilities for working with the values themselves on the enum member instances.

const PermissionsFlag = createBitFlagsEnum(['Read', 'Write', 'Execute'] as const);

{ // offers 'or' syntax on the enum value itself
  const userPermissions = PermissionsFlag.Read
    .or(PermissionsFlag.Write)
    .or(PermissionsFlag.Execute);
  const canRead = userPermissions.hasFlag(PermissionsFlag.Read); // true
  const canExecute = userPermissions.hasFlag(PermissionsFlag.Execute); // true
}

{ // static `union` works in the same fashion as bitFlag
  const userPermissions = PermissionsFlag.union([PermissionsFlag.Read, PermissionsFlag.Write]);
  const canRead = userPermissions.hasFlag(PermissionsFlag.Read); // true
  const canExecute = userPermissions.hasFlag(PermissionsFlag.Execute); // false
}