@woosh/meep-engine 2.48.22 → 2.49.0

package/src/core/collection/HashMap.js

@@ -1,6 +1,38 @@
 import { assert } from "../assert.js";
 import { invokeObjectEquals } from "../model/object/invokeObjectEquals.js";
 import { invokeObjectHash } from "../model/object/invokeObjectHash.js";
+import { isPowerOfTwo } from "../math/isPowerOrTwo.js";
+import { ctz32 } from "../binary/ctz32.js";
+import { ceilPowerOfTwo } from "../binary/operations/ceilPowerOfTwo.js";
+import { UintArrayForCount } from "./array/typed/uint_array_for_count.js";
+import { array_copy } from "./array/copyArray.js";
+import { min2 } from "../math/min2.js";
+import { arraySwapElements } from "./array/arraySwapElements.js";
+
+/*
+ * Heavily inspired by ruby's "new" (circa 2016) hash table implementation
+ * @see https://github.com/ruby/ruby/blob/82995d4615e993f1d13f3e826b93fbd65c47e19e/st.c
+ * @see https://blog.heroku.com/ruby-2-4-features-hashes-integers-rounding#hash-changes
+ */
+
+/**
+ * Formula: Xn+1 = (a * Xn + c ) % m
+ *
+ *    According the Hull-Dobell theorem a generator
+ *    "Xnext = (a*Xprev + c) mod m" is a full cycle generator if and only if
+ *      o m and c are relatively prime
+ *      o a-1 is divisible by all prime factors of m
+ *      o a-1 is divisible by 4 if m is divisible by 4.
+ *    For our case a is 5, c is 1, and m is a power of two.
+ * @param index
+ * @param mask used to execute division, this is a number equal to (2^K - 1) where 2^K is the size of the "bins" array
+ * @see https://en.wikipedia.org/wiki/Linear_congruential_generator
+ */
+export function generate_next_linear_congruential_index(index, mask) {
+    const index5 = (index << 2) + index; // this is just a faster version of index*5
+
+    return (index5 + 1) & mask;
+}
 
 
 /**
@@ -40,28 +72,151 @@ class MapEntry {
  * @readonly
  * @type {number}
  */
-const DEFAULT_INITIAL_CAPACITY = 16;
+const DEFAULT_INITIAL_CAPACITY_POWER = 4;
 
 /**
  * @readonly
  * @type {number}
  */
-const DEFAULT_LOAD_FACTOR = 0.75;
+const DEFAULT_INITIAL_CAPACITY = 2 ** DEFAULT_INITIAL_CAPACITY_POWER;
 
 /**
- * Multiply previous size by this number when growing the table
  * @readonly
  * @type {number}
  */
-const GROWTH_FACTOR = 2;
+const DEFAULT_LOAD_FACTOR = 0.75;
+
+
+/**
+ * Reserved value that we store in "bins" array to indicate an empty slot
+ * @type {number}
+ */
+const BIN_RESERVED_VALUE_EMPTY = 0;
+
+/**
+ * Reserved value that we store in "bins" array to indicate a deleted entry
+ * @type {number}
+ */
+const BIN_RESERVED_VALUE_DELETED = 1;
+
+/**
+ * Real index offset into entry array
+ * @type {number}
+ */
+const ENTRY_BASE = 2;
+
+/**
+ * Special hash value used to indicate "dead" entries
+ * If key hashes to this value - we will replace it
+ * @type {number}
+ */
+const RESERVED_HASH = 4294967295;
+/**
+ * Used as a replacement for reserved hash
+ * @type {number}
+ */
+const RESERVED_HASH_SUBSTITUTE = 0;
+
+/**
+ *
+ * @type {number}
+ */
+const UNDEFINED_BIN_INDEX = ~0;
+
+
+/**
+ * @template K,V
+ * @param {MapEntry<K,V>} record
+ * @param {number} hash
+ * @param {K} key
+ * @param {function(a:K,b:K):boolean} equality_op
+ */
+function entry_equality_check(record, hash, key, equality_op) {
+    if (record.hash !== hash) {
+        return false;
+    }
+
+    if (record.key === key) {
+        return true;
+    }
+
+    const result = equality_op(record.key, key);
+
+    assert.isBoolean(result, `result(a=${record.key},b=${key})`);
+
+    return result;
+}
+
+
+const EMPTY_BINS = new Uint32Array(0);
 
 /**
  * Implements part of {@link Map} interface
+ * NOTE: as with any hash-based data structure, keys are assumed to be immutable. If you modified keys after inserting them into the map, it will cause the hash table to become invalid. You can fix this by forcing rehashing, but generally - try to avoid changing keys in the first place.
+ *
  * @copyright Alex Goldring (c) 2023
  * @template K,V
  * @extends Map<K,V>
  */
 export class HashMap {
+    /**
+     * Index pointers to entries array,
+     * number of bins is always power or two
+     * @type {Uint32Array}
+     */
+    #bins = EMPTY_BINS;
+
+    /**
+     * Note that dead entries are marked as such with a special reserved hash values, so records can be reused for new entries
+     * @type {MapEntry<K,V>[]}
+     */
+    #entries = new Array(0);
+
+    /**
+     * Pointer to the end of allocated entries segment
+     * @type {number}
+     */
+    #entries_bound = 0;
+
+    /**
+     *
+     * @type {number}
+     */
+    #entries_start = 0;
+
+    /**
+     * number of records in the map
+     * @type {number}
+     */
+    #size = 0;
+
+    #bin_count = 0;
+
+    /**
+     * Always exactly half of the number of bins
+     * @type {number}
+     */
+    #entries_allocated_count = 0;
+
+    #bin_count_power_of_two = 0;
+
+    #entries_count_power_of_two = 0;
+
+    /**
+     * Mask used to map from hash to a bin index
+     * @type {number}
+     */
+    #bin_count_mask = 0;
+
+    /**
+     * How full the table can get before number of buckets is increased
+     * @type {number}
+     * @private
+     */
+    #load_factor = DEFAULT_LOAD_FACTOR;
+
+    #version = 0;
+
     /**
      * @template K, V
      * @param {function(K):number} [keyHashFunction]
@@ -81,45 +236,31 @@ export class HashMap {
         assert.isNonNegativeInteger(capacity, 'capacity');
 
         assert.isNumber(loadFactor, 'loadFactor');
+        assert.notNaN(loadFactor, 'loadFactor');
         assert.greaterThan(loadFactor, 0, 'loadFactor must be > 0');
 
         /**
          *
          * @type {function(K): number}
+         * @readonly
+         * @private
          */
         this.keyHashFunction = keyHashFunction;
         /**
          *
          * @type {function(K, K): boolean}
+         * @readonly
+         * @private
          */
         this.keyEqualityFunction = keyEqualityFunction;
 
-        /**
-         * Sparse array of map entries
-         * @type {MapEntry[][]}
-         */
-        this.records = [];
-
-        /**
-         *
-         * @type {number}
-         */
-        this.size = 0;
+        this.#load_factor = loadFactor;
 
+        this.#setBinCount(ceilPowerOfTwo(capacity));
+    }
 
-        /**
-         *
-         * @type {number}
-         * @private
-         */
-        this.__bucket_count = capacity;
-
-        /**
-         * How full the table can get before number of buckets is increased
-         * @type {number}
-         * @private
-         */
-        this.__load_factor = loadFactor;
+    get size() {
+        return this.#size;
     }
 
     /**
@@ -127,61 +268,43 @@ export class HashMap {
      * @returns {number}
      */
     getCurrentLoad() {
-        return this.size / this.__bucket_count;
+        return this.#size / this.#bin_count;
     }
 
     /**
-     * Proportion of buckets that are occupied with at least 1 record
-     * @returns {number}
+     * Note: this method is not intended for public use
+     * @param {number} count
      */
-    getOccupancy() {
-        let occupied_bucket_count = 0;
-
-        const c = this.__bucket_count;
-        for (let i = 0; i < c; i++) {
-            const bucket = this.records[i];
+    #setBinCount(count) {
+        assert.greaterThanOrEqual(count, 1, 'bucket count must be at least 1');
+        assert.isNonNegativeInteger(count, 'count');
+        assert.equal(isPowerOfTwo(count), true, `count must be a power of two, instead was ${count}`);
 
-            if (bucket !== undefined && bucket.length > 0) {
-                occupied_bucket_count++;
-            }
+        if (count < this.#size) {
+            throw new Error(`count must be at least equal to must of records in the map (=${this.#size}), instead was ${count}`);
         }
 
-        return occupied_bucket_count / this.__bucket_count;
-    }
 
-    /**
-     * Number of collisions, that is elements beyond first that occupy the same bucket in the table
-     * @returns {number}
-     */
-    getCollisionCount() {
-        let count = 0;
+        this.#entries_count_power_of_two = ctz32(count);
+        this.#bin_count_power_of_two = this.#entries_count_power_of_two + 1;
 
-        const c = this.__bucket_count;
-        for (let i = 0; i < c; i++) {
-            const bucket = this.records[i];
+        this.#bin_count = 2 ** this.#bin_count_power_of_two;
+        this.#bin_count_mask = this.#bin_count - 1;
 
-            if (bucket !== undefined) {
-                const occupancy = bucket.length;
-                const collisions = occupancy - 1;
-                if (collisions > 0) {
-                    count += collisions;
-                }
-            }
-        }
+        this.#entries_allocated_count = 2 ** this.#entries_count_power_of_two;
 
-        return count;
-    }
+        const BinsArray = UintArrayForCount(this.#entries_allocated_count + ENTRY_BASE);
 
-    /**
-     *
-     * @param {number} count
-     */
-    setBucketCount(count) {
-        assert.greaterThanOrEqual(count, 1, 'bucket count must be at least 1');
-        assert.isNonNegativeInteger(count, 'count');
+        this.#bins = new BinsArray(this.#bin_count);
+
+        const new_entries = new Array(this.#entries_allocated_count);
+        const old_entries = this.#entries;
+
+        this.#entries = new_entries;
+
+        array_copy(old_entries, 0, new_entries, 0, min2(old_entries.length, this.#entries_allocated_count));
 
-        this.__bucket_count = count;
-        if (this.size > 0) {
+        if (this.#size > 0) {
             // re-hash
             this.rebuild();
         }
@@ -193,7 +316,7 @@ export class HashMap {
      * @returns {number}
      * @private
      */
-    __compute_bucket_index(hash) {
+    #compute_bin_index(hash) {
         assert.isInteger(hash, 'hash');
 
         // mix the input hash to minimize potential impact of poor hash function spread
@@ -202,76 +325,141 @@ export class HashMap {
         // force index to unsigned integer
         const index = mixed_hash >>> 0;
 
-        return index % this.__bucket_count;
+        return index & this.#bin_count_mask;
     }
 
     /**
      *
      * @param {K} key
-     * @param {V} value
+     * @return {number}
      */
-    set(key, value) {
-        const raw_hash = this.keyHashFunction(key);
-        const bucket_index = this.__compute_bucket_index(raw_hash);
+    #build_key_hash(key) {
+        const original = this.keyHashFunction(key);
 
-        assert.isFiniteNumber(bucket_index, 'hash');
+        return original === RESERVED_HASH ? RESERVED_HASH_SUBSTITUTE : original;
+    }
 
-        const records = this.records;
+    /**
+     *
+     * @param {K} k
+     * @param {V} v
+     * @param {number} hash
+     * @return {number}
+     */
+    #allocate_entry(k, v, hash) {
 
-        let bucket = records[bucket_index];
+        const i = this.#entries_bound;
 
-        if (bucket === undefined) {
+        this.#entries_bound++;
 
-            // bucket for this value doesn't exist
+        if (this.#entries[i] !== undefined) {
+            const entry = this.#entries[i];
+            entry.hash = hash;
+            entry.key = k;
+            entry.value = v;
+        } else {
+            this.#entries[i] = new MapEntry(k, v, hash);
+        }
 
-            bucket = [];
+        return i;
+    }
 
-            records[bucket_index] = bucket;
+    /**
+     *
+     * @param {MapEntry<K,V>} entry
+     */
+    #deallocate(entry) {
 
-        } else {
+        // clear out entry to allow values/keys to be garbage collected
+        entry.key = null;
+        entry.value = null;
+        entry.hash = RESERVED_HASH; // mark as dead via hash
 
-            // bucket exists
+    }
 
-            const bucketSize = bucket.length;
+    #rebuild_if_necessary() {
+        if (this.#entries_bound === this.#entries_allocated_count) {
+            if (this.#size === this.#entries_allocated_count) {
+                // used up all allocated entries
+                // bin count must always be larger than end of the entries table
+                this.#grow();
+            } else {
+                // exhausted entries array, perform compaction
+                this.rebuild();
+            }
+        }
+    }
 
-            //check if key already exists
-            for (let i = 0; i < bucketSize; i++) {
-                const entry = bucket[i];
+    /**
+     *
+     * @param {K} key
+     * @param {V} value
+     */
+    set(key, value) {
+        this.#rebuild_if_necessary();
 
-                const entryKey = entry.key;
+        const raw_hash = this.#build_key_hash(key);
+        let bin_index = this.#compute_bin_index(raw_hash);
+        assert.isFiniteNumber(bin_index, 'hash');
 
+        let first_deleted_bin_index = UNDEFINED_BIN_INDEX;
 
-                if (
-                    entry.hash === raw_hash
-                    && (entryKey === key || this.keyEqualityFunction(entryKey, key))
-                ) {
+        for (; ;) {
+            const bin = this.#bins[bin_index];
 
-                    // found record with matching key, replace the value
+            if (bin > BIN_RESERVED_VALUE_DELETED) {
+                // bin is occupied
 
-                    entry.value = value;
+                // check if it's the entry that we're looking for
+                const entry = this.#entries[bin - ENTRY_BASE];
 
-                    // done, return
+                if (entry_equality_check(entry, raw_hash, key, this.keyEqualityFunction)) {
+                    // found the right entry
+                    entry.value = value;
                     return;
+                }
+            } else if (bin === BIN_RESERVED_VALUE_EMPTY) {
+                // bin is empty
 
+                if (first_deleted_bin_index !== UNDEFINED_BIN_INDEX) {
+                    // reused bin of deleted entity
+                    bin_index = first_deleted_bin_index;
                 }
 
+                const entry_index = this.#allocate_entry(key, value, raw_hash);
+
+                assert.defined(this.#entries[entry_index], 'entry');
+
+                assert.equal(this.#entries[entry_index].hash, raw_hash, 'entry.hash');
+                assert.equal(this.#entries[entry_index].value, value, 'entry.value');
+                assert.equal(this.#entries[entry_index].key, key, 'entry.key');
+
+                this.#bins[bin_index] = entry_index + ENTRY_BASE;
+
+                break;
+
+            } else if (first_deleted_bin_index === UNDEFINED_BIN_INDEX) {
+                // bin is deleted
+                first_deleted_bin_index = bin_index;
+
             }
 
-        }
+            // perform secondary hashing
+            bin_index = generate_next_linear_congruential_index(bin_index, this.#bin_count_mask);
 
-        bucket.push(new MapEntry(key, value, raw_hash));
+        }
 
-        const old_size = this.size;
+        const old_size = this.#size;
         const new_size = old_size + 1;
-        this.size = new_size;
+        this.#size = new_size;
 
         // compute actual current load
-        const bucket_count = this.__bucket_count;
+        const bucket_count = this.#bin_count;
         const load = new_size / bucket_count;
 
-        if (load > this.__load_factor) {
+        if (load > this.#load_factor) {
             // current load is too high, increase table size
-            this.setBucketCount(bucket_count * GROWTH_FACTOR);
+            this.#grow();
         }
     }
 
@@ -281,33 +469,34 @@ export class HashMap {
      * @returns {V|undefined}
      */
     get(key) {
-        const raw_hash = this.keyHashFunction(key);
-        const bucket_index = this.__compute_bucket_index(raw_hash);
-        const bucket = this.records[bucket_index];
+        const raw_hash = this.#build_key_hash(key);
 
-        if (bucket !== undefined) {
+        let bin_index = this.#compute_bin_index(raw_hash);
 
-            const bucketSize = bucket.length;
+        for (; ;) {
+            const bin = this.#bins[bin_index];
 
-            //check if key already exists
-            for (let i = 0; i < bucketSize; i++) {
-                const entry = bucket[i];
+            if (bin > BIN_RESERVED_VALUE_DELETED) {
+                // bin is occupied
 
-                const entryKey = entry.key;
+                // check if the entry is what we're looking for
+                const entry = this.#entries[bin - ENTRY_BASE];
 
-                if (
-                    entry.hash === raw_hash
-                    && (entryKey === key || this.keyEqualityFunction(entryKey, key))
-                ) {
+                if (entry_equality_check(entry, raw_hash, key, this.keyEqualityFunction)) {
+                    // found the right entry
                     return entry.value;
-
                 }
+
+            } else if (bin === BIN_RESERVED_VALUE_EMPTY) {
+                // bin is empty
+                return undefined;
             }
 
+            // perform secondary hashing
+            bin_index = generate_next_linear_congruential_index(bin_index, this.#bin_count_mask);
+
         }
 
-        //not found
-        return undefined;
     }
 
     /**
@@ -351,6 +540,26 @@ export class HashMap {
         return value;
     }
 
+    /**
+     *
+     * @param {number} bin
+     */
+    #update_range_for_deleted(bin) {
+        if (this.#entries_start === bin) {
+            let start = bin + 1;
+            let bound = this.#entries_bound;
+
+            const entries = this.#entries;
+
+            while (start < bound && entries[start].hash === RESERVED_HASH) {
+                start++;
+            }
+
+            assert.greaterThanOrEqual(bound - start, this.#size, `live entity bounds must span at least number of entries equal to map size(=${this.#size}), instead got start(=${start}), and end(=${bound})`)
+
+            this.#entries_start = start;
+        }
+    }
 
     /**
      *
@@ -359,38 +568,49 @@ export class HashMap {
      */
     delete(key) {
 
-        const raw_hash = this.keyHashFunction(key);
-        const bucket_index = this.__compute_bucket_index(raw_hash);
-        const bucket = this.records[bucket_index];
+        const raw_hash = this.#build_key_hash(key);
+        let bin_index = this.#compute_bin_index(raw_hash);
 
-        if (bucket === undefined) {
-            return false;
-        }
+        assert.isFiniteNumber(bin_index, 'hash');
 
+        const bins = this.#bins;
+        const entries = this.#entries;
 
-        const bucketSize = bucket.length;
+        for (; ;) {
+            const bin = bins[bin_index];
 
-        //check if key already exists
-        for (let i = 0; i < bucketSize; i++) {
-            const entry = bucket[i];
+            if (bin > BIN_RESERVED_VALUE_DELETED) {
+                // bin is occupied
 
-            const entryKey = entry.key;
-            if (entryKey === key || this.keyEqualityFunction(entryKey, key)) {
+                // check if the entry is what we're looking for
+                const entry_index = bin - ENTRY_BASE;
+                const entry = entries[entry_index];
 
-                if (bucket.length <= 1) {
-                    //last element in the bucket
-                    delete this.records[bucket_index];
-                } else {
-                    bucket.splice(i, 1);
+                if (entry_equality_check(entry, raw_hash, key, this.keyEqualityFunction)) {
+                    // found the right entry
+
+                    // record entry as dead
+                    this.#deallocate(entry);
+
+                    // mark slot as removed
+                    bins[bin_index] = BIN_RESERVED_VALUE_DELETED;
+
+                    this.#size--;
+
+                    this.#update_range_for_deleted(entry_index);
+
+                    return true;
                 }
 
-                this.size--;
-                return true;
+            } else if (bin === BIN_RESERVED_VALUE_EMPTY) {
+                // bin is empty
+                return false;
             }
-        }
 
-        //not found
-        return false;
+            // perform secondary hashing
+            bin_index = generate_next_linear_congruential_index(bin_index, this.#bin_count_mask);
+
+        }
     }
 
     /**
@@ -402,130 +622,134 @@ export class HashMap {
     verifyHashes(callback, thisArg) {
         let all_hashes_valid = true;
 
-        let h, i;
-
-        const records = this.records;
+        const count = this.#bin_count;
+        for (let j = 0; j < count; j++) {
+            const bin = this.#bins[j];
 
-        for (h in records) {
-            if (!records.hasOwnProperty(h)) {
+            if (bin <= BIN_RESERVED_VALUE_DELETED) {
+                // unoccupied
                 continue;
             }
 
-            const bucket = records[h];
-
-            const bucketSize = bucket.length;
-
-            //check if key already exists
-            for (i = 0; i < bucketSize; i++) {
-
-                /**
-                 * @type {MapEntry<K,V>}
-                 */
-                const entry = bucket[i];
+            /**
+             * @type {MapEntry<K,V>}
+             */
+            const entry = this.#entries[bin - ENTRY_BASE];
 
-                //check hash
-                const raw_hash = this.keyHashFunction(entry.key);
+            //check hash
+            const raw_hash = this.#build_key_hash(entry.key);
 
-                if (entry.hash !== raw_hash) {
-                    callback.call(thisArg, `Hash stored on the entry(=${entry.hash}) is different from the computed key hash(=${raw_hash}).`, entry.key, entry.value)
+            if (entry.hash !== raw_hash) {
+                callback.call(thisArg, `Hash stored on the entry(=${entry.hash}) is different from the computed key hash(=${raw_hash}).`, entry.key, entry.value)
 
-                    all_hashes_valid = false;
-                }
-
-                const actual_bucket_index = this.__compute_bucket_index(raw_hash);
-
-                const stored_bucket_index = parseInt(h);
-
-                if (actual_bucket_index !== stored_bucket_index) {
-                    callback.call(thisArg, `Hash of key has changed. old=${stored_bucket_index}, new=${actual_bucket_index}`, entry.key, entry.value);
-
-                    all_hashes_valid = false;
-                }
+                all_hashes_valid = false;
             }
+
         }
 
         return all_hashes_valid;
     }
 
+    #grow() {
+        this.#setBinCount(this.#entries_allocated_count * 2);
+    }
+
+
     /**
-     * Rebuild table, useful for when table is resized or hashes of stored keys change
+     * Rebuild table, useful for when table is resized
      */
     rebuild() {
+        const entries_bound = this.#entries_bound;
+        const entries = this.#entries;
+
+        // reset all bins
+        const bins = this.#bins;
+        bins.fill(BIN_RESERVED_VALUE_EMPTY);
 
-        let string_bucket_index, i, l;
+        let written_entries = 0;
 
-        const records = this.records;
+        for (let existing_entry_index = this.#entries_start; existing_entry_index < entries_bound; existing_entry_index++) {
+            const entry = entries[existing_entry_index];
 
-        for (string_bucket_index in records) {
-            const stored_bucket_index = parseInt(string_bucket_index);
+            const hash = entry.hash;
 
-            if (!records.hasOwnProperty(string_bucket_index)) {
+            if (hash === RESERVED_HASH) {
+                // entry is dead
                 continue;
             }
 
-            const bucket = records[stored_bucket_index];
+            const new_index = written_entries;
+            written_entries++;
 
-            for (i = 0, l = bucket.length; i < l; i++) {
-                /**
-                 * @type {MapEntry<K,V>}
-                 */
-                const entry = bucket[i];
+            if (new_index !== existing_entry_index) {
+                // move entries to the new position, compacting holes
+                arraySwapElements(entries, new_index, existing_entry_index);
+            }
 
-                //check hash
-                const raw_hash = this.keyHashFunction(entry.key);
+            let bin_index = this.#compute_bin_index(hash);
 
-                entry.hash = raw_hash;
+            for (; ;) {
+                const bin = bins[bin_index];
 
-                const actual_bucket_index = this.__compute_bucket_index(raw_hash);
+                if (bin === BIN_RESERVED_VALUE_EMPTY) {
+                    // empty slot, take it
+                    bins[bin_index] = new_index + ENTRY_BASE;
+                    break;
+                }
 
+                // perform secondary hashing
+                bin_index = generate_next_linear_congruential_index(bin_index, this.#bin_count_mask);
 
-                if (actual_bucket_index !== stored_bucket_index) {
-                    //remove entry from the bucket
+            }
+        }
 
-                    bucket.splice(i, 1);
-                    //update iterator
-                    l--;
-                    i--;
+        assert.equal(written_entries, this.#size, `live entries(=${written_entries}) should match size(=${this.#size})`);
 
-                    if (bucket.length === 0) {
-                        //delete empty bucket
-                        delete records[stored_bucket_index];
-                    }
+        this.#entries_start = 0;
+        this.#entries_bound = this.#size;
+        this.#version++;
+    }
 
-                    const newBucket = records[actual_bucket_index];
+    #count_live_entities() {
+        let count = 0;
+        for (let i = this.#entries_start; i < this.#entries_bound; i++) {
+            const entry = this.#entries[i];
 
-                    if (newBucket === undefined) {
-                        records[actual_bucket_index] = [entry];
-                    } else {
-                        newBucket.push(entry);
-                    }
+            if (entry.hash !== RESERVED_HASH) {
+                count++;
 
-                }
+                assert.equal(entry.hash, this.#build_key_hash(entry.key));
+            } else {
+                assert.isNull(entry.key, 'key');
             }
         }
+
+        return count;
     }
 
     forEach(callback, thisArg) {
-        let h, i, l;
+        const count = this.#bin_count;
+        const entries = this.#entries;
+        const bins = this.#bins;
+        const start_version = this.#version;
+
+        for (let j = 0; j < count; j++) {
+            assert.equal(start_version, this.#version, 'HashMap modified during traversal');
 
-        const records = this.records;
+            const bin = bins[j];
 
-        for (h in records) {
-            if (!records.hasOwnProperty(h)) {
+            if (bin <= BIN_RESERVED_VALUE_DELETED) {
+                // unoccupied
                 continue;
             }
 
-            const bucket = records[h];
+            /**
+             * @type {MapEntry<K,V>}
+             */
+            const entry = entries[bin - ENTRY_BASE];
 
-            for (i = 0, l = bucket.length; i < l; i++) {
-                /**
-                 * @type {MapEntry<K,V>}
-                 */
-                const entry = bucket[i];
-
-                // Signature based on MDN docs of Map.prototype.forEach()
-                callback.call(thisArg, entry.value, entry.key, this);
-            }
+            // Signature based on MDN docs of Map.prototype.forEach()
+            callback.call(thisArg, entry.value, entry.key, this);
         }
     }
 
@@ -542,30 +766,61 @@ export class HashMap {
      * Remove all data from the Map
      */
     clear() {
-        this.records = [];
-        this.size = 0;
+
+        // clear out all
+        const bins = this.#bins;
+        const count = this.#bin_count;
+
+        for (let i = 0; i < count; i++) {
+            const bin = bins[i];
+
+            if (bin !== BIN_RESERVED_VALUE_EMPTY) {
+
+                if (bin !== BIN_RESERVED_VALUE_DELETED) {
+                    // occupied, move to deleted
+                    const entry_index = bin - ENTRY_BASE;
+
+                    this.#deallocate(this.#entries[entry_index]);
+                }
+
+                // mark as empty
+                bins[i] = BIN_RESERVED_VALUE_EMPTY;
+            }
+
+
+        }
+
+        this.#size = 0;
+
+        this.#entries_start = 0;
+        this.#entries_bound = 0;
     }
 
     * [Symbol.iterator]() {
-        let h, i, l;
 
-        const records = this.records;
+        const count = this.#bin_count;
 
-        for (h in records) {
-            if (!records.hasOwnProperty(h)) {
-                continue;
-            }
+        const bins = this.#bins;
+        const entries = this.#entries;
+
+        const start_version = this.#version;
 
-            const bucket = records[h];
+        for (let j = 0; j < count; j++) {
+            assert.equal(start_version, this.#version, 'HashMap modified during traversal');
 
-            for (i = 0, l = bucket.length; i < l; i++) {
-                /**
-                 * @type {MapEntry<K,V>}
-                 */
-                const entry = bucket[i];
+            const bin = bins[j];
 
-                yield  [entry.key, entry.value];
+            if (bin <= BIN_RESERVED_VALUE_DELETED) {
+                // unoccupied
+                continue;
             }
+
+            /**
+             * @type {MapEntry<K,V>}
+             */
+            const entry = entries[bin - ENTRY_BASE];
+
+            yield  [entry.key, entry.value];
         }
 
     }