@typeberry/lib 0.5.1 → 0.5.2-03e1aed

package/packages/core/collections/array-view.test.js

@@ -0,0 +1,49 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { deepEqual } from "#@typeberry/utils";
+import { ArrayView } from "./array-view.js";
+describe("ArrayView", () => {
+    const arr = [10, 20, 30, 40, 50];
+    it("creates a view from array", () => {
+        const view = ArrayView.from(arr, 1, 4);
+        assert.deepEqual(view.length, 3);
+        deepEqual([...view], [20, 30, 40]);
+    });
+    it("throws on invalid range", () => {
+        assert.throws(() => ArrayView.from(arr, -1, 3), /Invalid start \(-1\)\/end \(3\) for ArrayView/);
+        assert.throws(() => ArrayView.from(arr, 2, 10), /Invalid start \(2\)\/end \(10\) for ArrayView/);
+        assert.throws(() => ArrayView.from(arr, 4, 1), /Invalid start \(4\)\/end \(1\) for ArrayView/);
+    });
+    it("supports get()", () => {
+        const view = ArrayView.from(arr, 0, 3);
+        assert.equal(view.get(0), 10);
+        assert.equal(view.get(2), 30);
+        assert.throws(() => view.get(-1), /Index out of bounds./);
+        assert.throws(() => view.get(3), /Index out of bounds./);
+    });
+    it("creates subview correctly", () => {
+        const view = ArrayView.from(arr, 1, 5); // [20,30,40,50]
+        const sub = view.subview(1, 3); // [30,40]
+        deepEqual([...sub], [30, 40]);
+        assert.strictEqual(sub.length, 2);
+        const subToEnd = view.subview(2); // [40,50]
+        deepEqual([...subToEnd], [40, 50]);
+        assert.strictEqual(subToEnd.length, 2);
+    });
+    it("toArray() produces a copy", () => {
+        const view = ArrayView.from(arr, 1, 4);
+        const copy = view.toArray();
+        assert.deepEqual(copy, [20, 30, 40]);
+        copy[0] = 999;
+        assert.strictEqual(arr[1], 20);
+    });
+    it("works with for-of and spread", () => {
+        const view = ArrayView.from(arr, 2, 5); // [30,40,50]
+        const collected = [];
+        for (const x of view) {
+            collected.push(x);
+        }
+        deepEqual(collected, [30, 40, 50]);
+        deepEqual([...view], [30, 40, 50]);
+    });
+});

package/packages/core/collections/blob-dictionary.d.ts

@@ -0,0 +1,214 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import type { Comparator } from "#@typeberry/ordering";
+import { TEST_COMPARE_USING, WithDebug } from "#@typeberry/utils";
+/** A map which uses byte blobs as keys */
+export declare class BlobDictionary<K extends BytesBlob, V> extends WithDebug {
+    private mapNodeThreshold;
+    /**
+     * The root node of the dictionary.
+     *
+     * This is the main internal data structure that organizes entries
+     * in a tree-like fashion (array-based nodes up to `mapNodeThreshold`,
+     * map-based nodes beyond it). All insertions, updates, and deletions
+     * operate through this structure.
+     */
+    private root;
+    /**
+     * Auxiliary map that stores references to the original keys and their values.
+     *
+     * - Overriding a value in the main structure does not replace the original key reference.
+     * - Used for efficient iteration over `keys()`, `values()`, `entries()`, and computing `size`.
+     */
+    private keyvals;
+    /**
+     * Protected constructor used internally by `BlobDictionary.new`
+     * and `BlobDictionary.fromEntries`.
+     *
+     * This enforces controlled instantiation — users should create instances
+     * through the provided static factory methods instead of calling the
+     * constructor directly.
+     *
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     */
+    protected constructor(mapNodeThreshold: number);
+    /**
+     * Returns the number of entries in the dictionary.
+     *
+     * The count is derived from the auxiliary `keyvals` map, which stores
+     * all original key references and their associated values. This ensures
+     * that the `size` reflects the actual number of entries, independent of
+     * internal overrides in the main `root` structure.
+     *
+     * @returns The total number of entries in the dictionary.
+     */
+    get size(): number;
+    [TEST_COMPARE_USING](): [K, V][];
+    /**
+     * Creates an empty `BlobDictionary`.
+     *
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     * Defaults to `0`.
+     *
+     * @returns A new, empty `BlobDictionary` instance.
+     */
+    static new<K extends BytesBlob, V>(mapNodeThreshold?: number): BlobDictionary<K, V>;
+    /**
+     * Creates a new `BlobDictionary` initialized with the given entries.
+     *
+     * @param entries - An array of `[key, value]` pairs used to populate the dictionary.
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     * Defaults to `0`.
+     *
+     * @returns A new `BlobDictionary` containing the provided entries.
+     */
+    static fromEntries<K extends BytesBlob, V>(entries: [K, V][], mapNodeThreshold?: number): BlobDictionary<K, V>;
+    /**
+     * Internal helper that inserts, updates or deletes an entry in the dictionary.
+     *
+     * Behaviour details:
+     * - Passing `undefined` as `value` indicates a deletion. (E.g. `delete` uses `internalSet(key, undefined)`.)
+     * - When an add (new entry) or a delete actually changes the structure, the method returns the affected leaf node.
+     * - When the call only overrides an existing value (no structural add/delete), the method returns `null`.
+     *
+     * This method is intended for internal use by the dictionary implementation and allows `undefined` as a
+     * sentinel value to signal removals.
+     *
+     * @param key - The key to insert, update or remove.
+     * @param value - The value to associate with the key, or `undefined` to remove the key.
+     * @returns The leaf node created or removed on add/delete, or `null` if the operation only overwrote an existing value.
+     */
+    private internalSet;
+    /**
+     * Adds a new entry to the dictionary or updates the value of an existing key.
+     *
+     * If an entry with the given key already exists, its value is replaced
+     * with the new one.
+     *
+     * @param key - The key to add or update in the dictionary.
+     * @param value - The value to associate with the specified key.
+     * @returns Nothing (`void`).
+     */
+    set(key: K, value: V): void;
+    /**
+     * Retrieves the value associated with the given key from the dictionary.
+     *
+     * If the key does not exist, this method returns `undefined`.
+     *
+     * @param key - The key whose associated value should be retrieved.
+     * @returns The value associated with the specified key, or `undefined` if the key is not present.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Checks whether the dictionary contains an entry for the given key.
+     *
+     * ⚠️ **Note:** Avoid using `has(...)` together with `get(...)` in a pattern like this:
+     *
+     * ```ts
+     * if (dict.has(key)) {
+     *   const value = dict.get(key);
+     *   ...
+     * }
+     * ```
+     *
+     * This approach performs two lookups for the same key.
+     *
+     * Instead, prefer the following pattern, which retrieves the value once:
+     *
+     * ```ts
+     * const value = dict.get(key);
+     * if (value !== undefined) {
+     *   ...
+     * }
+     * ```
+     *
+     * @param key - The key to check for.
+     * @returns `true` if the dictionary contains an entry for the given key, otherwise `false`.
+     */
+    has(key: K): boolean;
+    /**
+     * Removes an entry with the specified key from the dictionary.
+     *
+     * Internally, this calls {@link internalSet} with `undefined` to mark the entry as deleted.
+     *
+     * @param key - The key of the entry to remove.
+     * @returns `true` if an entry was removed (i.e. the key existed), otherwise `false`.
+     */
+    delete(key: K): boolean;
+    /**
+     * Returns an iterator over the keys in the dictionary.
+     *
+     * The iterator yields each key in insertion order.
+     *
+     * @returns An iterator over all keys in the dictionary.
+     */
+    keys(): Iterator<K> & Iterable<K>;
+    /**
+     * Returns an iterator over the values in the dictionary.
+     *
+     * The iterator yields each value in insertion order.
+     *
+     * @returns An iterator over all values in the dictionary.
+     */
+    values(): Iterator<V> & Iterable<V>;
+    /**
+     * Returns an iterator over the `[key, value]` pairs in the dictionary.
+     *
+     * The iterator yields entries in insertion order.
+     *
+     * @returns An iterator over `[key, value]` tuples for each entry in the dictionary.
+     */
+    entries(): Iterator<[K, V]> & Iterable<[K, V]>;
+    /**
+     * Default iterator for the dictionary.
+     *
+     * Equivalent to calling {@link entries}.
+     * Enables iteration with `for...of`:
+     *
+     * ```ts
+     * for (const [key, value] of dict) {
+     *   ...
+     * }
+     * ```
+     *
+     * @returns An iterator over `[key, value]` pairs.
+     */
+    [Symbol.iterator](): Iterator<[K, V]> & Iterable<[K, V]>;
+    /**
+     * Creates a new sorted array of values, ordered by their corresponding keys.
+     *
+     * Iterates over all entries in the dictionary and sorts them according
+     * to the provided comparator function applied to the keys.
+     *
+     * @param comparator - A comparator function that can compare two keys.
+     *
+     * @returns A new array containing all values from the dictionary,
+     * sorted according to their keys.
+     */
+    toSortedArray(comparator: Comparator<K>): V[];
+}
+/**
+ * A function to transform a bytes chunk (up to 6 bytes into U48 number)
+ *
+ * Note that it uses 3 additional bits to store length(`value * 8 + len;`),
+ * It is needed to distinguish shorter chunks that have 0s at the end, for example: [1, 2] and [1, 2, 0]
+ * */
+export declare function bytesAsU48(bytes: Uint8Array): number;
+type SubKey<_K extends BytesBlob> = BytesBlob;
+type OriginalKeyRef<K> = K;
+type Leaf<K extends BytesBlob, V> = {
+    key: OriginalKeyRef<K>;
+    value: V;
+};
+export declare class ListChildren<K extends BytesBlob, V> {
+    children: [SubKey<K>, Leaf<K, V>][];
+    private constructor();
+    find(key: SubKey<K>): Leaf<K, V> | null;
+    remove(key: SubKey<K>): Leaf<K, V> | null;
+    insert(key: SubKey<K>, leaf: Leaf<K, V>): Leaf<K, V> | null;
+    static new<K extends BytesBlob, V>(): ListChildren<K, V>;
+}
+export {};
+//# sourceMappingURL=blob-dictionary.d.ts.map

package/packages/core/collections/blob-dictionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-dictionary.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/blob-dictionary.ts"],"names":[],"mappings":"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"}

package/packages/core/collections/blob-dictionary.js

@@ -0,0 +1,423 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { asOpaqueType, assertNever, check, TEST_COMPARE_USING, WithDebug } from "#@typeberry/utils";
+/** A map which uses byte blobs as keys */
+export class BlobDictionary extends WithDebug {
+    mapNodeThreshold;
+    /**
+     * The root node of the dictionary.
+     *
+     * This is the main internal data structure that organizes entries
+     * in a tree-like fashion (array-based nodes up to `mapNodeThreshold`,
+     * map-based nodes beyond it). All insertions, updates, and deletions
+     * operate through this structure.
+     */
+    root = Node.withList();
+    /**
+     * Auxiliary map that stores references to the original keys and their values.
+     *
+     * - Overriding a value in the main structure does not replace the original key reference.
+     * - Used for efficient iteration over `keys()`, `values()`, `entries()`, and computing `size`.
+     */
+    keyvals = new Map();
+    /**
+     * Protected constructor used internally by `BlobDictionary.new`
+     * and `BlobDictionary.fromEntries`.
+     *
+     * This enforces controlled instantiation — users should create instances
+     * through the provided static factory methods instead of calling the
+     * constructor directly.
+     *
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     */
+    constructor(mapNodeThreshold) {
+        super();
+        this.mapNodeThreshold = mapNodeThreshold;
+    }
+    /**
+     * Returns the number of entries in the dictionary.
+     *
+     * The count is derived from the auxiliary `keyvals` map, which stores
+     * all original key references and their associated values. This ensures
+     * that the `size` reflects the actual number of entries, independent of
+     * internal overrides in the main `root` structure.
+     *
+     * @returns The total number of entries in the dictionary.
+     */
+    get size() {
+        return this.keyvals.size;
+    }
+    [TEST_COMPARE_USING]() {
+        const vals = Array.from(this);
+        vals.sort((a, b) => a[0].compare(b[0]).value);
+        return vals;
+    }
+    /**
+     * Creates an empty `BlobDictionary`.
+     *
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     * Defaults to `0`.
+     *
+     * @returns A new, empty `BlobDictionary` instance.
+     */
+    static new(mapNodeThreshold = 0) {
+        return new BlobDictionary(mapNodeThreshold);
+    }
+    /**
+     * Creates a new `BlobDictionary` initialized with the given entries.
+     *
+     * @param entries - An array of `[key, value]` pairs used to populate the dictionary.
+     * @param mapNodeThreshold - The threshold that determines when the dictionary
+     * switches from using an array-based (`ListChildren`) node to a map-based (`MapChildren`) node for storing entries.
+     * Defaults to `0`.
+     *
+     * @returns A new `BlobDictionary` containing the provided entries.
+     */
+    static fromEntries(entries, mapNodeThreshold) {
+        const dict = BlobDictionary.new(mapNodeThreshold);
+        for (const [key, value] of entries) {
+            dict.set(key, value);
+        }
+        return dict;
+    }
+    /**
+     * Internal helper that inserts, updates or deletes an entry in the dictionary.
+     *
+     * Behaviour details:
+     * - Passing `undefined` as `value` indicates a deletion. (E.g. `delete` uses `internalSet(key, undefined)`.)
+     * - When an add (new entry) or a delete actually changes the structure, the method returns the affected leaf node.
+     * - When the call only overrides an existing value (no structural add/delete), the method returns `null`.
+     *
+     * This method is intended for internal use by the dictionary implementation and allows `undefined` as a
+     * sentinel value to signal removals.
+     *
+     * @param key - The key to insert, update or remove.
+     * @param value - The value to associate with the key, or `undefined` to remove the key.
+     * @returns The leaf node created or removed on add/delete, or `null` if the operation only overwrote an existing value.
+     */
+    internalSet(key, value) {
+        let node = this.root;
+        const keyChunkGenerator = key.chunks(CHUNK_SIZE);
+        let depth = 0;
+        for (;;) {
+            const maybeKeyChunk = keyChunkGenerator.next().value;
+            if (maybeKeyChunk === undefined) {
+                if (value === undefined) {
+                    return node.remove(key);
+                }
+                return node.set(key, value);
+            }
+            const keyChunk = asOpaqueType(maybeKeyChunk);
+            if (node.children instanceof ListChildren) {
+                const subkey = BytesBlob.blobFrom(key.raw.subarray(CHUNK_SIZE * depth));
+                const leaf = value !== undefined ? node.children.insert(subkey, { key, value }) : node.children.remove(subkey);
+                if (subkey.length > CHUNK_SIZE && node.children.children.length > this.mapNodeThreshold) {
+                    node.convertListChildrenToMap();
+                }
+                return leaf;
+            }
+            depth += 1;
+            const children = node.children;
+            if (children instanceof ListChildren) {
+                throw new Error("We handle list node earlier. If we fall through, we know it's for the `Map` case.");
+            }
+            if (children instanceof MapChildren) {
+                const maybeNode = children.getChild(keyChunk);
+                if (maybeNode !== undefined) {
+                    // simply go one level deeper
+                    node = maybeNode;
+                }
+                else {
+                    // we are trying to remove an item, but it does not exist
+                    if (value === undefined) {
+                        return null;
+                    }
+                    // no more child nodes, we insert a new one.
+                    const newNode = Node.withList();
+                    children.setChild(keyChunk, newNode);
+                    node = newNode;
+                }
+                continue;
+            }
+            assertNever(children);
+        }
+    }
+    /**
+     * Adds a new entry to the dictionary or updates the value of an existing key.
+     *
+     * If an entry with the given key already exists, its value is replaced
+     * with the new one.
+     *
+     * @param key - The key to add or update in the dictionary.
+     * @param value - The value to associate with the specified key.
+     * @returns Nothing (`void`).
+     */
+    set(key, value) {
+        const leaf = this.internalSet(key, value);
+        if (leaf !== null) {
+            this.keyvals.set(leaf.key, leaf);
+        }
+    }
+    /**
+     * Retrieves the value associated with the given key from the dictionary.
+     *
+     * If the key does not exist, this method returns `undefined`.
+     *
+     * @param key - The key whose associated value should be retrieved.
+     * @returns The value associated with the specified key, or `undefined` if the key is not present.
+     */
+    get(key) {
+        let node = this.root;
+        const pathChunksGenerator = key.chunks(CHUNK_SIZE);
+        let depth = 0;
+        while (node !== undefined) {
+            const maybePathChunk = pathChunksGenerator.next().value;
+            if (node.children instanceof ListChildren) {
+                const subkey = BytesBlob.blobFrom(key.raw.subarray(depth * CHUNK_SIZE));
+                const child = node.children.find(subkey);
+                if (child !== null) {
+                    return child.value;
+                }
+            }
+            if (maybePathChunk === undefined) {
+                return node.getLeaf()?.value;
+            }
+            if (node.children instanceof MapChildren) {
+                const pathChunk = asOpaqueType(maybePathChunk);
+                node = node.children.getChild(pathChunk);
+                depth += 1;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Checks whether the dictionary contains an entry for the given key.
+     *
+     * ⚠️ **Note:** Avoid using `has(...)` together with `get(...)` in a pattern like this:
+     *
+     * ```ts
+     * if (dict.has(key)) {
+     *   const value = dict.get(key);
+     *   ...
+     * }
+     * ```
+     *
+     * This approach performs two lookups for the same key.
+     *
+     * Instead, prefer the following pattern, which retrieves the value once:
+     *
+     * ```ts
+     * const value = dict.get(key);
+     * if (value !== undefined) {
+     *   ...
+     * }
+     * ```
+     *
+     * @param key - The key to check for.
+     * @returns `true` if the dictionary contains an entry for the given key, otherwise `false`.
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Removes an entry with the specified key from the dictionary.
+     *
+     * Internally, this calls {@link internalSet} with `undefined` to mark the entry as deleted.
+     *
+     * @param key - The key of the entry to remove.
+     * @returns `true` if an entry was removed (i.e. the key existed), otherwise `false`.
+     */
+    delete(key) {
+        const leaf = this.internalSet(key, undefined);
+        if (leaf !== null) {
+            this.keyvals.delete(leaf.key);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Returns an iterator over the keys in the dictionary.
+     *
+     * The iterator yields each key in insertion order.
+     *
+     * @returns An iterator over all keys in the dictionary.
+     */
+    keys() {
+        return this.keyvals.keys();
+    }
+    /**
+     * Returns an iterator over the values in the dictionary.
+     *
+     * The iterator yields each value in insertion order.
+     *
+     * @returns An iterator over all values in the dictionary.
+     */
+    *values() {
+        for (const leaf of this.keyvals.values()) {
+            yield leaf.value;
+        }
+    }
+    /**
+     * Returns an iterator over the `[key, value]` pairs in the dictionary.
+     *
+     * The iterator yields entries in insertion order.
+     *
+     * @returns An iterator over `[key, value]` tuples for each entry in the dictionary.
+     */
+    *entries() {
+        for (const leaf of this.keyvals.values()) {
+            yield [leaf.key, leaf.value];
+        }
+    }
+    /**
+     * Default iterator for the dictionary.
+     *
+     * Equivalent to calling {@link entries}.
+     * Enables iteration with `for...of`:
+     *
+     * ```ts
+     * for (const [key, value] of dict) {
+     *   ...
+     * }
+     * ```
+     *
+     * @returns An iterator over `[key, value]` pairs.
+     */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    /**
+     * Creates a new sorted array of values, ordered by their corresponding keys.
+     *
+     * Iterates over all entries in the dictionary and sorts them according
+     * to the provided comparator function applied to the keys.
+     *
+     * @param comparator - A comparator function that can compare two keys.
+     *
+     * @returns A new array containing all values from the dictionary,
+     * sorted according to their keys.
+     */
+    toSortedArray(comparator) {
+        const vals = Array.from(this);
+        vals.sort((a, b) => comparator(a[0], b[0]).value);
+        return vals.map((x) => x[1]);
+    }
+}
+const CHUNK_SIZE = 6;
+/**
+ * A function to transform a bytes chunk (up to 6 bytes into U48 number)
+ *
+ * Note that it uses 3 additional bits to store length(`value * 8 + len;`),
+ * It is needed to distinguish shorter chunks that have 0s at the end, for example: [1, 2] and [1, 2, 0]
+ * */
+export function bytesAsU48(bytes) {
+    const len = bytes.length;
+    check `${len <= CHUNK_SIZE} Length has to be <= ${CHUNK_SIZE}, got: ${len}`;
+    let value = bytes[3] | (bytes[2] << 8) | (bytes[1] << 16) | (bytes[0] << 24);
+    for (let i = 4; i < bytes.length; i++) {
+        value = value * 256 + bytes[i];
+    }
+    return value * 8 + len;
+}
+class Node {
+    leaf;
+    children;
+    convertListChildrenToMap() {
+        if (!(this.children instanceof ListChildren)) {
+            return;
+        }
+        this.children = MapChildren.fromListNode(this.children);
+    }
+    static withList() {
+        return new Node(undefined, ListChildren.new());
+    }
+    static withMap() {
+        return new Node(undefined, MapChildren.new());
+    }
+    constructor(leaf, children) {
+        this.leaf = leaf;
+        this.children = children;
+    }
+    getLeaf() {
+        return this.leaf;
+    }
+    remove(_key) {
+        if (this.leaf === undefined) {
+            return null;
+        }
+        const removedLeaf = this.leaf;
+        this.leaf = undefined;
+        return removedLeaf;
+    }
+    set(key, value) {
+        if (this.leaf === undefined) {
+            this.leaf = { key, value };
+            return this.leaf;
+        }
+        this.leaf.value = value;
+        return null;
+    }
+}
+export class ListChildren {
+    children = [];
+    constructor() { }
+    find(key) {
+        const result = this.children.find((item) => item[0].isEqualTo(key));
+        if (result !== undefined) {
+            return result[1];
+        }
+        return null;
+    }
+    remove(key) {
+        const existingIndex = this.children.findIndex((item) => item[0].isEqualTo(key));
+        if (existingIndex >= 0) {
+            const ret = this.children.splice(existingIndex, 1);
+            return ret[0][1];
+        }
+        return null;
+    }
+    insert(key, leaf) {
+        const existingIndex = this.children.findIndex((item) => item[0].isEqualTo(key));
+        if (existingIndex >= 0) {
+            const existing = this.children[existingIndex];
+            existing[1].value = leaf.value;
+            return null;
+        }
+        this.children.push([key, leaf]);
+        return leaf;
+    }
+    static new() {
+        return new ListChildren();
+    }
+}
+class MapChildren {
+    children = new Map();
+    constructor() { }
+    static new() {
+        return new MapChildren();
+    }
+    static fromListNode(node) {
+        const mapNode = new MapChildren();
+        for (const [key, leaf] of node.children) {
+            const currentKeyChunk = asOpaqueType(BytesBlob.blobFrom(key.raw.subarray(0, CHUNK_SIZE)));
+            const subKey = BytesBlob.blobFrom(key.raw.subarray(CHUNK_SIZE));
+            let child = mapNode.getChild(currentKeyChunk);
+            if (child === undefined) {
+                child = Node.withList();
+                mapNode.setChild(currentKeyChunk, child);
+            }
+            const children = child.children;
+            children.insert(subKey, leaf);
+        }
+        return mapNode;
+    }
+    getChild(keyChunk) {
+        const chunkAsNumber = bytesAsU48(keyChunk.raw);
+        return this.children.get(chunkAsNumber);
+    }
+    setChild(keyChunk, node) {
+        const chunkAsNumber = bytesAsU48(keyChunk.raw);
+        this.children.set(chunkAsNumber, node);
+    }
+}

package/packages/core/collections/blob-dictionary.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blob-dictionary.test.d.ts.map

package/packages/core/collections/blob-dictionary.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-dictionary.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/blob-dictionary.test.ts"],"names":[],"mappings":""}