@woosh/meep-engine 2.169.6 → 2.170.0

package/src/core/collection/PairUint32Map.js

@@ -1,321 +1,322 @@
-import { assert } from "../assert.js";
-
-/**
- * Returned by {@link PairUint32Map#get} when the key pair is absent.
- * @type {number}
- */
-export const PAIR_UINT32_MAP_ABSENT = -1;
-
-const UINT32_MAX = 4294967295;
-
-/**
- * Two multipliers chosen so the bits of `a` and `b` mix into one 32-bit hash
- * with reasonable spread for sequential-ish keys. The first is 2^32 / phi
- * (the Fibonacci constant used by {@link Uint32Map}); the second is a large
- * odd 32-bit prime used in the FNV-1a family for the secondary mix.
- * @type {number}
- */
-const MIX_A = 2654435761;
-const MIX_B = 2246822519;
-
-/**
- * Slot is 3 words wide: [key_a + 1, key_b, value]. `key_a` is stored offset by
- * +1 so that 0 in the first word unambiguously means "empty slot" — see
- * {@link Uint32Map} for the same trick on a single-key map.
- * @type {number}
- */
-const SLOT_STRIDE = 3;
-
-const DEFAULT_CAPACITY = 16;
-const MIN_CAPACITY = 2;
-const LOAD_FACTOR_NUMERATOR = 3;
-const LOAD_FACTOR_SHIFT = 2;
-
-/**
- * Open-addressed Robin Hood map from a pair of uint32 keys to a uint32 value.
- *
- * Layout: a single `Uint32Array` of `3 * capacity` words. Slot `s` is
- * `[key_a + 1, key_b, value]`. The first word doubles as the slot-occupied
- * marker (0 = empty).
- *
- * Hashing: `mix = imul(key_a + 1, MIX_A) ^ imul(key_b + 1, MIX_B)`, indexed via
- * the high bits (right-shift, not low-bit mask — high bits of a multiplicative
- * hash have more entropy, see Skarupke 2018).
- *
- * Collision resolution: Robin Hood linear probing with backward-shift deletion.
- *
- * Symmetric pair use: callers wanting `(a, b)` to be indistinguishable from
- * `(b, a)` should canonicalise (e.g. `min, max`) before calling.
- *
- * Allowed key range per slot field: 0 .. UINT32_MAX − 1 (because key_a is stored
- * as key+1). Allowed value range: full uint32.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class PairUint32Map {
-
-    /**
-     *
-     * @param {number} [initial_capacity] minimum number of slots; rounded up to power of two.
-     */
-    constructor(initial_capacity = DEFAULT_CAPACITY) {
-        assert.isNonNegativeInteger(initial_capacity, 'initial_capacity');
-
-        let cap = MIN_CAPACITY;
-        while (cap < initial_capacity) cap <<= 1;
-
-        this.__capacity = cap;
-        this.__mask = cap - 1;
-        this.__shift = Math.clz32(cap - 1);
-        this.__grow_threshold = (cap * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
-        this.__size = 0;
-        this.__data = new Uint32Array(cap * SLOT_STRIDE);
-    }
-
-    /**
-     * @returns {number}
-     */
-    get size() {
-        return this.__size;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get capacity() {
-        return this.__capacity;
-    }
-
-    /**
-     *
-     * @param {number} key_a_shifted key_a + 1 (already shifted form, as stored)
-     * @param {number} key_b
-     * @returns {number}
-     */
-    __hash(key_a_shifted, key_b) {
-        return (Math.imul(key_a_shifted, MIX_A) ^ Math.imul(key_b + 1, MIX_B)) >>> 0;
-    }
-
-    /**
-     *
-     * @param {number} key_a
-     * @param {number} key_b
-     * @returns {number} value or {@link PAIR_UINT32_MAP_ABSENT}.
-     */
-    get(key_a, key_b) {
-        const data = this.__data;
-        const mask = this.__mask;
-        const shift = this.__shift;
-
-        const ksa = key_a + 1;
-
-        let slot = this.__hash(ksa, key_b) >>> shift;
-        let dist = 0;
-
-        while (true) {
-            const off = slot * SLOT_STRIDE;
-            const ka = data[off];
-
-            if (ka === 0) {
-                return PAIR_UINT32_MAP_ABSENT;
-            }
-            if (ka === ksa && data[off + 1] === key_b) {
-                return data[off + 2];
-            }
-
-            // Robin Hood early-exit.
-            const home = this.__hash(ka, data[off + 1]) >>> shift;
-            const slot_dist = (slot - home) & mask;
-            if (dist > slot_dist) {
-                return PAIR_UINT32_MAP_ABSENT;
-            }
-
-            slot = (slot + 1) & mask;
-            dist++;
-        }
-    }
-
-    /**
-     *
-     * @param {number} key_a
-     * @param {number} key_b
-     * @returns {boolean}
-     */
-    has(key_a, key_b) {
-        return this.get(key_a, key_b) !== PAIR_UINT32_MAP_ABSENT;
-    }
-
-    /**
-     *
-     * @param {number} key_a
-     * @param {number} key_b
-     * @param {number} value
-     */
-    set(key_a, key_b, value) {
-        if (this.__size >= this.__grow_threshold) {
-            this.__resize(this.__capacity << 1);
-        }
-        this.__insert_no_grow(key_a + 1, key_b, value);
-    }
-
-    /**
-     * @private
-     * @param {number} ksa key_a + 1
-     * @param {number} kb  key_b (raw)
-     * @param {number} value
-     */
-    __insert_no_grow(ksa, kb, value) {
-        const data = this.__data;
-        const mask = this.__mask;
-        const shift = this.__shift;
-
-        let a = ksa;
-        let b = kb;
-        let v = value;
-        let slot = this.__hash(a, b) >>> shift;
-        let dist = 0;
-
-        while (true) {
-            const off = slot * SLOT_STRIDE;
-            const occ_a = data[off];
-
-            if (occ_a === 0) {
-                data[off] = a;
-                data[off + 1] = b;
-                data[off + 2] = v;
-                this.__size++;
-                return;
-            }
-
-            if (occ_a === a && data[off + 1] === b) {
-                // overwrite existing
-                data[off + 2] = v;
-                return;
-            }
-
-            const home = this.__hash(occ_a, data[off + 1]) >>> shift;
-            const occ_dist = (slot - home) & mask;
-
-            if (occ_dist < dist) {
-                // steal
-                const tmp_a = occ_a;
-                const tmp_b = data[off + 1];
-                const tmp_v = data[off + 2];
-                data[off] = a;
-                data[off + 1] = b;
-                data[off + 2] = v;
-                a = tmp_a;
-                b = tmp_b;
-                v = tmp_v;
-                dist = occ_dist;
-            }
-
-            slot = (slot + 1) & mask;
-            dist++;
-        }
-    }
-
-    /**
-     *
-     * @param {number} key_a
-     * @param {number} key_b
-     * @returns {boolean}
-     */
-    delete(key_a, key_b) {
-        const data = this.__data;
-        const mask = this.__mask;
-        const shift = this.__shift;
-
-        const ksa = key_a + 1;
-
-        let slot = this.__hash(ksa, key_b) >>> shift;
-        let dist = 0;
-
-        while (true) {
-            const off = slot * SLOT_STRIDE;
-            const ka = data[off];
-
-            if (ka === 0) {
-                return false;
-            }
-            if (ka === ksa && data[off + 1] === key_b) {
-                break;
-            }
-
-            const home = this.__hash(ka, data[off + 1]) >>> shift;
-            const slot_dist = (slot - home) & mask;
-            if (dist > slot_dist) {
-                return false;
-            }
-
-            slot = (slot + 1) & mask;
-            dist++;
-        }
-
-        // backward-shift deletion
-        while (true) {
-            const next = (slot + 1) & mask;
-            const next_off = next * SLOT_STRIDE;
-            const next_ka = data[next_off];
-
-            if (next_ka === 0) {
-                break;
-            }
-
-            const next_home = this.__hash(next_ka, data[next_off + 1]) >>> shift;
-            const next_dist = (next - next_home) & mask;
-            if (next_dist === 0) {
-                break;
-            }
-
-            const off = slot * SLOT_STRIDE;
-            data[off] = next_ka;
-            data[off + 1] = data[next_off + 1];
-            data[off + 2] = data[next_off + 2];
-            slot = next;
-        }
-
-        const off = slot * SLOT_STRIDE;
-        data[off] = 0;
-        data[off + 1] = 0;
-        data[off + 2] = 0;
-
-        this.__size--;
-        return true;
-    }
-
-    clear() {
-        this.__data.fill(0);
-        this.__size = 0;
-    }
-
-    /**
-     * @private
-     * @param {number} new_capacity power of two
-     */
-    __resize(new_capacity) {
-        const old_data = this.__data;
-        const old_capacity = this.__capacity;
-
-        this.__capacity = new_capacity;
-        this.__mask = new_capacity - 1;
-        this.__shift = Math.clz32(new_capacity - 1);
-        this.__grow_threshold = (new_capacity * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
-        this.__data = new Uint32Array(new_capacity * SLOT_STRIDE);
-        this.__size = 0;
-
-        for (let i = 0; i < old_capacity; i++) {
-            const off = i * SLOT_STRIDE;
-            const a = old_data[off];
-            if (a !== 0) {
-                this.__insert_no_grow(a, old_data[off + 1], old_data[off + 2]);
-            }
-        }
-    }
-}
-
-/**
- * @type {number}
- */
-PairUint32Map.MAX_KEY = UINT32_MAX - 1;
+import { assert } from "../assert.js";
+
+/**
+ * Returned by {@link PairUint32Map#get} when the key pair is absent.
+ * @type {number}
+ */
+export const PAIR_UINT32_MAP_ABSENT = -1;
+
+const UINT32_MAX = 4294967295;
+
+/**
+ * Two multipliers chosen so the bits of `a` and `b` mix into one 32-bit hash
+ * with reasonable spread for sequential-ish keys. The first is 2^32 / phi
+ * (the Fibonacci constant used by {@link Uint32Map}); the second is a large
+ * odd 32-bit prime used in the FNV-1a family for the secondary mix.
+ * @type {number}
+ */
+const MIX_A = 2654435761;
+const MIX_B = 2246822519;
+
+/**
+ * Slot is 3 words wide: [key_a + 1, key_b, value]. `key_a` is stored offset by
+ * +1 so that 0 in the first word unambiguously means "empty slot" — see
+ * {@link Uint32Map} for the same trick on a single-key map.
+ * @type {number}
+ */
+const SLOT_STRIDE = 3;
+
+const DEFAULT_CAPACITY = 16;
+const MIN_CAPACITY = 2;
+const LOAD_FACTOR_NUMERATOR = 3;
+const LOAD_FACTOR_SHIFT = 2;
+
+/**
+ * Open-addressed Robin Hood map from a pair of uint32 keys to a uint32 value.
+ *
+ * Layout: a single `Uint32Array` of `3 * capacity` words. Slot `s` is
+ * `[key_a + 1, key_b, value]`. The first word doubles as the slot-occupied
+ * marker (0 = empty).
+ *
+ * Hashing: `mix = imul(key_a + 1, MIX_A) ^ imul(key_b + 1, MIX_B)`, indexed via
+ * the high bits (right-shift, not low-bit mask — high bits of a multiplicative
+ * hash have more entropy, see Skarupke 2018).
+ *
+ * Collision resolution: Robin Hood linear probing with backward-shift deletion.
+ *
+ * Symmetric pair use: callers wanting `(a, b)` to be indistinguishable from
+ * `(b, a)` should canonicalise (e.g. `min, max`) before calling.
+ *
+ * Allowed key range per slot field: 0 .. UINT32_MAX − 1 (because key_a is stored
+ * as key+1). Allowed value range: full uint32.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PairUint32Map {
+
+    __size = 0;
+
+    /**
+     *
+     * @param {number} [initial_capacity] minimum number of slots; rounded up to power of two.
+     */
+    constructor(initial_capacity = DEFAULT_CAPACITY) {
+        assert.isNonNegativeInteger(initial_capacity, 'initial_capacity');
+
+        let cap = MIN_CAPACITY;
+        while (cap < initial_capacity) cap <<= 1;
+
+        this.__capacity = cap;
+        this.__mask = cap - 1;
+        this.__shift = Math.clz32(cap - 1);
+        this.__grow_threshold = (cap * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        this.__data = new Uint32Array(cap * SLOT_STRIDE);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get size() {
+        return this.__size;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get capacity() {
+        return this.__capacity;
+    }
+
+    /**
+     *
+     * @param {number} key_a_shifted key_a + 1 (already shifted form, as stored)
+     * @param {number} key_b
+     * @returns {number}
+     */
+    __hash(key_a_shifted, key_b) {
+        return (Math.imul(key_a_shifted, MIX_A) ^ Math.imul(key_b + 1, MIX_B)) >>> 0;
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {number} value or {@link PAIR_UINT32_MAP_ABSENT}.
+     */
+    get(key_a, key_b) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const ksa = key_a + 1;
+
+        let slot = this.__hash(ksa, key_b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const ka = data[off];
+
+            if (ka === 0) {
+                return PAIR_UINT32_MAP_ABSENT;
+            }
+            if (ka === ksa && data[off + 1] === key_b) {
+                return data[off + 2];
+            }
+
+            // Robin Hood early-exit.
+            const home = this.__hash(ka, data[off + 1]) >>> shift;
+            const slot_dist = (slot - home) & mask;
+            if (dist > slot_dist) {
+                return PAIR_UINT32_MAP_ABSENT;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    has(key_a, key_b) {
+        return this.get(key_a, key_b) !== PAIR_UINT32_MAP_ABSENT;
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @param {number} value
+     */
+    set(key_a, key_b, value) {
+        if (this.__size >= this.__grow_threshold) {
+            this.__resize(this.__capacity << 1);
+        }
+        this.__insert_no_grow(key_a + 1, key_b, value);
+    }
+
+    /**
+     * @private
+     * @param {number} ksa key_a + 1
+     * @param {number} kb  key_b (raw)
+     * @param {number} value
+     */
+    __insert_no_grow(ksa, kb, value) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        let a = ksa;
+        let b = kb;
+        let v = value;
+        let slot = this.__hash(a, b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const occ_a = data[off];
+
+            if (occ_a === 0) {
+                data[off] = a;
+                data[off + 1] = b;
+                data[off + 2] = v;
+                this.__size++;
+                return;
+            }
+
+            if (occ_a === a && data[off + 1] === b) {
+                // overwrite existing
+                data[off + 2] = v;
+                return;
+            }
+
+            const home = this.__hash(occ_a, data[off + 1]) >>> shift;
+            const occ_dist = (slot - home) & mask;
+
+            if (occ_dist < dist) {
+                // steal
+                const tmp_a = occ_a;
+                const tmp_b = data[off + 1];
+                const tmp_v = data[off + 2];
+                data[off] = a;
+                data[off + 1] = b;
+                data[off + 2] = v;
+                a = tmp_a;
+                b = tmp_b;
+                v = tmp_v;
+                dist = occ_dist;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    delete(key_a, key_b) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const ksa = key_a + 1;
+
+        let slot = this.__hash(ksa, key_b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const ka = data[off];
+
+            if (ka === 0) {
+                return false;
+            }
+            if (ka === ksa && data[off + 1] === key_b) {
+                break;
+            }
+
+            const home = this.__hash(ka, data[off + 1]) >>> shift;
+            const slot_dist = (slot - home) & mask;
+            if (dist > slot_dist) {
+                return false;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+
+        // backward-shift deletion
+        while (true) {
+            const next = (slot + 1) & mask;
+            const next_off = next * SLOT_STRIDE;
+            const next_ka = data[next_off];
+
+            if (next_ka === 0) {
+                break;
+            }
+
+            const next_home = this.__hash(next_ka, data[next_off + 1]) >>> shift;
+            const next_dist = (next - next_home) & mask;
+            if (next_dist === 0) {
+                break;
+            }
+
+            const off = slot * SLOT_STRIDE;
+            data[off] = next_ka;
+            data[off + 1] = data[next_off + 1];
+            data[off + 2] = data[next_off + 2];
+            slot = next;
+        }
+
+        const off = slot * SLOT_STRIDE;
+        data[off] = 0;
+        data[off + 1] = 0;
+        data[off + 2] = 0;
+
+        this.__size--;
+        return true;
+    }
+
+    clear() {
+        this.__data.fill(0);
+        this.__size = 0;
+    }
+
+    /**
+     * @private
+     * @param {number} new_capacity power of two
+     */
+    __resize(new_capacity) {
+        const old_data = this.__data;
+        const old_capacity = this.__capacity;
+
+        this.__capacity = new_capacity;
+        this.__mask = new_capacity - 1;
+        this.__shift = Math.clz32(new_capacity - 1);
+        this.__grow_threshold = (new_capacity * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        this.__data = new Uint32Array(new_capacity * SLOT_STRIDE);
+        this.__size = 0;
+
+        for (let i = 0; i < old_capacity; i++) {
+            const off = i * SLOT_STRIDE;
+            const a = old_data[off];
+            if (a !== 0) {
+                this.__insert_no_grow(a, old_data[off + 1], old_data[off + 2]);
+            }
+        }
+    }
+}
+
+/**
+ * @type {number}
+ */
+PairUint32Map.MAX_KEY = UINT32_MAX - 1;

package/src/core/collection/RingBuffer.d.ts

@@ -9,11 +9,6 @@ export class RingBuffer<V> {
      * @param {number} size
      */
     constructor(size: number);
-    /**
-     * Capacity of the buffer, number of slots
-     * @type {number}
-     */
-    size: number;
     /**
      *
      * @type {number}
@@ -29,6 +24,11 @@ export class RingBuffer<V> {
      * @type {number}
      */
     count: number;
+    /**
+     * Capacity of the buffer, number of slots
+     * @type {number}
+     */
+    size: number;
     /**
      *
      * @type {V[]}