@woosh/meep-engine 2.121.13 → 2.122.0

package/package.json

@@ -5,7 +5,7 @@
   "description": "Fully featured ECS game engine written in JavaScript",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.121.13",
+  "version": "2.122.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/binary/allocator/OffsetAllocator.d.ts

@@ -0,0 +1,113 @@
+export const ALLOCATOR_NO_SPACE: 4294967295;
+/**
+ * Fast hard realtime O(1) offset allocator with minimal fragmentation.
+ *
+ * Uses 256 bins with 8 bit floating point distribution (3 bit mantissa + 5 bit exponent) and a two level bitfield to find the next available bin using 2x LZCNT instructions to make all operations O(1). Bin sizes following the floating point distribution ensures hard bounds for memory overhead percentage regardless of size class. Pow2 bins would waste up to +100% memory (+50% on average). Our float bins waste up to +12.5% (+6.25% on average).
+ *
+ * The allocation metadata is stored in a separate data structure, making this allocator suitable for sub-allocating any resources, such as GPU heaps, buffers and arrays. Returns an offset to the first element of the allocated contiguous range.
+ *
+ * @see "A comparison of memory allocators for real-time applications" by Miguel Masmano et al
+ * @example
+ *      const allocator = new Allocator(12345);     // Allocator with 12345 contiguous elements in total
+ *
+ *      const a = allocator.allocate(1337);         // Allocate a 1337 element contiguous range
+ *      const offset_a = a.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_a);
+ *
+ *      const b = allocator.allocate(123);          // Allocate a 123 element contiguous range
+ *      const offset_b = b.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_b);
+ *
+ *      allocator.free(a);                          // Free allocation a
+ *      allocator.free(b);                          // Free allocation b
+ */
+export class OffsetAllocator {
+    /**
+     *
+     * @param {number} size
+     * @param {number} maxAllocs
+     */
+    constructor(size: number, maxAllocs?: number);
+    /**
+     * Total managed space
+     * uint32
+     * @type {number}
+     */
+    size: number;
+    /**
+     * Limit on number of allocations
+     * uint32
+     * @type {number}
+     */
+    maxAllocs: number;
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeStorage: number;
+    /**
+     * uint32
+     * @type {number}
+     */
+    usedBinsTop: number;
+    /**
+     *
+     * @type {Uint8Array}
+     */
+    usedBins: Uint8Array;
+    /**
+     *
+     * @type {Uint32Array}
+     */
+    binIndices: Uint32Array;
+    /**
+     *
+     * @type {RowFirstTable}
+     */
+    nodes: RowFirstTable;
+    /**
+     * @type {Uint32Array}
+     */
+    freeNodes: Uint32Array;
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeOffset: number;
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size: number): Allocation;
+    /**
+     *
+     * @param {Allocation} allocation
+     */
+    free(allocation: Allocation): void;
+    reset(): void;
+    /**
+     * Useful for debug and UI
+     * @return {StorageReport}
+     */
+    storageReport(): StorageReport;
+    #private;
+}
+import { RowFirstTable } from "../../collection/table/RowFirstTable.js";
+declare class Allocation {
+    /**
+     *
+     * @param {number} offset
+     * @param {number} metadata
+     * @return {Allocation}
+     */
+    static from(offset: number, metadata: number): Allocation;
+    offset: number;
+    metadata: number;
+}
+declare class StorageReport {
+    totalFreeSpace: number;
+    largestFreeRegion: number;
+}
+export {};
+//# sourceMappingURL=OffsetAllocator.d.ts.map

package/src/core/binary/allocator/OffsetAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAaA,iCAAkC,UAAU,CAAC;AAmF7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwDI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAtED;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAmBf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CAkGtB;IAED;;;OAGG;IACH,iBAFW,UAAU,QAsFpB;IAqID,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BA9jB6B,yCAAyC;AAgDvE;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAhBD,eAA4B;IAC5B,iBAA8B;CAgBjC;AAoBD;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}

package/src/core/binary/allocator/OffsetAllocator.js

@@ -0,0 +1,576 @@
+import { assert } from "../../assert.js";
+import { RowFirstTable } from "../../collection/table/RowFirstTable.js";
+import { RowFirstTableSpec } from "../../collection/table/RowFirstTableSpec.js";
+import { ctz32 } from "../ctz32.js";
+import { floatToUint, uintToFloatRoundDown, uintToFloatRoundUp } from "../float/SmallFloat.js";
+import { msb_32 } from "../msb_32.js";
+import { BinaryDataType } from "../type/BinaryDataType.js";
+
+const NUM_TOP_BINS = 32;
+const BINS_PER_LEAF = 8;
+const TOP_BINS_INDEX_SHIFT = 3;
+const LEAF_BINS_INDEX_MASK = 0x7;
+const NUM_LEAF_BINS = NUM_TOP_BINS * BINS_PER_LEAF;
+export const ALLOCATOR_NO_SPACE = 0xffffffff;
+const NODE_UNUSED = 0xffffffff
+
+/**
+ * Can potentially use u16, but number of allocation slots will be limited to 65k, so a severe limitation for little gain
+ * @type {BinaryDataType}
+ */
+const NODE_INDEX_DATA_TYPE = BinaryDataType.Uint32;
+
+const DEBUG_VERBOSE = false;
+
+/**
+ * @see https://github.com/sebbbi/OffsetAllocator/blob/3610a7377088b1e8c8f1525f458c96038a4e6fc0/offsetAllocator.hpp#L70
+ * @type {RowFirstTableSpec}
+ */
+const NODE_TABLE_SPEC = RowFirstTableSpec.get([
+    BinaryDataType.Uint32, // Data Offset
+    BinaryDataType.Uint32, // Data Size
+    NODE_INDEX_DATA_TYPE, // Bin List Prev
+    NODE_INDEX_DATA_TYPE, // Bin List Next
+    NODE_INDEX_DATA_TYPE, // Neighbour Prev
+    NODE_INDEX_DATA_TYPE, // Neighbour Next
+    BinaryDataType.Uint8, // FLAGS
+]);
+
+const NODE_FLAGS_USED = 1;
+
+
+const NODE_FIELD_DATA_OFFSET = 0;
+const NODE_FIELD_DATA_SIZE = 1;
+const NODE_FIELD_BIN_LIST_PREV = 2;
+const NODE_FIELD_BIN_LIST_NEXT = 3;
+const NODE_FIELD_NEIGHBOR_PREV = 4;
+const NODE_FIELD_NEIGHBOR_NEXT = 5;
+const NODE_FIELD_FLAGS = 6;
+
+class Allocation {
+    offset = ALLOCATOR_NO_SPACE;
+    metadata = ALLOCATOR_NO_SPACE;
+
+    /**
+     *
+     * @param {number} offset
+     * @param {number} metadata
+     * @return {Allocation}
+     */
+    static from(offset, metadata) {
+        const r = new Allocation();
+
+        r.offset = offset;
+        r.metadata = metadata;
+
+        return r;
+    }
+}
+
+/**
+ *
+ * @param {number} bitMask
+ * @param {number} startBitIndex
+ * @return {number}
+ */
+function findLowestSetBitAfter(bitMask, startBitIndex) {
+    const maskBeforeStartIndex = (1 << startBitIndex) - 1;
+    const maskAfterStartIndex = ~maskBeforeStartIndex;
+    const bitsAfter = bitMask & maskAfterStartIndex;
+
+    if (bitsAfter === 0) {
+        return ALLOCATOR_NO_SPACE;
+    }
+
+    return ctz32(bitsAfter);
+}
+
+class StorageReport {
+    totalFreeSpace = 0
+    largestFreeRegion = 0
+}
+
+/*
+Largely a port of https://github.com/sebbbi/OffsetAllocator by "Sebastian Aaltonen"
+ */
+
+/**
+ * Fast hard realtime O(1) offset allocator with minimal fragmentation.
+ *
+ * Uses 256 bins with 8 bit floating point distribution (3 bit mantissa + 5 bit exponent) and a two level bitfield to find the next available bin using 2x LZCNT instructions to make all operations O(1). Bin sizes following the floating point distribution ensures hard bounds for memory overhead percentage regardless of size class. Pow2 bins would waste up to +100% memory (+50% on average). Our float bins waste up to +12.5% (+6.25% on average).
+ *
+ * The allocation metadata is stored in a separate data structure, making this allocator suitable for sub-allocating any resources, such as GPU heaps, buffers and arrays. Returns an offset to the first element of the allocated contiguous range.
+ *
+ * @see "A comparison of memory allocators for real-time applications" by Miguel Masmano et al
+ * @example
+ *      const allocator = new Allocator(12345);     // Allocator with 12345 contiguous elements in total
+ *
+ *      const a = allocator.allocate(1337);         // Allocate a 1337 element contiguous range
+ *      const offset_a = a.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_a);
+ *
+ *      const b = allocator.allocate(123);          // Allocate a 123 element contiguous range
+ *      const offset_b = b.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_b);
+ *
+ *      allocator.free(a);                          // Free allocation a
+ *      allocator.free(b);                          // Free allocation b
+ */
+export class OffsetAllocator {
+    /**
+     * Total managed space
+     * uint32
+     * @type {number}
+     */
+    size = 0;
+
+    /**
+     * Limit on number of allocations
+     * uint32
+     * @type {number}
+     */
+    maxAllocs = 0;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeStorage = 0;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    usedBinsTop = 0;
+
+    /**
+     *
+     * @type {Uint8Array}
+     */
+    usedBins = new Uint8Array(NUM_TOP_BINS);
+
+    /**
+     *
+     * @type {Uint32Array}
+     */
+    binIndices = new Uint32Array(NUM_LEAF_BINS);
+
+    /**
+     *
+     * @type {RowFirstTable}
+     */
+    nodes = new RowFirstTable(NODE_TABLE_SPEC)
+
+    /**
+     * @type {Uint32Array}
+     */
+    freeNodes;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeOffset = 0;
+
+    /**
+     *
+     * @param {number} size
+     * @param {number} maxAllocs
+     */
+    constructor(size, maxAllocs = 128 * 1024) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.isNonNegativeInteger(maxAllocs, 'maxAllocs');
+
+        this.size = size;
+        this.maxAllocs = maxAllocs;
+
+        this.freeNodes = new Uint32Array(this.maxAllocs);
+
+        this.reset();
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size) {
+        assert.isNonNegativeInteger(size, 'size');
+
+        // Out of allocations?
+        if (this.freeOffset === 0) {
+            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+        }
+
+        // Round up to bin index to ensure that alloc >= bin
+        // Gives us min bin index that fits the size
+        let minBinIndex = uintToFloatRoundUp(size);
+
+        const minTopBinIndex = minBinIndex >>> TOP_BINS_INDEX_SHIFT;
+        const minLeafBinIndex = minBinIndex & LEAF_BINS_INDEX_MASK;
+
+        let topBinIndex = minTopBinIndex;
+        let leafBinIndex = ALLOCATOR_NO_SPACE;
+
+        // If top bin exists, scan its leaf bin. This can fail (NO_SPACE).
+        if ((this.usedBinsTop & (1 << topBinIndex)) !== 0) {
+            leafBinIndex = findLowestSetBitAfter(this.usedBins[topBinIndex], minLeafBinIndex);
+        }
+
+        // If we didn't find space in top bin, we search top bin from +1
+        if (leafBinIndex === ALLOCATOR_NO_SPACE) {
+            topBinIndex = findLowestSetBitAfter(this.usedBinsTop, minTopBinIndex + 1);
+
+            // Out of space?
+            if (topBinIndex === ALLOCATOR_NO_SPACE) {
+                return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+            }
+
+            // All leaf bins here fit the alloc, since the top bin was rounded up. Start leaf search from bit 0.
+            // NOTE: This search can't fail since at least one leaf bit was set because the top bit was set.
+            leafBinIndex = ctz32(this.usedBins[topBinIndex]);
+        }
+
+        let bin_index = ((topBinIndex << TOP_BINS_INDEX_SHIFT) | leafBinIndex) >>> 0; // ">>> 0" shift is to force UINT32
+
+        // Pop the top node of the bin. Bin top = node.next.
+        let node_index = this.binIndices[bin_index];
+
+        const nodes = this.nodes;
+
+        const nodeTotalSize = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_SIZE, size);
+        nodes.writeCellValue(node_index, NODE_FIELD_FLAGS, NODE_FLAGS_USED); //mark as USED
+
+        const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+        this.binIndices[bin_index] = node_bin_list_next;
+
+        if (node_bin_list_next !== NODE_UNUSED) {
+            nodes.writeCellValue(node_bin_list_next, NODE_FIELD_BIN_LIST_PREV, NODE_UNUSED);
+        }
+
+        this.freeStorage -= nodeTotalSize;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (-${nodeTotalSize}) (allocate)`);
+        }
+
+        // Bin empty?
+        if (this.binIndices[bin_index] === NODE_UNUSED) {
+            // Remove a leaf bin mask bit
+            this.usedBins[topBinIndex] &= ~(1 << leafBinIndex);
+
+            // All leaf bins empty?
+            if (this.usedBins[topBinIndex] === 0) {
+                // Remove a top bin mask bit
+                this.usedBinsTop &= ~(1 << topBinIndex);
+            }
+        }
+
+        // Push back reminder N elements to a lower bin
+        const reminderSize = nodeTotalSize - size;
+
+        const node_data_offset = nodes.readCellValue(node_index, NODE_FIELD_DATA_OFFSET);
+
+        if (reminderSize > 0) {
+            const new_node_index = this.#insertNodeIntoBin(reminderSize, node_data_offset + size);
+
+            const node_neighbor_next = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+            // Link nodes next to each other so that we can merge them later if both are free
+            // And update the old next neighbor to point to the new node (in middle)
+            if (node_neighbor_next !== NODE_UNUSED) {
+                nodes.writeCellValue(node_neighbor_next, NODE_FIELD_NEIGHBOR_PREV, new_node_index);
+            }
+            nodes.writeCellValue(new_node_index, NODE_FIELD_NEIGHBOR_PREV, node_index);
+            nodes.writeCellValue(new_node_index, NODE_FIELD_NEIGHBOR_NEXT, node_neighbor_next);
+
+            nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, new_node_index);
+        }
+
+
+        return Allocation.from(node_data_offset, node_index);
+    }
+
+    /**
+     *
+     * @param {Allocation} allocation
+     */
+    free(allocation) {
+        assert.notEqual(allocation.metadata, ALLOCATOR_NO_SPACE, 'Invalid allocation');
+        // if (!m_nodes) return;
+
+        const node_index = allocation.metadata;
+
+        const nodes = this.nodes;
+        const node_flags = nodes.readCellValue(node_index, NODE_FIELD_FLAGS);
+
+        // Double delete check
+        assert.notEqual(node_flags & NODE_FLAGS_USED, 0, 'Node is not in use');
+
+        // Merge with neighbors...
+        let offset = nodes.readCellValue(node_index, NODE_FIELD_DATA_OFFSET)
+        let size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+
+        const node_neighbour_prev = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV);
+
+        if (
+            (node_neighbour_prev !== NODE_UNUSED)
+            && ((nodes.readCellValue(node_neighbour_prev, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0) // not used
+        ) {
+            // Previous (contiguous) free node: Change offset to previous node offset. Sum sizes
+
+            const previous_offset = nodes.readCellValue(node_neighbour_prev, NODE_FIELD_DATA_OFFSET);
+            const previous_size = nodes.readCellValue(node_neighbour_prev, NODE_FIELD_DATA_SIZE);
+
+            offset = previous_offset;
+            size += previous_size;
+
+            // Remove node from the bin linked list and put it in the freelist
+            this.#removeNodeFromBin(node_neighbour_prev);
+
+            assert.equal(nodes.readCellValue(node_neighbour_prev, NODE_FIELD_NEIGHBOR_NEXT), node_index);
+
+            nodes.writeCellValue(
+                node_index, NODE_FIELD_NEIGHBOR_PREV,
+                nodes.readCellValue(node_neighbour_prev, NODE_FIELD_NEIGHBOR_PREV)
+            );
+        }
+
+        const node_neighbour_next = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+        if (
+            (node_neighbour_next !== NODE_UNUSED)
+            && ((nodes.readCellValue(node_neighbour_next, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0) // not used
+        ) {
+            // Next (contiguous) free node: Offset remains the same. Sum sizes.
+
+            size += nodes.readCellValue(node_neighbour_next, NODE_FIELD_DATA_SIZE);
+
+            // Remove node from the bin linked list and put it in the freelist
+            this.#removeNodeFromBin(node_neighbour_next);
+
+            assert.equal(nodes.readCellValue(node_neighbour_next, NODE_FIELD_NEIGHBOR_PREV), node_index);
+
+            nodes.writeCellValue(
+                node_index, NODE_FIELD_NEIGHBOR_NEXT,
+                nodes.readCellValue(node_neighbour_next, NODE_FIELD_NEIGHBOR_NEXT)
+            );
+        }
+
+        const neighborNext = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+        const neighborPrev = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV);
+
+        // Insert the removed node to freelist
+        if (DEBUG_VERBOSE) {
+            console.log(`Putting node ${node_index} into freelist[${this.freeOffset + 1}] (free)`);
+        }
+
+        this.freeNodes[++this.freeOffset] = node_index;
+
+        // Insert the (combined) free node to bin
+        const combinedNodeIndex = this.#insertNodeIntoBin(size, offset);
+
+        // Connect neighbors with the new combined node
+        if (neighborNext !== NODE_UNUSED) {
+            nodes.writeCellValue(combinedNodeIndex, NODE_FIELD_NEIGHBOR_NEXT, neighborNext);
+            nodes.writeCellValue(neighborNext, NODE_FIELD_NEIGHBOR_PREV, combinedNodeIndex);
+        }
+        if (neighborPrev !== NODE_UNUSED) {
+            nodes.writeCellValue(combinedNodeIndex, NODE_FIELD_NEIGHBOR_PREV, neighborPrev);
+            nodes.writeCellValue(neighborPrev, NODE_FIELD_NEIGHBOR_NEXT, combinedNodeIndex);
+        }
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @param {number} data_offset
+     * @returns {number}
+     */
+    #insertNodeIntoBin(size, data_offset) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.isNonNegativeInteger(data_offset, 'size');
+
+        // Round down to bin index to ensure that bin >= alloc
+        const bin_index = uintToFloatRoundDown(size);
+
+        const top_bin_index = bin_index >>> TOP_BINS_INDEX_SHIFT;
+        const leafBinIndex = bin_index & LEAF_BINS_INDEX_MASK;
+
+        // Bin was empty before?
+        if (this.binIndices[bin_index] === NODE_UNUSED) {
+            // Set bin mask bits
+            this.usedBins[top_bin_index] |= 1 << leafBinIndex;
+            this.usedBinsTop |= 1 << top_bin_index;
+        }
+
+        // Take a freelist node and insert on top of the bin linked list (next = old top)
+        const top_node_index = this.binIndices[bin_index];
+        const node_index = this.freeNodes[this.freeOffset--];
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Getting node ${node_index} from freelist[${this.freeOffset + 1}]`);
+        }
+
+        const nodes = this.nodes;
+
+        // initialize node
+
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_OFFSET, data_offset);
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_SIZE, size);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_BIN_LIST_PREV, NODE_UNUSED);
+        nodes.writeCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT, top_node_index);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV, NODE_UNUSED);
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, NODE_UNUSED);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_FLAGS, 0);
+
+        if (top_node_index !== NODE_UNUSED) {
+            nodes.writeCellValue(top_node_index, NODE_FIELD_BIN_LIST_PREV, node_index);
+        }
+
+        this.binIndices[bin_index] = node_index;
+
+        this.freeStorage += size;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (+${size}) (insertNodeIntoBin)`);
+        }
+
+        return node_index;
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     */
+    #removeNodeFromBin(node_index) {
+        assert.isNonNegativeInteger(node_index, 'node_index');
+
+        const nodes = this.nodes;
+        const node_bin_list_prev = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_PREV);
+        if (node_bin_list_prev !== NODE_UNUSED) {
+            // Easy case: We have previous node. Just remove this node from the middle of the list.
+            const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+            nodes.writeCellValue(
+                node_bin_list_prev, NODE_FIELD_BIN_LIST_NEXT,
+                node_bin_list_next
+            );
+
+            if (node_bin_list_next !== NODE_UNUSED) {
+                nodes.writeCellValue(
+                    node_bin_list_next, NODE_FIELD_BIN_LIST_PREV,
+                    node_bin_list_prev
+                )
+            }
+        } else {
+            // Hard case: We are the first node in a bin. Find the bin.
+
+            // Round down to bin index to ensure that bin >= alloc
+            const node_data_size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+            const binIndex = uintToFloatRoundDown(node_data_size);
+
+            const topBinIndex = binIndex >> TOP_BINS_INDEX_SHIFT;
+            const leafBinIndex = binIndex & LEAF_BINS_INDEX_MASK;
+
+            const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+            this.binIndices[binIndex] = node_bin_list_next;
+            if (node_bin_list_next !== NODE_UNUSED) {
+                nodes.writeCellValue(
+                    node_bin_list_next, NODE_FIELD_BIN_LIST_PREV,
+                    NODE_UNUSED
+                );
+            }
+
+            // Bin empty?
+            if (this.binIndices[binIndex] === NODE_UNUSED) {
+                // Remove a leaf bin mask bit
+                this.usedBins[topBinIndex] &= ~(1 << leafBinIndex);
+
+                // All leaf bins empty?
+                if (this.usedBins[topBinIndex] === 0) {
+                    // Remove a top bin mask bit
+                    this.usedBinsTop &= ~(1 << topBinIndex);
+                }
+            }
+        }
+
+        // Insert the node to freelist
+        if (DEBUG_VERBOSE) {
+            console.log(`Putting node ${node_index} into freelist[${this.freeOffset + 1}] (removeNodeFromBin)`);
+        }
+
+        this.freeNodes[++this.freeOffset] = node_index;
+
+        const node_data_size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+        this.freeStorage -= node_data_size;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (-${node_data_size}) (removeNodeFromBin)`);
+        }
+    }
+
+    reset() {
+        this.freeStorage = 0;
+        this.usedBinsTop = 0;
+
+        const maxAllocs = this.maxAllocs;
+
+        this.freeOffset = maxAllocs - 1;
+
+        for (let i = 0; i < NUM_TOP_BINS; i++) {
+            this.usedBins[i] = 0;
+        }
+        for (let i = 0; i < NUM_LEAF_BINS; i++) {
+            this.binIndices[i] = NODE_UNUSED;
+        }
+
+        // drop data from the node table
+        this.nodes.length = 0;
+        this.nodes.setCapacity(maxAllocs);
+
+        // Freelist is a stack. Nodes in inverse order so that [0] pops first.
+        for (let i = 0; i < maxAllocs; i++) {
+            this.freeNodes[i] = maxAllocs - i - 1;
+        }
+
+        // Start state: Whole storage as one big node
+        // Algorithm will split remainders and push them back as smaller nodes
+        this.#insertNodeIntoBin(this.size, 0);
+
+    }
+
+    /**
+     * Useful for debug and UI
+     * @return {StorageReport}
+     */
+    storageReport() {
+        let largestFreeRegion = 0;
+        let freeStorage = 0;
+
+        // Out of allocations? -> Zero free space
+        if (this.freeOffset > 0) {
+            freeStorage = this.freeStorage;
+
+            if (this.usedBinsTop !== 0) {
+                const topBinIndex = msb_32(this.usedBinsTop);
+                const leafBinIndex = msb_32(this.usedBins[topBinIndex]);
+
+                largestFreeRegion = floatToUint((topBinIndex << TOP_BINS_INDEX_SHIFT) | leafBinIndex);
+
+                assert.greaterThanOrEqual(freeStorage, largestFreeRegion);
+            }
+
+        }
+
+        const report = new StorageReport();
+
+        report.largestFreeRegion = largestFreeRegion;
+        report.totalFreeSpace = freeStorage;
+
+        return report;
+    }
+}

package/src/core/binary/float/SmallFloat.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bin sizes follow floating point (exponent + mantissa) distribution (piecewise linear log approx)
+ * This ensures that for each size class, the average overhead percentage stays the same
+ * @param {number} size
+ * @returns {number} uint32
+ */
+export function uintToFloatRoundUp(size: number): number;
+/**
+ *
+ * @param {number} size
+ * @return {number}
+ */
+export function uintToFloatRoundDown(size: number): number;
+/**
+ *
+ * @param {number} floatValue
+ * @return {number}
+ */
+export function floatToUint(floatValue: number): number;
+//# sourceMappingURL=SmallFloat.d.ts.map

package/src/core/binary/float/SmallFloat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmallFloat.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/float/SmallFloat.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,MAAM,CA0BlB;AAED;;;;GAIG;AACH,2CAHW,MAAM,GACL,MAAM,CAoBjB;AAED;;;;GAIG;AACH,wCAHW,MAAM,GACL,MAAM,CAcjB"}

package/src/core/binary/float/SmallFloat.js

@@ -0,0 +1,84 @@
+import { assert } from "../../assert.js";
+import { msb_32 } from "../msb_32.js";
+
+// TODO this has some overlap with `frexp` function behavior, perhaps we can generalize
+
+const MANTISSA_BITS = 3;
+const MANTISSA_VALUE = 1 << MANTISSA_BITS;
+const MANTISSA_MASK = MANTISSA_VALUE - 1;
+
+/**
+ * Bin sizes follow floating point (exponent + mantissa) distribution (piecewise linear log approx)
+ * This ensures that for each size class, the average overhead percentage stays the same
+ * @param {number} size
+ * @returns {number} uint32
+ */
+export function uintToFloatRoundUp(size) {
+    let exp = 0;
+    let mantissa = 0;
+
+    if (size < MANTISSA_VALUE) {
+        // Denorm: 0..(MANTISSA_VALUE-1)
+        mantissa = size;
+    } else {
+        // Normalized: Hidden high bit always 1. Not stored. Just like float.
+        const highestSetBit = msb_32(size);
+
+        const mantissaStartBit = highestSetBit - MANTISSA_BITS;
+        exp = mantissaStartBit + 1;
+        mantissa = (size >>> mantissaStartBit) & MANTISSA_MASK;
+
+        const lowBitsMask = (1 << mantissaStartBit) - 1;
+
+        // Round up!
+        if ((size & lowBitsMask) !== 0) {
+            mantissa++;
+        }
+    }
+
+    return (exp << MANTISSA_BITS) + mantissa; // + allows mantissa->exp overflow for round up
+}
+
+/**
+ *
+ * @param {number} size
+ * @return {number}
+ */
+export function uintToFloatRoundDown(size) {
+    let exp = 0;
+    let mantissa = 0;
+
+    if (size < MANTISSA_VALUE) {
+        // Denorm: 0..(MANTISSA_VALUE-1)
+        mantissa = size;
+    } else {
+        // Normalized: Hidden high bit always 1. Not stored. Just like float.
+        const highestSetBit = msb_32(size);
+
+        const mantissaStartBit = highestSetBit - MANTISSA_BITS;
+
+        exp = mantissaStartBit + 1;
+        mantissa = (size >>> mantissaStartBit) & MANTISSA_MASK;
+    }
+
+    return (exp << MANTISSA_BITS) | mantissa;
+}
+
+/**
+ *
+ * @param {number} floatValue
+ * @return {number}
+ */
+export function floatToUint(floatValue) {
+    assert.isNonNegativeInteger(floatValue, 'floatValue');
+
+    let exponent = floatValue >>> MANTISSA_BITS;
+    let mantissa = floatValue & MANTISSA_MASK;
+    if (exponent === 0) {
+        // Denorms
+        return mantissa;
+    } else {
+        const x = (mantissa | MANTISSA_VALUE) << (exponent - 1);
+        return x >>> 0; // convert to unsigned in case of sign overflow
+    }
+}

package/src/core/collection/table/RowFirstTable.d.ts

@@ -1,7 +1,11 @@
 /**
- * Compact binary table storage
- * Very efficient in terms of memory usage and allocation
- * You can think of it as an SQL table but only for numbers
+ * Compact binary table storage.
+ * Very efficient in terms of memory usage and allocation.
+ * Read and write speeds are optimized through code generation.
+ * You can think of it as an SQL table but only for numeric types.
+ *
+ * @copyright Company Named Limited (c) 2025
+ * @author Alex Goldring
  */
 export class RowFirstTable {
     /**
@@ -44,26 +48,8 @@ export class RowFirstTable {
         added: Signal;
     };
     /**
-     * @deprecated access directly via spec instead
-     * @return {BinaryDataType[]}
-     */
-    get types(): BinaryDataType[];
-    /**
-     * @deprecated access {@link RowFirstTableSpec#bytesPerRecord} directly instead
-     * @return {number}
-     */
-    get bytesPerRecord(): number;
-    /**
-     * @deprecated use {@link RowFirstTable.spec.readRowMethod} instead
-     * @return {function(DataView, number, number[]): void}
-     */
-    get readRowMethod(): (arg0: DataView, arg1: number, arg2: number[]) => void;
-    /**
-     @deprecated use {@link RowFirstTable.spec.writeRowMethod} instead
-     * @return {function(DataView, number, number[]): void}
-     */
-    get writeRowMethod(): (arg0: DataView, arg1: number, arg2: number[]) => void;
-    /**
+     * Useful for deserialization.
+     * This is an unsafe method, avoid using it if you are not sure.
      * NOTE: capacity is set automatically
      * NOTE: length is not set automatically, you have to do that yourself
      * @param {ArrayBuffer|SharedArrayBuffer} buffer
@@ -130,7 +116,7 @@ export class RowFirstTable {
      */
     addRow(values: Array<number>): number;
     /**
-     *
+     * @deprecated Use {@link addRow} and {@link setCapacity} instead
      * @param {number} count number of rows to be added
      * @param {function(row_index:number, row:Array.<number>):*} valueSupplier supplier of row values, called with row index and an empty row to be filled
      */
@@ -141,17 +127,6 @@ export class RowFirstTable {
      * @param {number} target
      */
     copyRow(source: number, target: number): void;
-    /**
-     * Copy data from another table. Specs must match.
-     * NOTE: does not send onAdded signal
-     * @param {RowFirstTable} other
-     */
-    copy(other: RowFirstTable): void;
-    /**
-     * @param {RowFirstTable} other
-     * @returns {boolean}
-     */
-    equals(other: RowFirstTable): boolean;
     /**
      * Read a single row of values from the table
      * @param {number} index
@@ -165,6 +140,14 @@ export class RowFirstTable {
      * @param {number[]} record
      */
     writeRow(index: number, record: number[]): void;
+    /**
+     * Sets memory region of the row to 0s.
+     * Useful for initializing dirty rows for re-use.
+     * If you have a specific value in mind - use {@link writeRow} method instead
+     * NOTE: All numeric types will produce a 0 after this, so every cell of this row will be 0
+     * @param {number} index
+     */
+    clearRow(index: number): void;
     /**
      * Reverse order of rows, row-0 will end up at and previously last row will become the first row etc.
      */
@@ -174,31 +157,27 @@ export class RowFirstTable {
      */
     clear(): void;
     /**
-     * @deprecated access {@link RowFirstTableSpec#getColumnCount} from spec instead
-     * @returns {number}
-     */
-    getNumColumns(): number;
-    /**
-     *
+     * Utility method. Returns table contents as a 2d array of [row][cell] form.
+     * Primarily useful for data conversion and debugging.
      * @returns {number[][]}
      */
     toRowArray(): number[][];
     /**
-     * Print the table to console
+     * Print the table to console.
+     * Useful for debugging.
      */
     printToConsole(): void;
     /**
-     * @deprecated
-     */
-    initialize(): void;
-    /**
-     * @deprecated use {@link RowFirstTable#readRow} instead
+     * Copy data from another table. Specs must match.
+     * NOTE: does not dispatch {@link onAdded} signal
+     * @param {RowFirstTable} other
      */
-    getRow: (index: number, result?: number[]) => number[];
+    copy(other: RowFirstTable): void;
     /**
-     @deprecated use {@link RowFirstTable#writeRow} instead
+     * @param {RowFirstTable} other
+     * @returns {boolean}
      */
-    setRow: (index: number, record: number[]) => void;
+    equals(other: RowFirstTable): boolean;
 }
 import Signal from "../../events/signal/Signal.js";
 //# sourceMappingURL=RowFirstTable.d.ts.map

package/src/core/collection/table/RowFirstTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RowFirstTable.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/table/RowFirstTable.js"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH;IACI;;;;;OAKG;IACH,kBAJW,iBAAiB,iBACjB,OAAO,EAiDjB;IAzCG;;;OAGG;IACH,MAFU,iBAAiB,CAEX;IAEhB;;;OAGG;IACH,MAFU,WAAW,CAE4D;IAEjF;;;OAGG;IACH,QAFU,MAAM,CAED;IAEf;;;OAGG;IACH,UAFU,MAAM,CAEgB;IAEhC;;;OAGG;IACH,UAFU,QAAQ,CAEqB;IAEvC;;;OAGG;IACH,IAFU;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAOxB;IAIL;;;OAGG;IACH,aAFY,cAAc,EAAE,CAI3B;IAED;;;OAGG;IACH,sBAFY,MAAM,CAIjB;IAED;;;OAGG;IACH,qBAFY,CAAS,IAAQ,EAAR,QAAQ,EAAE,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,IAAI,CAIrD;IAED;;;OAGG;IACH,sBAFY,CAAS,IAAQ,EAAR,QAAQ,EAAE,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,IAAI,CAIrD;IAGD;;;;OAIG;IACH,yBAFW,WAAW,GAAC,iBAAiB,EAQvC;IAED;;;OAGG;IACH,QAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH,sBAFW,MAAM,QAgDhB;IAED;;OAEG;IACH,aAEC;IAED;;;OAGG;IACH,kBAFW,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,gBACN,MAAM,SACN,MAAM,QAmBhB;IAED;;;;;OAKG;IACH,yBAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;OAIG;IACH,kBAHW,MAAM,aACN,MAAM,QAyBhB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,aACN,MAAM,QAwBhB;IAED;;;;;OAKG;IACH,kBAFY,MAAM,CAYjB;IAED;;;;OAIG;IACH,eAHW,KAAK,CAAE,MAAM,CAAC,GACZ,MAAM,CAYlB;IAED;;;;OAIG;IACH,eAHW,MAAM,4BA8ChB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,MAAM,QAwBhB;IAED;;;;OAIG;IACH,YAFW,aAAa,QAmBvB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CAmCnB;IAED;;;;;OAKG;IACH,eAJW,MAAM,WACN,MAAM,EAAE,GACN,MAAM,EAAE,CAUpB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,MAAM,EAAE,QAUlB;IAED;;OAEG;IACH,qBA4BC;IAED;;OAEG;IACH,cAIC;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,cAFa,MAAM,EAAE,EAAE,CAetB;IAED;;OAEG;IACH,uBAIC;IAED;;OAEG;IACH,mBAEC;IAGL;;OAEG;IACH,gBAtHe,MAAM,WACN,MAAM,EAAE,KACN,MAAM,EAAE,CAoHK;IAC9B;;OAEG;IACH,gBA1Ge,MAAM,UACN,MAAM,EAAE,UAyGO;CAT7B;mBAlpBkB,+BAA+B"}
+{"version":3,"file":"RowFirstTable.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/table/RowFirstTable.js"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH;IACI;;;;;OAKG;IACH,kBAJW,iBAAiB,iBACjB,OAAO,EAsDjB;IAzCG;;;OAGG;IACH,MAFU,iBAAiB,CAEX;IAEhB;;;OAGG;IACH,MAFU,WAAW,CAE4D;IAEjF;;;OAGG;IACH,QAFU,MAAM,CAED;IAEf;;;OAGG;IACH,UAFU,MAAM,CAEgB;IAEhC;;;OAGG;IACH,UAFU,QAAQ,CAEqB;IAEvC;;;OAGG;IACH,IAFU;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAOxB;IAKL;;;;;;OAMG;IACH,yBAFW,WAAW,GAAC,iBAAiB,EAQvC;IAED;;;OAGG;IACH,QAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH,sBAFW,MAAM,QAgDhB;IAED;;OAEG;IACH,aAEC;IAED;;;OAGG;IACH,kBAFW,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,gBACN,MAAM,SACN,MAAM,QAmBhB;IAED;;;;;OAKG;IACH,yBAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;OAIG;IACH,kBAHW,MAAM,aACN,MAAM,QAyBhB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,aACN,MAAM,QAwBhB;IAED;;;;;OAKG;IACH,kBAFY,MAAM,CAYjB;IAED;;;;OAIG;IACH,eAHW,KAAK,CAAE,MAAM,CAAC,GACZ,MAAM,CAYlB;IAED;;;;OAIG;IACH,eAHW,MAAM,4BA8ChB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,MAAM,QAwBhB;IAGD;;;;;OAKG;IACH,eAJW,MAAM,WACN,MAAM,EAAE,GACN,MAAM,EAAE,CAUpB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,MAAM,EAAE,QAUlB;IAED;;;;;;OAMG;IACH,gBAFW,MAAM,QAgBhB;IAED;;OAEG;IACH,qBA4BC;IAED;;OAEG;IACH,cAIC;IAED;;;;OAIG;IACH,cAFa,MAAM,EAAE,EAAE,CAetB;IAED;;;OAGG;IACH,uBAIC;IAED;;;;OAIG;IACH,YAFW,aAAa,QAmBvB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CAwCnB;CACJ;mBA7oBkB,+BAA+B"}

package/src/core/collection/table/RowFirstTable.js

@@ -30,9 +30,13 @@ const ALLOCATION_GROW_MINIMUM_STEP = 32;
 const ALLOCATION_SHRINK_FACTOR = 0.5;
 
 /**
- * Compact binary table storage
- * Very efficient in terms of memory usage and allocation
- * You can think of it as an SQL table but only for numbers
+ * Compact binary table storage.
+ * Very efficient in terms of memory usage and allocation.
+ * Read and write speeds are optimized through code generation.
+ * You can think of it as an SQL table but only for numeric types.
+ *
+ * @copyright Company Named Limited (c) 2025
+ * @author Alex Goldring
  */
 export class RowFirstTable {
     /**
@@ -41,11 +45,16 @@ export class RowFirstTable {
      * @param {boolean} [shared_array] should we use SharedArrayBuffer instead of ArrayBuffer?
      * @constructor
      */
-    constructor(spec, shared_array = false) {
+    constructor(
+        spec,
+        shared_array = false
+    ) {
         assert.defined(spec, 'spec');
         assert.notNull(spec, 'spec');
         assert.equal(spec.isRowFirstTableSpec, true, 'spec.isRowFirstTableSpec !== true');
 
+        assert.isBoolean(shared_array, 'shared_array');
+
         /**
          *
          * @type {RowFirstTableSpec}
@@ -89,40 +98,10 @@ export class RowFirstTable {
 
     }
 
-    /**
-     * @deprecated access directly via spec instead
-     * @return {BinaryDataType[]}
-     */
-    get types() {
-        return this.spec.types;
-    }
-
-    /**
-     * @deprecated access {@link RowFirstTableSpec#bytesPerRecord} directly instead
-     * @return {number}
-     */
-    get bytesPerRecord() {
-        return this.spec.bytesPerRecord;
-    }
-
-    /**
-     * @deprecated use {@link RowFirstTable.spec.readRowMethod} instead
-     * @return {function(DataView, number, number[]): void}
-     */
-    get readRowMethod() {
-        return this.spec.readRowMethod;
-    }
-
-    /**
-     @deprecated use {@link RowFirstTable.spec.writeRowMethod} instead
-     * @return {function(DataView, number, number[]): void}
-     */
-    get writeRowMethod() {
-        return this.spec.writeRowMethod;
-    }
-
 
     /**
+     * Useful for deserialization.
+     * This is an unsafe method, avoid using it if you are not sure.
      * NOTE: capacity is set automatically
      * NOTE: length is not set automatically, you have to do that yourself
      * @param {ArrayBuffer|SharedArrayBuffer} buffer
@@ -402,7 +381,7 @@ export class RowFirstTable {
     }
 
     /**
-     *
+     * @deprecated Use {@link addRow} and {@link setCapacity} instead
      * @param {number} count number of rows to be added
      * @param {function(row_index:number, row:Array.<number>):*} valueSupplier supplier of row values, called with row index and an empty row to be filled
      */
@@ -480,68 +459,6 @@ export class RowFirstTable {
         }
     }
 
-    /**
-     * Copy data from another table. Specs must match.
-     * NOTE: does not send onAdded signal
-     * @param {RowFirstTable} other
-     */
-    copy(other) {
-
-        // check that the spec is equivalent
-        if (!this.spec.equals(other.spec)) {
-            throw new Error('Different table specs');
-        }
-
-        const record_count = other.length;
-
-        this.resize(record_count);
-
-        this.length = other.length;
-
-        // copy data
-        const data_byte_count = other.spec.bytesPerRecord * record_count;
-
-        array_buffer_copy(other.data, 0, this.data, 0, data_byte_count);
-    }
-
-    /**
-     * @param {RowFirstTable} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            // shortcut
-            return true;
-        }
-
-        if (other === undefined || other === null) {
-            // this should not generally not happen
-            return false;
-        }
-
-        if (!this.spec.equals(other.spec)) {
-            return false;
-        }
-
-        const this_length = this.length;
-
-        if (this_length !== other.length) {
-            return false;
-        }
-
-        const total_bytes = this_length * this.spec.bytesPerRecord;
-
-        for (let i = 0; i < total_bytes; i++) {
-            const a = this.dataView.getUint8(i);
-            const b = other.dataView.getUint8(i);
-
-            if (a !== b) {
-                return false;
-            }
-        }
-
-        return true;
-    }
 
     /**
      * Read a single row of values from the table
@@ -574,6 +491,29 @@ export class RowFirstTable {
         spec.writeRowMethod(this.dataView, spec.bytesPerRecord * index, record);
     }
 
+    /**
+     * Sets memory region of the row to 0s.
+     * Useful for initializing dirty rows for re-use.
+     * If you have a specific value in mind - use {@link writeRow} method instead
+     * NOTE: All numeric types will produce a 0 after this, so every cell of this row will be 0
+     * @param {number} index
+     */
+    clearRow(index) {
+        assert.isNonNegativeInteger(index, 'index');
+
+        const spec = this.spec;
+
+        const bytesPerRecord = spec.bytesPerRecord;
+
+        const address = index * bytesPerRecord;
+
+        const dataView = this.dataView;
+
+        for (let i = 0; i < bytesPerRecord; i++) {
+            dataView.setUint8(address + i, 0);
+        }
+    }
+
     /**
      * Reverse order of rows, row-0 will end up at and previously last row will become the first row etc.
      */
@@ -617,15 +557,8 @@ export class RowFirstTable {
     }
 
     /**
-     * @deprecated access {@link RowFirstTableSpec#getColumnCount} from spec instead
-     * @returns {number}
-     */
-    getNumColumns() {
-        return this.spec.getColumnCount();
-    }
-
-    /**
-     *
+     * Utility method. Returns table contents as a 2d array of [row][cell] form.
+     * Primarily useful for data conversion and debugging.
      * @returns {number[][]}
      */
     toRowArray() {
@@ -644,7 +577,8 @@ export class RowFirstTable {
     }
 
     /**
-     * Print the table to console
+     * Print the table to console.
+     * Useful for debugging.
      */
     printToConsole() {
         const rows = this.toRowArray();
@@ -653,18 +587,70 @@ export class RowFirstTable {
     }
 
     /**
-     * @deprecated
+     * Copy data from another table. Specs must match.
+     * NOTE: does not dispatch {@link onAdded} signal
+     * @param {RowFirstTable} other
      */
-    initialize() {
-        console.warn('deprecated, no longer serves any purpose. Table no longer requires initialization')
+    copy(other) {
+
+        // check that the spec is equivalent
+        if (!this.spec.equals(other.spec)) {
+            throw new Error('Different table specs');
+        }
+
+        const record_count = other.length;
+
+        this.resize(record_count);
+
+        this.length = other.length;
+
+        // copy data
+        const data_byte_count = other.spec.bytesPerRecord * record_count;
+
+        array_buffer_copy(other.data, 0, this.data, 0, data_byte_count);
     }
-}
 
-/**
- * @deprecated use {@link RowFirstTable#readRow} instead
- */
-RowFirstTable.prototype.getRow = RowFirstTable.prototype.readRow;
-/**
- @deprecated use {@link RowFirstTable#writeRow} instead
- */
-RowFirstTable.prototype.setRow = RowFirstTable.prototype.writeRow;
+    /**
+     * @param {RowFirstTable} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            // shortcut
+            return true;
+        }
+
+        if (other === undefined || other === null) {
+            // this should not generally not happen
+            return false;
+        }
+
+        if (!this.spec.equals(other.spec)) {
+            return false;
+        }
+
+        const this_length = this.length;
+
+        if (this_length !== other.length) {
+            return false;
+        }
+
+        const total_bytes = this_length * this.spec.bytesPerRecord;
+
+        // TODO can use `is_array_buffer_equals` to speed this up
+
+        const this_data_view = this.dataView;
+        const other_data_view = other.dataView;
+
+        for (let i = 0; i < total_bytes; i++) {
+            const a = this_data_view.getUint8(i);
+            const b = other_data_view.getUint8(i);
+
+            if (a !== b) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}