Bitfield

A powerful, type-safe and flexible bitfield utility for JavaScript and TypeScript.

Supports bigint, multiple input formats, immutability, and dynamic class creation.

✨ Features

• ⚡ Type-safe flags
• 🧠 Accepts multiple input formats (string, bigint, arrays, instances)
• 🔢 Uses bigint (no 32-bit limits)
• 🧩 Dynamic bitfield classes with createBitfield
• 🔄 Mutable and immutable modes (via Object.freeze)
• 📦 Fully typed for TypeScript
• 🧪 Designed for reliability and testing

📦 Installation

npm install sybits

🚀 Quick Start

import { createBitfield } from "your-package-name";

const Permissions = createBitfield([
  "READ",
  "WRITE",
  "DELETE"
] as const);

const perms = new Permissions([
  "READ", 
  "WRITE"
]);

perms.has("READ");   // true
perms.has("DELETE"); // false

🧠 Creating a Bitfield

Simple

const Permissions = createBitfield([
  "READ",
  "WRITE",
  "DELETE"
] as const);

Advanced

const PermissionsBits = {
  READ: 1n << 0n,
  WRITE: 1n << 1n,
  DELETE: 1n << 2n
}
const Permissions = createBitfield(
  PermissionsBits,
  // Default Bits ( READ and WRITE )
  PermissionsBits.READ | PermissionsBits.WRITE
);

🛠️ Usage

Add / Remove

perms.add("READ");
perms.remove("WRITE");

Check flags

perms.has("READ"); // true

Multiple input formats

perms.add(
  "READ",
  ["WRITE", "DELETE"],
  1n,
  new Permissions("READ")
);

Missing flags

perms.missing(["READ", "WRITE", "DELETE"]);
// → ["WRITE", "DELETE"]

Convert to array

perms.toArray();
// → ["READ", "WRITE"]

Serialize

perms.serialize();
// → { READ: true, WRITE: true, DELETE: false }

Iterate

for (const flag of perms) {
  console.log(flag);
}

🔒 Immutability

If the instance is frozen, operations return a new instance:

const frozen = Object.freeze(new Permissions("READ"));

const updated = frozen.add("WRITE");

updated.has("WRITE"); // true
frozen.has("WRITE");  // false

🔢 Raw Value

perms.bits; // bigint

🧩 Static Properties

Permissions.Flags.READ; // bigint
Permissions.ALL;        // bigint (all flags combined)

🧠 How resolve Works

The library automatically resolves inputs like:

• string → flag
• bigint → raw value
• Bitfield → its bits
• arrays → recursively flattened and combined

⚠️ Notes

• Always use as const when defining flags arrays to preserve type safety
• toJSON() returns a number (may lose precision for very large bitfields)