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";constPermissions=createBitfield(["READ","WRITE","DELETE"]asconst);constperms=newPermissions(["READ","WRITE"]);perms.has("READ");// trueperms.has("DELETE");// false

---

🧠 Creating a Bitfield

Simple

constPermissions=createBitfield(["READ","WRITE","DELETE"]asconst);

Advanced

constPermissionsBits={READ: 1n<<0n,WRITE: 1n<<1n,DELETE: 1n<<2n}constPermissions=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,newPermissions("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(constflagofperms){console.log(flag);}

---

🔒 Immutability

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

constfrozen=Object.freeze(newPermissions("READ"));constupdated=frozen.add("WRITE");updated.has("WRITE");// truefrozen.has("WRITE");// false

---

🔢 Raw Value

perms.bits;// bigint

---

🧩 Static Properties

Permissions.Flags.READ;// bigintPermissions.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)

---