@bradensbay/globals-core 0.2.0

package/dist/src/external.js

@@ -0,0 +1,68 @@
+import { ExternalRef } from "./values.js";
+export class ExternalTier {
+    #nextHandle = 1;
+    #owned = new Map();
+    #transport;
+    #cache = new Map();
+    /**
+     * @param transport How a reader fetches a value it does not own. Omitted in the owner,
+     * which holds every value itself.
+     */
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /** Owner side. Store a value and get a handle that can go into shared state. */
+    put(value) {
+        const handle = this.#nextHandle;
+        this.#nextHandle += 1;
+        this.#owned.set(handle, value);
+        return new ExternalRef(handle);
+    }
+    /** Owner side. Drop a value. Reading its handle afterwards rejects. */
+    drop(reference) {
+        const handle = typeof reference === "number" ? reference : reference.handle;
+        this.#cache.delete(handle);
+        return this.#owned.delete(handle);
+    }
+    /**
+     * Read a value. Asynchronous in every process, including the owner, so that moving code
+     * between the owner and a window does not change whether it compiles.
+     */
+    async get(reference) {
+        const handle = typeof reference === "number" ? reference : reference.handle;
+        if (this.#owned.has(handle))
+            return this.#owned.get(handle);
+        const pending = this.#cache.get(handle);
+        if (pending !== undefined)
+            return pending;
+        if (this.#transport === undefined) {
+            throw new Error(`external handle ${handle} is not held here and no transport was supplied. In a ` +
+                "reader, construct the tier with the transport the integration provides.");
+        }
+        const request = this.#transport.fetch(handle);
+        this.#cache.set(handle, request);
+        try {
+            return await request;
+        }
+        catch (error) {
+            this.#cache.delete(handle);
+            throw error;
+        }
+    }
+    /** Owner side. Serve a fetch from another process. */
+    serve(handle) {
+        if (!this.#owned.has(handle)) {
+            throw new Error(`external handle ${handle} is not held by this owner`);
+        }
+        return this.#owned.get(handle);
+    }
+    /** Forget every cached replica. Called when the owner generation changes. */
+    invalidate() {
+        this.#cache.clear();
+    }
+    get size() {
+        return this.#owned.size;
+    }
+}
+export { ExternalRef };
+//# sourceMappingURL=external.js.map

package/dist/src/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B1C,MAAM,OAAO,YAAY;IACvB,WAAW,GAAG,CAAC,CAAC;IACP,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;IACpC,UAAU,CAAgC;IAC1C,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEtD;;;OAGG;IACH,YAAY,SAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,gFAAgF;IAChF,GAAG,CAAC,KAAc;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAChC,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC/B,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,uEAAuE;IACvE,IAAI,CAAC,SAA+B;QAClC,MAAM,MAAM,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC;QAC5E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,SAA+B;QACvC,MAAM,MAAM,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC;QAE5E,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAE5D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC;QAE1C,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,wDAAwD;gBAC/E,yEAAyE,CAC5E,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,MAAc;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,4BAA4B,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,6EAA6E;IAC7E,UAAU;QACR,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/src/hamt.d.ts

@@ -0,0 +1,87 @@
+import type { SharedArena } from "./arena.js";
+import type { Allocator } from "./allocator.js";
+import type { Slot } from "./values.js";
+/**
+ * A hash array mapped trie, used for objects, maps, and sets.
+ *
+ * The point of it is structural sharing. Setting one field of an object with ten thousand
+ * keys copies the path from the root to that key, which is at most seven nodes, rather than
+ * the whole record. That is what keeps write cost logarithmic and makes retention of several
+ * versions affordable.
+ *
+ * Node layout, at the payload offset the allocator returns:
+ *
+ *   word 0   kind, BITMAP or COLLISION
+ *   BITMAP    word 1 dataMap, word 2 nodeMap
+ *             then popcount(dataMap) entries of three words: key tag, key payload, and a
+ *             value slot packed as two words
+ *             then popcount(nodeMap) child offsets, one word each
+ *   COLLISION word 1 entry count, word 2 the shared hash
+ *             then count entries of four words: key tag, key payload, value tag, value
+ *             payload
+ *
+ * An explicit kind word costs four bytes per node and buys two things: collision nodes are
+ * distinguishable without stealing a bitmap value, and a wild offset that happens to land on
+ * plausible bitmaps is rejected rather than walked.
+ */
+export declare const HAMT_BITMAP = 1213022720;
+export declare const HAMT_COLLISION = 1213022721;
+export declare const EMPTY_NODE = 0;
+/** The hash a key slot contributes to the trie. */
+export declare function keyHash(arena: SharedArena, key: Slot): number;
+/**
+ * Key equality, SameValueZero.
+ *
+ * Interned strings compare by offset, which is the whole reason for interning: an object
+ * property lookup is an integer compare rather than a character walk. Doubles have to be
+ * compared by value, because two equal doubles live in two different blocks.
+ */
+export declare function keyEquals(arena: SharedArena, a: Slot, b: Slot): boolean;
+export interface HamtContext {
+    readonly arena: SharedArena;
+    readonly allocator: Allocator;
+    /** Nodes replaced on the copied path. The commit retires them. */
+    readonly retired: number[];
+    /**
+     * Every block this operation allocated.
+     *
+     * A commit that fails part way releases these, so a rejected write leaks nothing. It is a
+     * separate list from the retired one on purpose: retired blocks belong to the previous
+     * version and must survive a rollback, allocated ones must not.
+     */
+    readonly allocated: number[];
+}
+export declare function emptyNode(context: HamtContext): number;
+/** Look a key up. Returns undefined when it is absent, which a null value slot cannot be. */
+export declare function hamtGet(arena: SharedArena, node: number, key: Slot, hash: number): Slot | undefined;
+/**
+ * Insert or replace a key, returning the new root of this subtree.
+ *
+ * Every node on the path from the root to the key is copied and the original is pushed onto
+ * the retired list. Nothing already published is mutated, which is what makes a reader
+ * holding an older root safe without any coordination.
+ */
+export declare function hamtAssoc(context: HamtContext, node: number, key: Slot, hash: number, value: Slot, shift?: number): number;
+/** Remove a key. Returns the node unchanged when the key is absent. */
+export declare function hamtDissoc(context: HamtContext, node: number, key: Slot, hash: number, shift?: number): number;
+export interface HamtEntry {
+    readonly key: Slot;
+    readonly value: Slot;
+}
+/** Every entry in the subtree. Order is the trie order, which is stable for a given set. */
+export declare function hamtEntries(arena: SharedArena, node: number, out?: HamtEntry[], depth?: number, budget?: number): HamtEntry[];
+export declare function hamtSize(arena: SharedArena, node: number, depth?: number): number;
+/** Every node in the subtree, for retiring a whole structure the writer is discarding. */
+export declare function hamtNodes(arena: SharedArena, node: number, out?: number[], depth?: number, budget?: number): number[];
+/** Property names of an object node, as strings. */
+export declare function hamtKeyStrings(arena: SharedArena, node: number): string[];
+/**
+ * Look a string key up without interning it first.
+ *
+ * A reader cannot intern, because interning is a write, so it cannot compare keys by offset
+ * the way the writer does. It can still walk the trie by hash and compare only the one
+ * record it lands on, which is the same logarithmic walk with a character comparison at the
+ * end instead of an integer one.
+ */
+export declare function hamtGetString(arena: SharedArena, node: number, text: string, hash: number): Slot | undefined;
+//# sourceMappingURL=hamt.d.ts.map

package/dist/src/hamt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hamt.d.ts","sourceRoot":"","sources":["../../src/hamt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,cAAc,aAAa,CAAC;AAazC,eAAO,MAAM,UAAU,IAAI,CAAC;AAa5B,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CA8B7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAqBvE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;CAC9B;AAgFD,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAgDnG;AAmED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,IAAI,EACX,KAAK,SAAI,GACR,MAAM,CA4JR;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,EACZ,KAAK,SAAI,GACR,MAAM,CAuFR;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB;AA0BD,4FAA4F;AAC5F,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,SAAS,EAAO,EACrB,KAAK,SAAI,EACT,MAAM,SAAyB,GAC9B,SAAS,EAAE,CA4Cb;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,CAc5E;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAM,EAAO,EAClB,KAAK,SAAI,EACT,MAAM,SAAyB,GAC9B,MAAM,EAAE,CAyBV;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,IAAI,GAAG,SAAS,CAyClB"}