@zakkster/lite-fastbit32 1.1.3 → 1.2.0

package/FastBit32.d.ts

@@ -199,6 +199,74 @@ export class FastBit32 {
      */
     forEach(callback: (bit: number) => void): this;
 
+    // ── v1.2.0 AAA Engine Primitives ─────────────────────
+
+    /**
+     * Returns the index of the lowest INACTIVE (0) bit.
+     * O(1) via `Math.clz32` on the inverted mask — no loops, no scratch
+     * `FastBit32` allocation. Ideal for object pools: instantly finds the
+     * first free slot.
+     *
+     * @returns Bit index (0–31), or `-1` if all 32 bits are active.
+     */
+    nextClearBit(): number;
+
+    /**
+     * Returns the index of the highest INACTIVE (0) bit.
+     * O(1) via `Math.clz32` on the inverted mask.
+     *
+     * @returns Bit index (0–31), or `-1` if all 32 bits are active.
+     */
+    highestClearBit(): number;
+
+    /**
+     * Tests whether all 32 bits are active.
+     *
+     * @returns `true` if the value has every bit set.
+     */
+    isFull(): boolean;
+
+    /**
+     * Returns the number of active bits within an inclusive range
+     * `[start, end]`. Caller must guarantee `0 <= start <= end <= 31`.
+     *
+     * @param start - Lowest bit of the range (inclusive).
+     * @param end - Highest bit of the range (inclusive).
+     * @returns Active bit count within the range (0–32).
+     */
+    countRange(start: number, end: number): number;
+
+    // ── Debug & Init Helpers (allocate — NOT hot-path safe) ──
+
+    /**
+     * Returns a 32-character binary string of the raw value, LSB on the right.
+     * Forces unsigned representation so bit 31 prints as `1`, not a minus sign.
+     *
+     * ⚠️ Allocates a String. Debug use only.
+     *
+     * @param padded - Pad to 32 chars with leading zeros. Defaults to `true`.
+     */
+    toBinaryString(padded?: boolean): string;
+
+    /**
+     * Returns an array of active bit indexes in ascending order.
+     *
+     * ⚠️ Allocates an Array. Not safe for hot loops.
+     *
+     * @returns Array of bit indexes (0–31).
+     */
+    toArray(): number[];
+
+    /**
+     * Replaces the current value with a bitmask built from an array of bit
+     * indexes. Overwrites — does NOT OR into the existing value. Intended
+     * for initialization and deserialization, not hot paths.
+     *
+     * @param bits - Array of bit indexes (0–31).
+     * @returns `this` for chaining.
+     */
+    fromArray(bits: number[]): this;
+
     // ── Serialization ───────────────────────────────────
 
     /**

package/FastBit32.js

@@ -146,6 +146,92 @@ export class FastBit32 {
         }
         return this;
     }
+
+    // ── v1.2.0 AAA Engine Primitives ─────────────────────────
+
+    /**
+     * O(1) loop-free bit-scan forward for the lowest INACTIVE (0) bit.
+     * Essential for Object Pools to find the first available slot WITHOUT
+     * allocating a scratch FastBit32 for the inverted mask.
+     * Returns -1 if all 32 bits are active.
+     */
+    nextClearBit() {
+        const inv = ~this.value >>> 0;
+        if (inv === 0) return -1;
+        return Math.clz32(inv & -inv) ^ 31;
+    }
+
+    /**
+     * O(1) loop-free bit-scan reverse for the highest INACTIVE (0) bit.
+     * Returns -1 if all 32 bits are active.
+     */
+    highestClearBit() {
+        const inv = ~this.value >>> 0;
+        if (inv === 0) return -1;
+        return 31 - Math.clz32(inv);
+    }
+
+    /**
+     * O(1) Returns true if all 32 bits are active.
+     * Uses `~this.value === 0` because JS bitwise ops yield signed int32,
+     * so a fully-set value reads as -1 rather than 0xFFFFFFFF.
+     */
+    isFull() {
+        return ~this.value === 0;
+    }
+
+    /**
+     * O(1) active bit count within an inclusive range [start, end].
+     * Mask is built with `>>>` to avoid the `1 << 32` wraparound trap.
+     * Caller must guarantee 0 <= start <= end <= 31.
+     */
+    countRange(start, end) {
+        const mask = ((0xFFFFFFFF >>> (31 - (end - start))) << start) >>> 0;
+        return this.countMasked(mask);
+    }
+
+    // ── Debug & Init Helpers (allocate — NOT hot-path safe) ──
+
+    /**
+     * Returns the 32-bit binary string representation (LSB on the right).
+     * Forces unsigned via `>>> 0` so the sign bit prints as a leading `1`
+     * instead of triggering `toString(2)`'s minus-sign formatting.
+     * ⚠️ Allocates a String. Debug use only.
+     */
+    toBinaryString(padded = true) {
+        const str = (this.value >>> 0).toString(2);
+        return padded ? str.padStart(32, '0') : str;
+    }
+
+    /**
+     * Returns an array of active bit indexes in ascending order.
+     * Inlined O(k) scan — no closure allocation vs. delegating to forEach.
+     * ⚠️ Allocates an Array. Do not use in hot loop!
+     */
+    toArray() {
+        const result = [];
+        let v = this.value;
+        while (v !== 0) {
+            result.push(Math.clz32(v & -v) ^ 31);
+            v &= v - 1;
+        }
+        return result;
+    }
+
+    /**
+     * Replaces the mask from an array of bit indexes. Note: this OVERWRITES
+     * the current value — it does not OR into it. Accumulates in a local and
+     * writes `this.value` once for monomorphic-friendly init.
+     * ⚠️ Intended for initialization / deserialization, not hot paths.
+     */
+    fromArray(bits) {
+        let v = 0;
+        for (let i = 0; i < bits.length; i++) {
+            v |= (1 << bits[i]);
+        }
+        this.value = v >>> 0;
+        return this;
+    }
 }
 
 export class BitMapper {

package/README.md

@@ -12,9 +12,7 @@ Zero-GC, monomorphic, branchless 32-bit flag manager for ECS masking, object poo
 
 ## 🚀 Built with Lite-FastBit32: Lite-Tween Pro
 
-If you are building high-performance WebGL applications or JavaScript games, check out **Lite-Tween Pro**. It is a commercial, zero-allocation ECS tweening engine built directly on top of this bitwise architecture. 
-
-It completely bypasses the JavaScript Garbage Collector to guarantee a flat memory profile and a stable 120fps on mobile devices.
+If you are building high-performance WebGL applications or JavaScript games, check out **Lite-Tween Pro**. It is a commercial, zero-allocation ECS tweening engine built directly on top of this bitwise architecture. It completely bypasses the JavaScript Garbage Collector to guarantee a flat memory profile and a stable 120fps on mobile devices.
 
 👉 **[Get the Lite-Tween Pro Source Code here](https://zakkster.lemonsqueezy.com/checkout/buy/05ad56be-4b91-4bef-8218-9e85c65690b4)**
 
@@ -179,7 +177,7 @@ if (entity.hasAll(RENDER_QUERY))  drawSprite(entity);
 </details>
 
 <details>
-<summary><strong>Object Pool — First Free Slot</strong></summary>
+<summary><strong>Object Pool — First Free Slot (zero-allocation, v1.2.0)</strong></summary>
 
 ```javascript
 import { FastBit32 } from '@zakkster/lite-fastbit32';
@@ -188,9 +186,8 @@ const pool = new FastBit32();
 const objects = new Array(32);
 
 function allocate() {
-    const free = new FastBit32(~pool.value & 0xFFFFFFFF);
-    const slot = free.lowest();
-    if (slot === -1) return null;
+    const slot = pool.nextClearBit();   // O(1), zero allocation
+    if (slot === -1) return null;        // Pool full
     pool.add(slot);
     return slot;
 }
@@ -205,6 +202,8 @@ release(0);
 allocate(); // 0 — immediately reused
 ```
 
+> Before v1.2.0 this required constructing a scratch `FastBit32` from the inverted mask and calling `.lowest()` on it — one allocation per `allocate()` call. `nextClearBit` collapses that to a single `Math.clz32` on an inverted-and-isolated bit, with no allocations.
+
 </details>
 
 <details>
@@ -353,9 +352,13 @@ forEachMaskUnion(required, available, bit => console.log('all:', bit));
 |---|---|---|
 | `.count()` | `number` | O(1) popcount — number of active bits (0–32). |
 | `.countMasked(mask)` | `number` | O(1) popcount within a masked region. |
+| `.countRange(start, end)` | `number` | O(1) popcount within inclusive range `[start, end]`. |
 | `.lowest()` | `number` | O(1) index of least significant active bit. `-1` if empty. |
 | `.highest()` | `number` | O(1) index of most significant active bit. `-1` if empty. |
+| `.nextClearBit()` | `number` | O(1) index of least significant **clear** bit. `-1` if full. Zero-alloc pool slot lookup. |
+| `.highestClearBit()` | `number` | O(1) index of most significant **clear** bit. `-1` if full. |
 | `.isEmpty()` | `boolean` | True if value is `0`. |
+| `.isFull()` | `boolean` | True if all 32 bits are active. |
 
 ### Iteration
 
@@ -371,6 +374,16 @@ forEachMaskUnion(required, available, bit => console.log('all:', bit));
 | `.serialize()` | `number` | Export raw uint32 for JSON/binary storage. |
 | `FastBit32.deserialize(n)` | `FastBit32` | Restore from a serialized uint32. |
 
+### Debug & Init Helpers
+
+> These methods allocate. Do not call them inside hot loops.
+
+| Method | Returns | Description |
+|---|---|---|
+| `.toBinaryString(padded?)` | `string` | 32-char binary representation, LSB on the right. Sign-bit safe. |
+| `.toArray()` | `number[]` | Active bit indexes in ascending order. Inlined O(k) — no closure allocation. |
+| `.fromArray(bits)` | `this` | **Replaces** the mask from a bit-index array. Init/deserialization only. |
+
 ### `new BitMapper(names?)`
 
 | Method | Returns | Description |
@@ -396,6 +409,16 @@ forEachMaskUnion(required, available, bit => console.log('all:', bit));
 
 ## Changelog
 
+### v1.2.0
+
+**New: Clear-bit scans** — `nextClearBit()` and `highestClearBit()`. O(1) bit-scan on the inverted mask via `Math.clz32`. The object-pool slot-lookup pattern is now truly zero-allocation; the prior `new FastBit32(~pool.value & 0xFFFFFFFF).lowest()` workaround is retired.
+
+**New: `isFull()`** — Companion to `isEmpty()`. Uses `~this.value === 0` for correctness across both signed (`-1`) and unsigned (`0xFFFFFFFF`) representations of an all-set int32.
+
+**New: `countRange(start, end)`** — O(1) popcount within an inclusive bit range. Mask is built with `>>>` to sidestep the `1 << 32` wraparound.
+
+**New: Debug & init helpers** — `toBinaryString(padded?)`, `toArray()`, `fromArray(bits)`. Clearly documented as allocating; kept outside the hot-path API surface. `toBinaryString` forces unsigned via `>>> 0` so bit 31 does not trigger `toString(2)`'s minus-sign formatting. `toArray` inlines the `v &= v - 1` loop rather than delegating to `forEach`, avoiding a per-call closure allocation. `fromArray` **replaces** the current value (does not OR into it) and writes `this.value` exactly once.
+
 ### 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)`.

package/llms.txt

@@ -1,4 +1,4 @@
-# @zakkster/lite-fastbit32 v1.1.0
+# @zakkster/lite-fastbit32 v1.2.0
 
 > Zero-GC, monomorphic, branchless 32-bit flag manager for ECS masking, object pools, and 60fps hot-path engine code.
 
@@ -69,9 +69,13 @@ All mutating methods return `this` for chaining unless noted otherwise.
 |---|---|---|
 | `.count()` | `number` | O(1) popcount (Hamming weight). Active bit count, 0–32. |
 | `.countMasked(mask)` | `number` | O(1) popcount within masked region only. |
+| `.countRange(start, end)` | `number` | O(1) popcount within inclusive range `[start, end]`. Caller must ensure `0 <= start <= end <= 31`. |
 | `.lowest()` | `number` | Index of least significant set bit (0–31). Returns `-1` if empty. |
 | `.highest()` | `number` | Index of most significant set bit (0–31). Returns `-1` if empty. |
+| `.nextClearBit()` | `number` | Index of least significant **clear** bit (0–31). Returns `-1` if full. Zero-alloc object-pool slot lookup. |
+| `.highestClearBit()` | `number` | Index of most significant **clear** bit (0–31). Returns `-1` if full. |
 | `.isEmpty()` | `boolean` | True if value is 0. |
+| `.isFull()` | `boolean` | True if all 32 bits are set. |
 
 ### Iteration
 
@@ -87,6 +91,16 @@ All mutating methods return `this` for chaining unless noted otherwise.
 | `.serialize()` | `number` | Export raw uint32 for JSON/binary storage. |
 | `FastBit32.deserialize(n)` | `FastBit32` | Static. Restore from serialized uint32. |
 
+### Debug & Init Helpers
+
+These methods allocate — keep them out of hot loops.
+
+| Method | Returns | Description |
+|---|---|---|
+| `.toBinaryString(padded?)` | `string` | 32-char (or variable) binary string, LSB on the right. Handles the sign bit correctly. Allocates a String. |
+| `.toArray()` | `number[]` | Active bit indexes in ascending order. Inlined O(k) scan (no closure allocation). Allocates an Array. |
+| `.fromArray(bits)` | `this` | **Replaces** the value with a bitmask built from a bit-index array. Intended for init / deserialization. |
+
 ### Property
 
 | Property | Type | Description |
@@ -183,15 +197,14 @@ if (entity.hasAll(PHYSICS_QUERY)) {
 }
 ```
 
-### Object Pool — Find First Free Slot
+### Object Pool — Find First Free Slot (zero-allocation)
 
 ```javascript
 const occupied = new FastBit32();
 
 function allocate() {
-    const free = new FastBit32(~occupied.value & 0xFFFFFFFF);
-    const slot = free.lowest();
-    if (slot === -1) return -1; // Pool full
+    const slot = occupied.nextClearBit();   // O(1), zero allocation
+    if (slot === -1) return -1;              // Pool full
     occupied.add(slot);
     return slot;
 }
@@ -199,8 +212,13 @@ function allocate() {
 function release(slot) {
     occupied.remove(slot);
 }
+
+// Bail early when the pool is saturated:
+if (occupied.isFull()) return -1;
 ```
 
+> Prior to v1.2.0 this pattern required `new FastBit32(~occupied.value & 0xFFFFFFFF)` followed by `.lowest()`, which allocated a scratch instance per `allocate()` call. `nextClearBit` is the direct, zero-GC replacement.
+
 ### Input State Manager
 
 ```javascript

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-fastbit32",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Zero-GC, monomorphic 32-bit flag manager and ECS masking primitive for high-performance game loops.",
   "type": "module",
   "sideEffects": false,