{"_id":"@eliyya/flagged-bitfield","_rev":"3-718a8f944aecb1d0e38ad3ec829687a2","name":"@eliyya/flagged-bitfield","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@eliyya/flagged-bitfield","version":"1.0.0","keywords":["bitfield","flags","named-flags","flagged-bitfield","typescript","bigint","bitmask","binary-flags","mask","utility","data-structure"],"author":{"url":"https://github.com/eliyya","name":"eliyya","email":"elimacmun@gmail.com"},"license":"MIT","_id":"@eliyya/flagged-bitfield@1.0.0","maintainers":[{"name":"eliyya","email":"elimacmun@gmail.com"}],"homepage":"https://github.com/eliyya/flagged-bitfield#readme","bugs":{"url":"https://github.com/eliyya/flagged-bitfield/issues","email":"elimacmun@gmail.com"},"dist":{"shasum":"256ff8e3e5f43117364dc387481af275f1af188f","tarball":"https://registry.npmjs.org/@eliyya/flagged-bitfield/-/flagged-bitfield-1.0.0.tgz","fileCount":6,"integrity":"sha512-KP8xe3YB2bDkaWf08Vv1yGRN+tvTylWMIOBLtRW03vQOMpAIA28dTyecQgfZLt6zO1hVEj+b2Gg0JujThFPxQg==","signatures":[{"sig":"MEQCIDz0AFtgvfKwMASpF0wYjAX53+sOtb113XGqVZ9rLFtTAiBxewmbrezUFW/8MPMnC+H2GDxLbViHseR3AAM4GYLjhw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27412},"main":"lib/mod.js","type":"module","types":"lib/mod.d.ts","gitHead":"504e73f32b7aab6c0db31dbca0f8e22ce1ad94e6","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && terser lib/mod.js -o lib/mod.js"},"_npmUser":{"name":"eliyya","email":"elimacmun@gmail.com"},"repository":{"url":"git+https://github.com/eliyya/flagged-bitfield.git","type":"git"},"_npmVersion":"10.9.3","description":"Type-safe flagged bitfield utility for TypeScript/JavaScript","directories":{},"_nodeVersion":"22.19.0","_hasShrinkwrap":false,"devDependencies":{"eslint":"9.35.0","terser":"5.44.0","prettier":"3.6.2","@eslint/js":"9.35.0","typescript":"5.9.2","@types/node":"24.3.3","typescript-eslint":"8.43.0","eslint-plugin-node":"11.1.0","eslint-config-prettier":"10.1.8","eslint-plugin-prettier":"5.5.4","eslint-plugin-security":"3.0.1","@typescript-eslint/parser":"8.43.0","@typescript-eslint/eslint-plugin":"8.43.0"},"_npmOperationalInternal":{"tmp":"tmp/flagged-bitfield_1.0.0_1758067112229_0.7424924221865272","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@eliyya/flagged-bitfield","version":"1.1.0","keywords":["bitfield","flags","named-flags","flagged-bitfield","typescript","bigint","bitmask","binary-flags","mask","utility","data-structure"],"author":{"url":"https://github.com/eliyya","name":"eliyya","email":"elimacmun@gmail.com"},"license":"MIT","_id":"@eliyya/flagged-bitfield@1.1.0","maintainers":[{"name":"eliyya","email":"elimacmun@gmail.com"}],"homepage":"https://github.com/eliyya/flagged-bitfield#readme","bugs":{"url":"https://github.com/eliyya/flagged-bitfield/issues","email":"elimacmun@gmail.com"},"dist":{"shasum":"7cf0ca965c66ef57cb46b08075a1256a713316f3","tarball":"https://registry.npmjs.org/@eliyya/flagged-bitfield/-/flagged-bitfield-1.1.0.tgz","fileCount":6,"integrity":"sha512-VdHGSayX2pJTl1GweiZuQWPWLo96C4vPn2oLClPEb0FOWyFKVovYhYo2I4fIQVADVRpIGDx4HO68p8U8QIO09A==","signatures":[{"sig":"MEQCIDvPikq7Cgx618Y8dBMAV0QWRMEt2kDRCC/RLIP/yFeFAiBUuR6EkIWenWEX6W5vdJLME2HWi1XeZy6hoOJpG0dZzg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27513},"main":"lib/mod.js","type":"module","types":"lib/mod.d.ts","gitHead":"504e73f32b7aab6c0db31dbca0f8e22ce1ad94e6","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && terser lib/mod.js -o lib/mod.js"},"_npmUser":{"name":"eliyya","email":"elimacmun@gmail.com"},"repository":{"url":"git+https://github.com/eliyya/flagged-bitfield.git","type":"git"},"_npmVersion":"10.9.3","description":"Type-safe flagged bitfield utility for TypeScript/JavaScript","directories":{},"_nodeVersion":"22.19.0","_hasShrinkwrap":false,"devDependencies":{"eslint":"9.35.0","terser":"5.44.0","prettier":"3.6.2","@eslint/js":"9.35.0","typescript":"5.9.2","@types/node":"24.3.3","typescript-eslint":"8.43.0","eslint-plugin-node":"11.1.0","eslint-config-prettier":"10.1.8","eslint-plugin-prettier":"5.5.4","eslint-plugin-security":"3.0.1","@typescript-eslint/parser":"8.43.0","@typescript-eslint/eslint-plugin":"8.43.0"},"_npmOperationalInternal":{"tmp":"tmp/flagged-bitfield_1.1.0_1758068816954_0.17397922181437764","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@eliyya/flagged-bitfield","version":"1.1.1","description":"Type-safe flagged bitfield utility for TypeScript/JavaScript","main":"lib/mod.js","type":"module","types":"lib/mod.d.ts","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && terser lib/mod.js -o lib/mod.js"},"devDependencies":{"@eslint/js":"9.35.0","@types/node":"24.3.3","@typescript-eslint/eslint-plugin":"8.43.0","@typescript-eslint/parser":"8.43.0","eslint":"9.35.0","eslint-config-prettier":"10.1.8","eslint-plugin-node":"11.1.0","eslint-plugin-prettier":"5.5.4","eslint-plugin-security":"3.0.1","prettier":"3.6.2","terser":"5.44.0","typescript":"5.9.2","typescript-eslint":"8.43.0"},"keywords":["bitfield","flags","named-flags","flagged-bitfield","typescript","bigint","bitmask","binary-flags","mask","utility","data-structure"],"author":{"name":"eliyya","email":"elimacmun@gmail.com","url":"https://github.com/eliyya"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/eliyya/flagged-bitfield.git"},"bugs":{"url":"https://github.com/eliyya/flagged-bitfield/issues","email":"elimacmun@gmail.com"},"homepage":"https://github.com/eliyya/flagged-bitfield#readme","_id":"@eliyya/flagged-bitfield@1.1.1","gitHead":"d3b33495296c500981874432c5c6780ec5785fce","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-E7oOtJGwGiCn2y5Zc87eLFXFV8B21/PrWlroD2KYPDu3d3qR4tKCTFyhYXKJqr9D2q4FbYpC4OtBdvkvvtCO/Q==","shasum":"2f467bbc51ce46b76bba80d69e81e42d5afbf872","tarball":"https://registry.npmjs.org/@eliyya/flagged-bitfield/-/flagged-bitfield-1.1.1.tgz","fileCount":6,"unpackedSize":27919,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCra98aFM2v3tKPUTFoQ8c18CuMB6EZ+il/3rrf/0JNqgIgbFsUqcQvBUiw5QmZJoD/wMAPakMIzv1a/oCqojUEsDM="}]},"_npmUser":{"name":"eliyya","email":"elimacmun@gmail.com"},"directories":{},"maintainers":[{"name":"eliyya","email":"elimacmun@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/flagged-bitfield_1.1.1_1758341697256_0.14929913274101203"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-16T23:58:32.175Z","modified":"2025-09-20T04:14:57.626Z","1.0.0":"2025-09-16T23:58:32.409Z","1.1.0":"2025-09-17T00:26:57.147Z","1.1.1":"2025-09-20T04:14:57.437Z"},"bugs":{"url":"https://github.com/eliyya/flagged-bitfield/issues","email":"elimacmun@gmail.com"},"author":{"name":"eliyya","email":"elimacmun@gmail.com","url":"https://github.com/eliyya"},"license":"MIT","homepage":"https://github.com/eliyya/flagged-bitfield#readme","keywords":["bitfield","flags","named-flags","flagged-bitfield","typescript","bigint","bitmask","binary-flags","mask","utility","data-structure"],"repository":{"type":"git","url":"git+https://github.com/eliyya/flagged-bitfield.git"},"description":"Type-safe flagged bitfield utility for TypeScript/JavaScript","maintainers":[{"name":"eliyya","email":"elimacmun@gmail.com"}],"readme":"# flagged-bitfield\n\nType-safe flagged bitfield utility for TypeScript/JavaScript using bigint under the hood. Provides a clean API for combining, testing, and transforming named flags with excellent IntelliSense support via TSDoc.\n\n- Tiny, dependency-free\n- Type-safe flag names via generics\n- Mutable and immutable-style operations\n- Mask-aware and bigint-based for large flag sets\n\n## Installation\n\n```bash\nnpm install @eliyya/flagged-bitfield\n```\n\n## Quick start\n\n```ts\nimport { FlaggedBitfield } from '@eliyya/flagged-bitfield'\n\n// 1) Define your flags by extending the class\nclass Permissions extends FlaggedBitfield<typeof Permissions.Flags> {\n    static Flags = {\n        Read: 1n << 0n,\n        Write: 1n << 1n,\n        Execute: 1n << 2n,\n        Admin: 1n << 3n,\n    } as const\n}\n\n// 2) Create instances\nconst p = new Permissions(['Read', 'Write'])\n\n// 3) Test and manipulate\np.has('Read') // true\np.has('Execute') // false\n\n// Mutating operations\np.add('Execute')\np.remove('Write')\np.invert() // invert bits within the mask\n\n// Immutable-style operations (return a new instance)\nconst q = p.with('Admin').without('Read')\n\n// Interop\nq.toArray() // => ['Admin', 'Execute'] (order by bit value)\nq.toObject() // => { Read: false, Write: false, Execute: true, Admin: true }\nq.toString(2) // => binary string of the bigint\nq.toNumber() // => numeric representation (may truncate for huge values)\n```\n\n## API overview\n\nThe class exposes both mutating and non-mutating methods. All operations respect the mask derived from your `Flags` definition.\n\n- Mutable methods\n    - `add(bit)`\n    - `remove(bit)`\n    - `invert()`\n    - `freeze()` (turns the instance into a read-only, no-op for mutations)\n\n- Immutable methods (return a new instance)\n    - `with(bit)`\n    - `without(bit)`\n    - `missing()` (complement within the mask)\n    - `union(bit)` (alias of `with`)\n    - `intersection(bit)`\n    - `difference(bit)`\n    - `symmetricDifference(bit)`\n    - `complement()`\n\n- Queries and utilities\n    - `has(bit)` — any overlap\n    - `equals(bit)` — exact equality\n    - `any(bit)` — intersection != 0n\n    - `getFlags()` — returns the flags definition\n    - `isFrozen()`\n    - `toArray()`\n    - `toObject()`\n    - `toJSON()`\n    - `toString(radix?)`\n    - `toNumber()`\n    - Iteration support: `[Symbol.iterator]()` yields present flags in ascending bit order\n    - Helpers: `find`, `findIndex`, `forEach`, `map`, `entries`, `keys`, `values`\n\n### Accepted bit inputs\n\nMost methods accept any of the following as a bit input:\n\n- A single flag key (e.g., `'Read'`)\n- A numeric `number` or `bigint` value\n- An array of the above\n- Another `FlaggedBitfield` instance\n\n## Advanced usage\n\n### Freezing instances\n\n```ts\nconst frozen = p.freeze()\nfrozen.add('Admin') // no-op, still frozen\nfrozen.isFrozen() // true\n```\n\n### Custom default bit\n\n```ts\nclass Defaults extends FlaggedBitfield<typeof Defaults.Flags> {\n    static Flags = { A: 1n, B: 2n, C: 4n } as const\n    static DefaultBit = 1n // Start with flag A enabled\n}\n\nconst d = new Defaults() // bitfield starts at 1n\n```\n\n### Working with raw numbers/bigints, strings, arrays and other FlaggedBitfield instances\n\n```ts\nnew Permissions(0b001 | 0b100) // Read + Execute\nnew Permissions(5) // Read + Execute\nnew Permissions(5n) // Read + Execute\nnew Permissions('5') // Read + Execute\nnew Permissions(['Read', 'Execute']) // Read + Execute\nnew Permissions(Permissions.Flags.Read | Permissions.Flags.Execute) // Read + Execute\nnew Permissions([Permissions.Flags.Read, Permissions.Flags.Execute]) // Read + Execute\nnew Permissions(new Permissions(['Read', 'Execute'])) // same as above\n```\n\n### Combining sets\n\n```ts\nconst a = new Permissions(['Read'])\nconst b = new Permissions(['Write'])\n\nconst union = a.union(b) // Read | Write\nconst inter = union.intersection(a) // Read\nconst diff = union.difference(a) // Write\nconst symDiff = a.symmetricDifference(b) // Read ^ Write\n```\n\n## TypeScript notes\n\n- All bits are normalized to `bigint` internally.\n- The mask is computed from your `Flags` object: `Object.values(Flags)` OR-reduced.\n- Ordering for iteration and derived arrays is ascending by bit value.\n\n## Contributing\n\nIssues and PRs are welcome! Please open an issue first to discuss major changes.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}