@zakkster/lite-fastbit32 1.0.0 → 1.1.0

package/FastBit32.d.ts

@@ -84,12 +84,6 @@ export class FastBit32 {
      * Equivalent to `(value & mask) === mask`.
      *
      * @param mask - Bitmask to test against.
-     *
-     * @example
-     * ```js
-     * const PHYSICS = (1 << 1) | (1 << 4);
-     * if (entity.hasAll(PHYSICS)) { /* run physics *\/ }
-     * ```
      */
     hasAll(mask: number): boolean;
 
@@ -194,6 +188,17 @@ export class FastBit32 {
      */
     clone(): FastBit32;
 
+    // ── Iteration ───────────────────────────────────────
+
+    /**
+     * O(k) iteration over active bits, where k is the number of set bits.
+     * Visits each active bit index in ascending order.
+     *
+     * @param callback - Called with the bit index of each active bit.
+     * @returns `this` for chaining.
+     */
+    forEach(callback: (bit: number) => void): this;
+
     // ── Serialization ───────────────────────────────────
 
     /**
@@ -212,3 +217,151 @@ export class FastBit32 {
      */
     static deserialize(value: number): FastBit32;
 }
+
+/**
+ * BitMapper — The Human-to-Hardware Bridge.
+ *
+ * Translates semantic string names into 32-bit integer indices and raw masks.
+ * Protects developers from raw integer math while keeping the engine hot-path fast.
+ */
+export class BitMapper {
+    /**
+     * Creates a new BitMapper dictionary.
+     *
+     * @param names - Array of component/flag names (Maximum 32).
+     * @throws Error if more than 32 flags are provided.
+     */
+    constructor(names?: string[]);
+
+    /**
+     * Gets the raw bit index (0-31) for a specific flag name.
+     *
+     * @param name - The semantic string name of the flag.
+     * @returns The integer bit index.
+     * @throws Error if the flag name is not registered.
+     */
+    get(name: string): number;
+
+    /**
+     * Generates a raw 32-bit integer mask from an array of flag names.
+     * Ideal for building System signatures in an ECS.
+     *
+     * @param names - Array of semantic flag names to combine into a mask.
+     * @returns The generated unsigned 32-bit mask.
+     */
+    getMask(names: string[]): number;
+
+    /**
+     * Helper to extract which semantic strings are active inside a FastBit32 instance.
+     * Excellent for console.log debugging.
+     *
+     * @param fastBit32Instance - The FastBit32 instance to evaluate.
+     * @returns An array of active string names.
+     */
+    getActiveNames(fastBit32Instance: FastBit32): string[];
+
+    /**
+     * O(1) reverse lookup — integer bit index to string name.
+     *
+     * @param bit - The bit index (0–31).
+     * @returns The registered name, or `undefined` if no name is registered at that index.
+     */
+    getName(bit: number): string | undefined;
+}
+
+// ── O(k) Iteration Helpers ─────────────────────────────────
+
+/**
+ * Iterates active bits in a mask, calling back with the corresponding array element.
+ *
+ * @param mask - FastBit32 instance whose active bits select array indices.
+ * @param array - Data array indexed by bit position.
+ * @param callback - Called with `(element, bitIndex)` for each active bit.
+ */
+export function forEachArray<T>(
+    mask: FastBit32,
+    array: T[],
+    callback: (element: T, bit: number) => void
+): void;
+
+/**
+ * Iterates active bits, mapping through a keys array to object properties.
+ *
+ * @param mask - FastBit32 instance whose active bits select key indices.
+ * @param keys - Array of property keys indexed by bit position.
+ * @param obj - Object to read values from.
+ * @param callback - Called with `(value, key, bitIndex)` for each active bit.
+ */
+export function forEachObject<T>(
+    mask: FastBit32,
+    keys: string[],
+    obj: Record<string, T>,
+    callback: (value: T, key: string, bit: number) => void
+): void;
+
+/**
+ * Iterates active bits, resolving each to a string name via a BitMapper.
+ *
+ * @param mask - FastBit32 instance.
+ * @param mapper - BitMapper for reverse lookup.
+ * @param callback - Called with `(name, bitIndex)` for each active bit.
+ */
+export function forEachMapped(
+    mask: FastBit32,
+    mapper: BitMapper,
+    callback: (name: string, bit: number) => void
+): void;
+
+/**
+ * Iterates active bits, resolving names via BitMapper and reading object values.
+ *
+ * @param mask - FastBit32 instance.
+ * @param mapper - BitMapper for reverse lookup.
+ * @param obj - Object to read values from.
+ * @param callback - Called with `(value, key, bitIndex)` for each active bit.
+ */
+export function forEachMappedObject<T>(
+    mask: FastBit32,
+    mapper: BitMapper,
+    obj: Record<string, T>,
+    callback: (value: T, key: string, bit: number) => void
+): void;
+
+/**
+ * Iterates bits that are active in BOTH masks (intersection / AND).
+ *
+ * @param maskA - First FastBit32 instance.
+ * @param maskB - Second FastBit32 instance.
+ * @param callback - Called with `(bitIndex)` for each shared active bit.
+ */
+export function forEachMaskPair(
+    maskA: FastBit32,
+    maskB: FastBit32,
+    callback: (bit: number) => void
+): void;
+
+/**
+ * Iterates bits active in A but not in B (difference / A AND NOT B).
+ *
+ * @param maskA - First FastBit32 instance.
+ * @param maskB - Second FastBit32 instance.
+ * @param callback - Called with `(bitIndex)` for each bit in A not in B.
+ */
+export function forEachMaskDiff(
+    maskA: FastBit32,
+    maskB: FastBit32,
+    callback: (bit: number) => void
+): void;
+
+/**
+ * Iterates bits active in either mask (union / OR).
+ *
+ * @param maskA - First FastBit32 instance.
+ * @param maskB - Second FastBit32 instance.
+ * @param callback - Called with `(bitIndex)` for each active bit in A or B.
+ */
+export function forEachMaskUnion(
+    maskA: FastBit32,
+    maskB: FastBit32,
+    callback: (bit: number) => void
+): void;

package/Fastbit32.js

@@ -0,0 +1,257 @@
+/**
+ * FastBit32 — Zero-GC, Monomorphic 32-bit Flag Manager
+ * Engineered for 60fps hot-path execution, ECS masking, and object pooling.
+ * * ⚠️ ENGINE PRIMITIVE CAVEATS:
+ * - SILENT WRAPAROUND: JS bitwise shifts implicitly apply modulo 32.
+ * Calling `add(32)` evaluates as `add(0)`. `add(40)` evaluates as `add(8)`.
+ * - TRUNCATION: Floats and negative numbers are silently truncated and
+ * converted to unsigned 32-bit integers (e.g., `-1 >>> 0` becomes `4294967295`).
+ * Sanitize your inputs upstream if your domain logic requires strict bounds!
+ */
+export class Fastbit32 {
+    constructor(initial = 0) {
+        this.value = initial >>> 0;
+    }
+
+    add(bit) {
+        this.value |= (1 << bit);
+        return this;
+    }
+
+    remove(bit) {
+        this.value &= ~(1 << bit);
+        return this;
+    }
+
+    toggle(bit) {
+        this.value ^= (1 << bit);
+        return this;
+    }
+
+    has(bit) {
+        return (this.value & (1 << bit)) !== 0;
+    }
+
+    hasAll(mask) {
+        return (this.value & mask) === mask;
+    }
+
+    hasAny(mask) {
+        return (this.value & mask) !== 0;
+    }
+
+    hasNone(mask) {
+        return (this.value & mask) === 0;
+    }
+
+    clear() {
+        this.value = 0;
+        return this;
+    }
+
+    union(mask) {
+        this.value |= mask;
+        return this;
+    }
+
+    difference(mask) {
+        this.value &= ~mask;
+        return this;
+    }
+
+    intersect(mask) {
+        this.value &= mask;
+        return this;
+    }
+
+    // ── Advanced AAA Engine Helpers ──────────────────────────
+
+    /**
+     * O(1) loop-free popcount (Hamming Weight).
+     * Returns the number of active bits (e.g., how many flags are active).
+     */
+    count() {
+        let v = this.value;
+        v = v - ((v >>> 1) & 0x55555555);
+        v = (v & 0x33333333) + ((v >>> 2) & 0x33333333);
+        return Math.imul((v + (v >>> 4)) & 0x0F0F0F0F, 0x01010101) >>> 24;
+    }
+
+    /**
+     * O(1) loop-free popcount applying a mask first.
+     * Useful for counting active flags within a specific subsystem.
+     */
+    countMasked(mask) {
+        let v = this.value & mask;
+        v = v - ((v >>> 1) & 0x55555555);
+        v = (v & 0x33333333) + ((v >>> 2) & 0x33333333);
+        return Math.imul((v + (v >>> 4)) & 0x0F0F0F0F, 0x01010101) >>> 24;
+    }
+
+    /**
+     * Instantly finds the index of the lowest active bit.
+     * Incredibly useful for Object Pools (finding the first available slot).
+     * Returns -1 if empty.
+     */
+    lowest() {
+        if (this.value === 0) return -1;
+        // Isolate lowest set bit, then use native Count Leading Zeros to find index
+        return Math.clz32(this.value & -this.value) ^ 31;
+    }
+
+    /**
+     * Instantly finds the index of the highest active bit.
+     * Useful for determining the bounds of active arrays/spatial grids.
+     * Returns -1 if empty.
+     */
+    highest() {
+        if (this.value === 0) return -1;
+        return 31 - Math.clz32(this.value);
+    }
+
+    isEmpty() {
+        return this.value === 0;
+    }
+
+    clone() {
+        return new Fastbit32(this.value);
+    }
+
+    // ── Serialization (For ECS Save States) ──────────────────
+
+    /**
+     * Exports the raw 32-bit integer for ultra-lightweight JSON/binary storage.
+     */
+    serialize() {
+        return this.value;
+    }
+
+    /**
+     * Instantiates a new FastBit32 from a serialized integer.
+     */
+    static deserialize(value) {
+        return new Fastbit32(value);
+    }
+
+    /**
+     * O(k) loop-free iteration over active bits.
+     * @param {Function} callback - Called with (bit)
+     */
+    forEach(callback) {
+        let v = this.value;
+        while (v !== 0) {
+            const bit = Math.clz32(v & -v) ^ 31;
+            callback(bit);
+            v &= v - 1; // Clear lowest active bit
+        }
+        return this;
+    }
+}
+
+export class BitMapper {
+    constructor(names = []) {
+        if (names.length > 32) throw new Error('BitMapper: Maximum 32 flags supported.');
+
+        this._map = new Map();
+        this._reverse = new Array(32); // O(1) array lookup
+
+        names.forEach((name, index) => {
+            this._map.set(name, index);
+            this._reverse[index] = name;
+        });
+    }
+
+    get(name) {
+        const bit = this._map.get(name);
+        if (bit === undefined) throw new Error(`BitMapper: Unknown flag "${name}"`);
+        return bit;
+    }
+
+    getMask(names) {
+        let mask = 0;
+        for (let i = 0; i < names.length; i++) mask |= (1 << this.get(names[i]));
+        return mask >>> 0;
+    }
+
+    getActiveNames(fastBit32Instance) {
+        const active = [];
+        for (const [name, bit] of this._map.entries()) {
+            if (fastBit32Instance.has(bit)) active.push(name);
+        }
+        return active;
+    }
+
+    /**
+     * O(1) Reverse lookup. Integer -> String.
+     */
+    getName(bit) {
+        return this._reverse[bit];
+    }
+}
+
+// ── O(k) Iteration Helpers ─────────────────────────────────
+
+export function forEachArray(mask, array, callback) {
+    let v = mask.value;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        callback(array[bit], bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachObject(mask, keys, obj, callback) {
+    let v = mask.value;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        const key = keys[bit];
+        callback(obj[key], key, bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachMapped(mask, mapper, callback) {
+    let v = mask.value;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        callback(mapper.getName(bit), bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachMappedObject(mask, mapper, obj, callback) {
+    let v = mask.value;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        const key = mapper.getName(bit);
+        callback(obj[key], key, bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachMaskPair(maskA, maskB, callback) {
+    let v = (maskA.value & maskB.value) >>> 0;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        callback(bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachMaskDiff(maskA, maskB, callback) {
+    let v = (maskA.value & ~maskB.value) >>> 0;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        callback(bit);
+        v &= v - 1;
+    }
+}
+
+export function forEachMaskUnion(maskA, maskB, callback) {
+    let v = (maskA.value | maskB.value) >>> 0;
+    while (v !== 0) {
+        const bit = Math.clz32(v & -v) ^ 31;
+        callback(bit);
+        v &= v - 1;
+    }
+}

package/README.md

@@ -20,6 +20,8 @@ Zero-GC, monomorphic, branchless 32-bit flag manager for ECS masking, object poo
 | **Branchless**        | **Yes**        | No         | No              |
 | **O(1) popcount**     | **Yes**        | No         | No              |
 | **O(1) lowest/highest** | **Yes**      | No         | No              |
+| **O(k) iteration**    | **Yes**        | No         | No              |
+| **BitMapper**         | **Yes**        | No         | No              |
 | **BigInt support**    | No             | No         | No              |
 | **ECS-ready**         | **Yes**        | Yes        | Yes             |
 | **Object pool scan**  | **Yes**        | No         | No              |
@@ -37,7 +39,7 @@ npm install @zakkster/lite-fastbit32
 ## Quick Start
 
 ```javascript
-import { FastBit32 } from '@zakkster/lite-fastbit32';
+import { FastBit32, BitMapper } from '@zakkster/lite-fastbit32';
 
 const flags = new FastBit32();
 
@@ -47,6 +49,12 @@ flags.count();                // 2 — O(1) popcount
 flags.lowest();               // 1 — O(1) bit-scan forward
 flags.remove(1);              // Clear bit 1
 flags.serialize();            // Raw uint32 for storage
+
+// Human-readable flag management
+const mapper = new BitMapper(['Physics', 'Render', 'AI', 'Input']);
+const entity = new FastBit32();
+entity.add(mapper.get('Physics')).add(mapper.get('Input'));
+mapper.getActiveNames(entity); // ['Physics', 'Input']
 ```
 
 ---
@@ -83,6 +91,10 @@ lowest = Math.clz32(value & -value) ^ 31
 
 `highest` uses `31 - Math.clz32(value)` directly.
 
+### O(k) Iteration
+
+All iteration helpers visit only active bits using the `v &= v - 1` trick to clear the lowest bit each step. Complexity is O(k) where k is the number of set bits — not 32.
+
 ### Caveats
 
 - **Silent wraparound:** JS bitwise shifts apply modulo 32. `add(32)` evaluates as `add(0)`. `add(40)` evaluates as `add(8)`.
@@ -131,7 +143,7 @@ Tested on Apple M2 Pro, Node 22, V8 12.x. All values in **ops/ms**.
 ## Recipes
 
 <details>
-<summary><strong>🎮 ECS Component Masks</strong></summary>
+<summary><strong>ECS Component Masks</strong></summary>
 
 ```javascript
 import { FastBit32 } from '@zakkster/lite-fastbit32';
@@ -152,32 +164,23 @@ if (entity.hasAll(PHYSICS_QUERY)) runPhysics(entity);
 if (entity.hasAll(RENDER_QUERY))  drawSprite(entity);
 ```
 
-> **⚠️ Bit 31 (Sign Bit) Warning:** In JavaScript, `1 << 31` evaluates to `-2147483648` — a negative number. FastBit32 handles this correctly under the hood, but if you log raw mask values to the console, you will see negative integers and assume a bug. This also affects `serialize()`: masks using bit 31 produce negative numbers in JSON. **Recommendation:** Keep ECS component indices to 0–30 (31 components). If you must use all 32, compare serialized values with `>>> 0` to force unsigned representation.
+> **Bit 31 (Sign Bit) Warning:** In JavaScript, `1 << 31` evaluates to `-2147483648` — a negative number. FastBit32 handles this correctly under the hood, but if you log raw mask values to the console, you will see negative integers and assume a bug. This also affects `serialize()`: masks using bit 31 produce negative numbers in JSON. **Recommendation:** Keep ECS component indices to 0–30 (31 components). If you must use all 32, compare serialized values with `>>> 0` to force unsigned representation.
 
 </details>
 
 <details>
-<summary><strong>🏊 Object Pool — First Free Slot</strong></summary>
+<summary><strong>Object Pool — First Free Slot</strong></summary>
 
 ```javascript
 import { FastBit32 } from '@zakkster/lite-fastbit32';
 
-// Bit = 1 means slot is occupied
 const pool = new FastBit32();
 const objects = new Array(32);
 
 function allocate() {
-    // Invert to find free slots, mask to pool size
     const free = new FastBit32(~pool.value & 0xFFFFFFFF);
     const slot = free.lowest();
-
-    // ⚠️ CRITICAL: Always check for -1.
-    // If the pool is full, lowest() returns -1.
-    // Accessing objects[-1] bypasses V8's array bounds optimization,
-    // triggering a dictionary-mode fallback on the entire array —
-    // a massive de-optimization penalty that persists for the array's lifetime.
-    if (slot === -1) return null; // Pool exhausted — expand or drop
-
+    if (slot === -1) return null;
     pool.add(slot);
     return slot;
 }
@@ -195,7 +198,7 @@ allocate(); // 0 — immediately reused
 </details>
 
 <details>
-<summary><strong>🎹 Input State Manager</strong></summary>
+<summary><strong>Input State Manager</strong></summary>
 
 ```javascript
 import { FastBit32 } from '@zakkster/lite-fastbit32';
@@ -219,7 +222,6 @@ window.addEventListener('keyup', e => {
     if (e.code === 'Space')      input.remove(KEY_JUMP);
 });
 
-// In game loop — zero-branch checks
 if (input.has(KEY_JUMP)) jump();
 if (input.hasAny((1 << KEY_LEFT) | (1 << KEY_RIGHT))) move();
 ```
@@ -227,56 +229,7 @@ if (input.hasAny((1 << KEY_LEFT) | (1 << KEY_RIGHT))) move();
 </details>
 
 <details>
-<summary><strong>💥 Collision Layer Masks</strong></summary>
-
-```javascript
-import { FastBit32 } from '@zakkster/lite-fastbit32';
-
-const LAYER_PLAYER    = 0;
-const LAYER_ENEMY     = 1;
-const LAYER_BULLET    = 2;
-const LAYER_WALL      = 3;
-const LAYER_PICKUP    = 4;
-
-const playerMask = new FastBit32();
-playerMask.add(LAYER_ENEMY).add(LAYER_PICKUP).add(LAYER_WALL);
-
-const bulletMask = new FastBit32();
-bulletMask.add(LAYER_ENEMY).add(LAYER_WALL);
-
-function canCollide(entityLayer, targetMask) {
-    return targetMask.has(entityLayer);
-}
-```
-
-</details>
-
-<details>
-<summary><strong>🌐 Networking Flags</strong></summary>
-
-```javascript
-import { FastBit32 } from '@zakkster/lite-fastbit32';
-
-const FLAG_RELIABLE   = 0;
-const FLAG_ORDERED    = 1;
-const FLAG_COMPRESSED = 2;
-const FLAG_ENCRYPTED  = 3;
-
-const packet = new FastBit32();
-packet.add(FLAG_RELIABLE).add(FLAG_ENCRYPTED);
-
-const raw = packet.serialize();  // Send as uint32
-// ... network transport ...
-const restored = FastBit32.deserialize(raw);
-if (restored.has(FLAG_RELIABLE)) ack(packet);
-```
-
-</details>
-
-<details>
-<summary><strong>🧠 State Machine — Mutex Flags</strong></summary>
-
-In a strict FSM, only one state should be active at any time. Never use `remove(OLD).add(NEW)` — if the remove and add target the same bit index by mistake, you silently corrupt the state. Use `.clear().add()` to guarantee zero overlapping bits.
+<summary><strong>State Machine — Mutex Flags</strong></summary>
 
 ```javascript
 import { FastBit32 } from '@zakkster/lite-fastbit32';
@@ -290,39 +243,60 @@ const INVINCIBLE = 4;
 const state = new FastBit32();
 state.add(IDLE);
 
-// ✅ CORRECT — mutex transition: clear ALL bits, then set the new state.
-// Guarantees zero overlap regardless of previous state.
 function startAttack() {
     state.clear().add(ATTACKING).add(INVINCIBLE);
 }
 
-// ✅ CORRECT — return to single state after compound state ends.
 function endAttack() {
     state.clear().add(IDLE);
 }
 
-// ❌ WRONG — remove/add leaves stale bits if you forget one:
-// state.remove(ATTACKING).remove(INVINCIBLE).add(IDLE);
-// If INVINCIBLE was already cleared by another system, this still "works"
-// but masks a logic error. clear() is unconditional and safe.
-
 console.log(state.count()); // 1 — proof of mutex
 ```
 
 </details>
 
 <details>
-<summary><strong>💾 ECS Save State</strong></summary>
+<summary><strong>BitMapper + Iteration (v1.1.0)</strong></summary>
 
 ```javascript
-import { FastBit32 } from '@zakkster/lite-fastbit32';
+import { FastBit32, BitMapper, forEachMapped, forEachMappedObject } from '@zakkster/lite-fastbit32';
 
-// Save
-const entities = [entityA.serialize(), entityB.serialize()];
-const json = JSON.stringify(entities); // "[18, 7]" — bytes, not objects
+const components = new BitMapper(['Position', 'Velocity', 'Sprite', 'AI']);
+const entity = new FastBit32();
+entity.add(components.get('Position')).add(components.get('AI'));
+
+console.log(components.getActiveNames(entity)); // ['Position', 'AI']
 
-// Load
-const restored = JSON.parse(json).map(FastBit32.deserialize);
+forEachMapped(entity, components, (name, bit) => {
+    console.log(`Component ${name} at bit ${bit}`);
+});
+
+const systems = { Position: updatePos, Velocity: updateVel, Sprite: draw, AI: think };
+forEachMappedObject(entity, components, systems, (system, name) => {
+    system(entity);
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Mask Set Operations (v1.1.0)</strong></summary>
+
+```javascript
+import { FastBit32, forEachMaskPair, forEachMaskDiff, forEachMaskUnion } from '@zakkster/lite-fastbit32';
+
+const required = new FastBit32().add(0).add(1).add(3);
+const available = new FastBit32().add(0).add(3).add(5);
+
+forEachMaskPair(required, available, bit => console.log('matched:', bit));
+// matched: 0, matched: 3
+
+forEachMaskDiff(required, available, bit => console.log('missing:', bit));
+// missing: 1
+
+forEachMaskUnion(required, available, bit => console.log('all:', bit));
+// all: 0, all: 1, all: 3, all: 5
 ```
 
 </details>
@@ -373,6 +347,12 @@ const restored = JSON.parse(json).map(FastBit32.deserialize);
 | `.highest()` | `number` | O(1) index of most significant active bit. `-1` if empty. |
 | `.isEmpty()` | `boolean` | True if value is `0`. |
 
+### Iteration
+
+| Method | Returns | Description |
+|---|---|---|
+| `.forEach(callback)` | `this` | O(k) iteration over active bits. `callback(bit)`. |
+
 ### Utility
 
 | Method | Returns | Description |
@@ -381,6 +361,43 @@ const restored = JSON.parse(json).map(FastBit32.deserialize);
 | `.serialize()` | `number` | Export raw uint32 for JSON/binary storage. |
 | `FastBit32.deserialize(n)` | `FastBit32` | Restore from a serialized uint32. |
 
+### `new BitMapper(names?)`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.get(name)` | `number` | Bit index for a flag name. Throws if unknown. |
+| `.getMask(names)` | `number` | Combined uint32 mask from flag name array. |
+| `.getActiveNames(fb32)` | `string[]` | Active flag names from a FastBit32 instance. |
+| `.getName(bit)` | `string \| undefined` | O(1) reverse lookup — bit index to name. |
+
+### Standalone Iteration Helpers
+
+| Function | Description |
+|---|---|
+| `forEachArray(mask, array, cb)` | `cb(element, bit)` for each active bit. |
+| `forEachObject(mask, keys, obj, cb)` | `cb(value, key, bit)` via keys array. |
+| `forEachMapped(mask, mapper, cb)` | `cb(name, bit)` via BitMapper. |
+| `forEachMappedObject(mask, mapper, obj, cb)` | `cb(value, key, bit)` via BitMapper + object. |
+| `forEachMaskPair(maskA, maskB, cb)` | `cb(bit)` for intersection (A & B). |
+| `forEachMaskDiff(maskA, maskB, cb)` | `cb(bit)` for difference (A & ~B). |
+| `forEachMaskUnion(maskA, maskB, cb)` | `cb(bit)` for union (A \| B). |
+
+---
+
+## Changelog
+
+### v1.1.0
+
+**New: BitMapper** — Human-to-hardware bridge. Maps semantic string names to bit indices and masks, with O(1) reverse lookup via `getName(bit)`.
+
+**New: `forEach(callback)`** — O(k) iteration on FastBit32 instances. Visits only active bits in ascending order using `v &= v - 1` bit-clearing. Returns `this` for chaining.
+
+**New: 7 standalone iteration helpers** — `forEachArray`, `forEachObject`, `forEachMapped`, `forEachMappedObject`, `forEachMaskPair`, `forEachMaskDiff`, `forEachMaskUnion`. All O(k). Connect masks directly to arrays, objects, BitMapper dictionaries, and mask set operations without intermediate allocations.
+
+### v1.0.0
+
+Initial release. FastBit32 core: single-bit ops, bulk mask ops, in-place set math, O(1) popcount, O(1) bit-scan (lowest/highest), clone, serialize/deserialize.
+
 ---
 
 ## License
@@ -389,4 +406,4 @@ MIT
 
 ## Part of the @zakkster ecosystem
 
-Zero-GC, deterministic, tree-shakeable micro-libraries for high-performance web applications.
+Zero-GC, deterministic, tree-shakeable micro-libraries for high-performance web applications.

package/llms.txt

@@ -1,4 +1,4 @@
-# @zakkster/lite-fastbit32 v1.0.0
+# @zakkster/lite-fastbit32 v1.1.0
 
 > Zero-GC, monomorphic, branchless 32-bit flag manager for ECS masking, object pools, and 60fps hot-path engine code.
 
@@ -13,7 +13,13 @@ FastBit32 is a single-class library that wraps a plain unsigned 32-bit integer w
 ## Import
 
 ```javascript
-import { FastBit32 } from '@zakkster/lite-fastbit32';
+import { FastBit32, BitMapper } from '@zakkster/lite-fastbit32';
+
+// Standalone iteration helpers
+import {
+    forEachArray, forEachObject, forEachMapped,
+    forEachMappedObject, forEachMaskPair, forEachMaskDiff, forEachMaskUnion
+} from '@zakkster/lite-fastbit32';
 ```
 
 ## Constructor
@@ -67,6 +73,12 @@ All mutating methods return `this` for chaining unless noted otherwise.
 | `.highest()` | `number` | Index of most significant set bit (0–31). Returns `-1` if empty. |
 | `.isEmpty()` | `boolean` | True if value is 0. |
 
+### Iteration
+
+| Method | Returns | Description |
+|---|---|---|
+| `.forEach(callback)` | `this` | O(k) iteration over active bits in ascending order. Callback receives `(bit)`. |
+
 ### Utility
 
 | Method | Returns | Description |
@@ -81,6 +93,70 @@ All mutating methods return `this` for chaining unless noted otherwise.
 |---|---|---|
 | `.value` | `number` | The raw 32-bit integer. Safe to read directly in hot paths. |
 
+## BitMapper — Human-to-Hardware Bridge
+
+Translates semantic string names into bit indices and masks. Keeps engine hot paths fast while letting developers think in words.
+
+```javascript
+const mapper = new BitMapper(['Position', 'Velocity', 'Health', 'Magic']);
+```
+
+### Constructor
+
+```javascript
+new BitMapper(names?: string[])
+```
+
+- `names` — Array of up to 32 flag names. Each name maps to its array index (0–31).
+- Throws if more than 32 names are provided.
+
+### BitMapper Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `.get(name)` | `number` | Bit index (0–31) for a flag name. Throws if unknown. |
+| `.getMask(names)` | `number` | Combined uint32 mask from an array of flag names. |
+| `.getActiveNames(fb32)` | `string[]` | Array of active flag names from a FastBit32 instance. |
+| `.getName(bit)` | `string \| undefined` | O(1) reverse lookup — bit index to string name. |
+
+### BitMapper Example
+
+```javascript
+const mapper = new BitMapper(['Physics', 'Render', 'AI', 'Input']);
+const entity = new FastBit32();
+entity.add(mapper.get('Physics')).add(mapper.get('Input'));
+
+mapper.getActiveNames(entity); // ['Physics', 'Input']
+
+const PHYSICS_QUERY = mapper.getMask(['Physics', 'Render']);
+entity.hasAll(PHYSICS_QUERY); // false — missing Render
+```
+
+## Standalone Iteration Helpers
+
+All helpers are O(k) where k = number of active bits. No loops over 32 slots — only active bits are visited.
+
+| Function | Signature | Description |
+|---|---|---|
+| `forEachArray` | `(mask, array, cb)` | Active bits → array indices. `cb(element, bit)` |
+| `forEachObject` | `(mask, keys, obj, cb)` | Active bits → keys array → object values. `cb(value, key, bit)` |
+| `forEachMapped` | `(mask, mapper, cb)` | Active bits → BitMapper names. `cb(name, bit)` |
+| `forEachMappedObject` | `(mask, mapper, obj, cb)` | Active bits → BitMapper names → object values. `cb(value, key, bit)` |
+| `forEachMaskPair` | `(maskA, maskB, cb)` | Intersection (A & B). `cb(bit)` |
+| `forEachMaskDiff` | `(maskA, maskB, cb)` | Difference (A & ~B). `cb(bit)` |
+| `forEachMaskUnion` | `(maskA, maskB, cb)` | Union (A \| B). `cb(bit)` |
+
+### Iteration Example
+
+```javascript
+const mapper = new BitMapper(['Idle', 'Run', 'Jump', 'Attack']);
+const mask = new FastBit32().add(1).add(3); // Run + Attack
+
+forEachMapped(mask, mapper, (name, bit) => {
+    console.log(name); // 'Run', then 'Attack'
+});
+```
+
 ## Critical Caveats
 
 1. **Silent modulo-32 wraparound.** JavaScript bitwise shifts apply `% 32` implicitly. `add(32)` is identical to `add(0)`. `add(40)` is identical to `add(8)`. There is no bounds checking.
@@ -162,6 +238,23 @@ function startAttack() {
 }
 ```
 
+### ECS with BitMapper and Iteration
+
+```javascript
+const components = new BitMapper(['Position', 'Velocity', 'Sprite', 'AI']);
+const entity = new FastBit32();
+entity.add(components.get('Position')).add(components.get('AI'));
+
+// Debug: see what's active
+console.log(components.getActiveNames(entity)); // ['Position', 'AI']
+
+// Iterate only active components
+const systems = { Position: updatePos, Velocity: updateVel, Sprite: draw, AI: think };
+forEachMappedObject(entity, components, systems, (system, name, bit) => {
+    system(entity); // Only calls updatePos and think
+});
+```
+
 ### Serialization Round-Trip
 
 ```javascript
@@ -213,5 +306,6 @@ flags.has(10); // false — clone is independent
 - All single-bit operations: one bitwise instruction, zero branches.
 - `count()`: 5 bitwise operations (Hacker's Delight parallel popcount), zero loops.
 - `lowest()` / `highest()`: 1–2 operations using `Math.clz32`, zero loops.
+- `forEach` and all standalone helpers: O(k) where k = active bits, not 32.
 - All methods except `clone()` and `deserialize()`: zero allocations.
-- V8 monomorphic: single hidden class for the lifetime of the object.
+- V8 monomorphic: single hidden class for the lifetime of the object.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@zakkster/lite-fastbit32",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-GC, monomorphic 32-bit flag manager and ECS masking primitive for high-performance game loops.",
   "type": "module",
   "sideEffects": false,
-  "main": "FastBit32.js",
+  "main": "Fastbit32.js",
   "types": "FastBit32.d.ts",
   "exports": {
     ".": {
@@ -15,7 +15,7 @@
     }
   },
   "files": [
-    "FastBit32.js",
+    "Fastbit32.js",
     "FastBit32.d.ts",
     "llms.txt",
     "README.md"
@@ -33,6 +33,7 @@
   "keywords": [
     "bitflags",
     "bitmask",
+    "bitmap",
     "bitwise",
     "state-machine",
     "ecs",

package/FastBit32.js

@@ -1,134 +0,0 @@
-/**
- * FastBit32 — Zero-GC, Monomorphic 32-bit Flag Manager
- * Engineered for 60fps hot-path execution, ECS masking, and object pooling.
- * * ⚠️ ENGINE PRIMITIVE CAVEATS:
- * - SILENT WRAPAROUND: JS bitwise shifts implicitly apply modulo 32. 
- * Calling `add(32)` evaluates as `add(0)`. `add(40)` evaluates as `add(8)`.
- * - TRUNCATION: Floats and negative numbers are silently truncated and 
- * converted to unsigned 32-bit integers (e.g., `-1 >>> 0` becomes `4294967295`).
- * Sanitize your inputs upstream if your domain logic requires strict bounds!
- */
-export class FastBit32 {
-    constructor(initial = 0) {
-        // Enforce unsigned 32-bit integer immediately for V8 inline caching
-        this.value = initial >>> 0;
-    }
-
-    // ── Single Bit Ops (Zero-Branching) ──────────────────────
-
-    add(bit) {
-        this.value |= (1 << bit);
-        return this;
-    }
-
-    remove(bit) {
-        this.value &= ~(1 << bit);
-        return this;
-    }
-
-    toggle(bit) {
-        this.value ^= (1 << bit);
-        return this;
-    }
-
-    has(bit) {
-        return (this.value & (1 << bit)) !== 0;
-    }
-
-    // ── Bulk Mask Ops ────────────────────────────────────────
-
-    hasAll(mask)  { return (this.value & mask) === mask; }
-    hasAny(mask)  { return (this.value & mask) !== 0; }
-    hasNone(mask) { return (this.value & mask) === 0; }
-
-    // ── In-Place Mutations (Zero-GC Set Math) ────────────────
-
-    clear() {
-        this.value = 0;
-        return this;
-    }
-
-    union(mask) {
-        this.value |= mask;
-        return this;
-    }
-
-    difference(mask) {
-        this.value &= ~mask;
-        return this;
-    }
-
-    intersect(mask) {
-        this.value &= mask;
-        return this;
-    }
-
-    // ── Advanced AAA Engine Helpers ──────────────────────────
-
-    /**
-     * O(1) loop-free popcount (Hamming Weight).
-     * Returns the number of active bits (e.g., how many flags are active).
-     */
-    count() {
-        let v = this.value;
-        v = v - ((v >>> 1) & 0x55555555);
-        v = (v & 0x33333333) + ((v >>> 2) & 0x33333333);
-        return Math.imul((v + (v >>> 4)) & 0x0F0F0F0F, 0x01010101) >>> 24;
-    }
-
-    /**
-     * O(1) loop-free popcount applying a mask first.
-     * Useful for counting active flags within a specific subsystem.
-     */
-    countMasked(mask) {
-        let v = this.value & mask;
-        v = v - ((v >>> 1) & 0x55555555);
-        v = (v & 0x33333333) + ((v >>> 2) & 0x33333333);
-        return Math.imul((v + (v >>> 4)) & 0x0F0F0F0F, 0x01010101) >>> 24;
-    }
-
-    /**
-     * Instantly finds the index of the lowest active bit.
-     * Incredibly useful for Object Pools (finding the first available slot).
-     * Returns -1 if empty.
-     */
-    lowest() {
-        if (this.value === 0) return -1;
-        // Isolate lowest set bit, then use native Count Leading Zeros to find index
-        return Math.clz32(this.value & -this.value) ^ 31;
-    }
-
-    /**
-     * Instantly finds the index of the highest active bit.
-     * Useful for determining the bounds of active arrays/spatial grids.
-     * Returns -1 if empty.
-     */
-    highest() {
-        if (this.value === 0) return -1;
-        return 31 - Math.clz32(this.value);
-    }
-
-    isEmpty() {
-        return this.value === 0;
-    }
-
-    clone() {
-        return new FastBit32(this.value);
-    }
-
-    // ── Serialization (For ECS Save States) ──────────────────
-
-    /**
-     * Exports the raw 32-bit integer for ultra-lightweight JSON/binary storage.
-     */
-    serialize() {
-        return this.value;
-    }
-
-    /**
-     * Instantiates a new FastBit32 from a serialized integer.
-     */
-    static deserialize(value) {
-        return new FastBit32(value);
-    }
-}