@bradensbay/globals-core 0.2.0

package/dist/src/retained.js

@@ -0,0 +1,99 @@
+import { Header, RETAINED_SLOT_WORDS, RetainedSlot, RetainedState, WORD, } from "./layout.js";
+/**
+ * The retained version ring.
+ *
+ * The owner appends one entry per commit. Readers only read it, and they read it for one
+ * reason: to prove that the version they are pinned to is still live before they decode
+ * anything through it.
+ *
+ * The ring is bounded on purpose. A reader that stops advancing cannot pin memory forever,
+ * because once the ring wraps the owner force reclaims the oldest entry and that reader
+ * fails closed on its next decode. Unbounded retention would be the alternative, and it
+ * turns one frozen window into an out of memory crash for the whole application.
+ */
+export class RetainedRing {
+    #arena;
+    constructor(arena) {
+        this.#arena = arena;
+    }
+    get capacity() {
+        return this.#arena.geometry.retainedCapacity;
+    }
+    #wordIndex(index, field) {
+        return (this.#arena.geometry.retainedRingOffset / WORD + index * RETAINED_SLOT_WORDS + field);
+    }
+    #indexFor(versionId) {
+        // Version ids start at 1 and never wrap in practice: at one commit per millisecond a
+        // 32 bit counter lasts 24 days, and the owner refuses to commit past the limit rather
+        // than wrapping into ambiguity.
+        return (versionId - 1) % this.capacity;
+    }
+    /** Owner only. Publish a version into the ring, overwriting the entry it wraps onto. */
+    publish(versionId, rootTag, rootPayload) {
+        const words = this.#arena.words;
+        const index = this.#indexFor(versionId);
+        // Order matters: clear the state first so a reader cannot observe a new version id
+        // beside the previous entry's root.
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.State), RetainedState.Empty);
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.RootTag), rootTag);
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.RootPayload), rootPayload);
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.VersionId), versionId);
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.State), RetainedState.Live);
+    }
+    /** Owner only. Mark a version reclaimed. `forced` records that a reader was still pinned. */
+    retire(versionId, forced) {
+        const index = this.#indexFor(versionId);
+        const words = this.#arena.words;
+        if (Atomics.load(words, this.#wordIndex(index, RetainedSlot.VersionId)) !== versionId)
+            return;
+        Atomics.store(words, this.#wordIndex(index, RetainedSlot.State), forced ? RetainedState.ForceReclaimed : RetainedState.Reclaimed);
+    }
+    /**
+     * The check every reader runs after publishing its epoch. Returns true only when the
+     * version is still live in the ring, which proves the owner has not reclaimed the memory
+     * beneath it.
+     */
+    isLive(versionId) {
+        if (versionId <= 0)
+            return false;
+        const words = this.#arena.words;
+        const index = this.#indexFor(versionId);
+        return (Atomics.load(words, this.#wordIndex(index, RetainedSlot.VersionId)) === versionId &&
+            Atomics.load(words, this.#wordIndex(index, RetainedSlot.State)) === RetainedState.Live);
+    }
+    read(versionId) {
+        const words = this.#arena.words;
+        const index = this.#indexFor(versionId);
+        if (Atomics.load(words, this.#wordIndex(index, RetainedSlot.VersionId)) !== versionId) {
+            return undefined;
+        }
+        return {
+            versionId,
+            rootTag: Atomics.load(words, this.#wordIndex(index, RetainedSlot.RootTag)),
+            rootPayload: Atomics.load(words, this.#wordIndex(index, RetainedSlot.RootPayload)),
+            state: Atomics.load(words, this.#wordIndex(index, RetainedSlot.State)),
+        };
+    }
+    /** Live versions, oldest first. Diagnostics and the debug panel use this. */
+    live() {
+        const words = this.#arena.words;
+        const out = [];
+        for (let index = 0; index < this.capacity; index += 1) {
+            if (Atomics.load(words, this.#wordIndex(index, RetainedSlot.State)) !== RetainedState.Live) {
+                continue;
+            }
+            out.push({
+                versionId: Atomics.load(words, this.#wordIndex(index, RetainedSlot.VersionId)),
+                rootTag: Atomics.load(words, this.#wordIndex(index, RetainedSlot.RootTag)),
+                rootPayload: Atomics.load(words, this.#wordIndex(index, RetainedSlot.RootPayload)),
+                state: RetainedState.Live,
+            });
+        }
+        out.sort((a, b) => a.versionId - b.versionId);
+        return out;
+    }
+    reclaimFloor() {
+        return this.#arena.loadHeader(Header.ReclaimFloor);
+    }
+}
+//# sourceMappingURL=retained.js.map

package/dist/src/retained.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retained.js","sourceRoot":"","sources":["../../src/retained.ts"],"names":[],"mappings":"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"}

package/dist/src/schema.d.ts

@@ -0,0 +1,82 @@
+import type { Snapshot } from "./reader.js";
+/**
+ * Types.
+ *
+ * Two jobs, and the second one matters more than the first.
+ *
+ * The first is inference: declare the shape once and get typed reads without casting at
+ * every call site.
+ *
+ * The second is making the contract visible in the types. A synchronous read and an
+ * asynchronous write must not look alike, because the entire class of bug this library
+ * invites is reading straight after writing and expecting the new value. So a write returns
+ * a promise, always, even where an implementation could resolve it immediately.
+ */
+/** The values the type ladder can encode. Anything else needs the asynchronous tier. */
+export type Encodable = string | number | boolean | null | undefined | bigint | Date | RegExp | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array | Encodable[] | {
+    [key: string]: Encodable;
+} | Map<string | number | boolean | null, Encodable> | Set<string | number | boolean | null>;
+/** A state shape this library can hold. */
+export type StateShape = {
+    [key: string]: Encodable;
+};
+/** Deeply readonly, which is what a snapshot is. */
+export type Immutable<T> = T extends (infer Element)[] ? readonly Immutable<Element>[] : T extends Map<infer K, infer V> ? ReadonlyMap<K, Immutable<V>> : T extends Set<infer M> ? ReadonlySet<M> : T extends Date | RegExp | ArrayBufferView ? T : T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
+/** Mutable, which is what a draft is. */
+export type Draft<T> = T extends (infer Element)[] ? Draft<Element>[] : T extends Map<infer K, infer V> ? Map<K, Draft<V>> : T extends Set<infer M> ? Set<M> : T extends Date | RegExp | ArrayBufferView ? T : T extends object ? {
+    -readonly [K in keyof T]: Draft<T[K]>;
+} : T;
+/**
+ * A typed read side store.
+ *
+ * Every method here is synchronous, and there is no method that writes. A window holding one
+ * of these cannot write by accident, because there is nothing to call.
+ */
+export interface TypedReadableStore<State extends StateShape> {
+    get(): Immutable<State>;
+    select<T>(path: readonly (string | number)[]): T | undefined;
+    snapshot(): Snapshot;
+    subscribe(listener: () => void): () => void;
+    readonly version: number;
+}
+/**
+ * A typed write side store.
+ *
+ * `update` and `set` return promises. That is not an implementation detail leaking into the
+ * type: it is the contract. A write is serialised by the owner, so the value is not
+ * observable on the next line, and a signature that returned a version synchronously would
+ * be a lie that costs somebody a day.
+ */
+export interface TypedWritableStore<State extends StateShape> extends TypedReadableStore<State> {
+    update(recipe: (draft: Draft<State>) => void): Promise<number>;
+    set(value: State): Promise<number>;
+}
+/**
+ * A named write, as a window sends it.
+ *
+ * Functions cannot cross a process boundary, so a window sends the name of an operation and
+ * a payload. Declaring the operations as a type gives the dispatch call site the same
+ * checking a direct call would have had.
+ */
+export type OperationMap<State extends StateShape> = Record<string, (draft: Draft<State>, payload: never) => void>;
+export type PayloadOf<Operations extends OperationMap<StateShape>, Name extends keyof Operations> = Operations[Name] extends (draft: never, payload: infer Payload) => void ? Payload : never;
+/** A dispatcher typed against the operations the owner registered. */
+export interface TypedDispatcher<Operations extends OperationMap<StateShape>> {
+    <Name extends keyof Operations & string>(operation: Name, payload: PayloadOf<Operations, Name>): Promise<number>;
+}
+/**
+ * Declare a schema.
+ *
+ * Purely a type level helper: it returns its argument and exists so a state shape and its
+ * operations can be declared in one place and referenced by type everywhere else.
+ *
+ *     const schema = defineSchema<AppState>()({
+ *       increment: (draft, payload: { by: number }) => { draft.count += payload.by; },
+ *     });
+ *
+ *     type Dispatch = TypedDispatcher<typeof schema>;
+ */
+export declare function defineSchema<State extends StateShape>(): <Operations extends OperationMap<State>>(definitions: Operations) => Operations;
+//# sourceMappingURL=schema.d.ts.map

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

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

package/dist/src/schema.js

@@ -0,0 +1,18 @@
+/**
+ * Declare a schema.
+ *
+ * Purely a type level helper: it returns its argument and exists so a state shape and its
+ * operations can be declared in one place and referenced by type everywhere else.
+ *
+ *     const schema = defineSchema<AppState>()({
+ *       increment: (draft, payload: { by: number }) => { draft.count += payload.by; },
+ *     });
+ *
+ *     type Dispatch = TypedDispatcher<typeof schema>;
+ */
+export function defineSchema() {
+    return function operations(definitions) {
+        return definitions;
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAwHA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,UAAU,CACxB,WAAuB;QAEvB,OAAO,WAAW,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/store.d.ts

@@ -0,0 +1,83 @@
+import { ArenaOwner, type OwnerOptions, type OwnerStats } from "./owner.js";
+import { ArenaReader, type ReaderOptions, type Snapshot } from "./reader.js";
+/**
+ * The pair of interfaces the framework bindings and the Electron integration are written
+ * against.
+ *
+ * Splitting reading from writing in the type system is the point. A window holds a
+ * `ReadableStore`, which has no way to write, and the owner holds a `WritableStore`. Code
+ * that wants to write has to say so, and the asynchrony is in the return type where the
+ * caller can see it.
+ */
+export interface ReadableStore {
+    /** The current committed value, synchronously. No await, no round trip. */
+    get(): unknown;
+    /** Read one path without materialising the nodes along it. */
+    select(path: readonly (string | number)[]): unknown;
+    /** Pin the current version. Release it when you are finished, or hold it for a render. */
+    snapshot(): Snapshot;
+    /** Called after every commit. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** The version currently published. */
+    readonly version: number;
+}
+export interface WritableStore extends ReadableStore {
+    /**
+     * Apply a recipe to a draft and commit the result.
+     *
+     * The promise resolves once the write is committed and observable. Reading before it
+     * resolves may return the old value, which is the contract rather than a defect.
+     */
+    update<T>(recipe: (draft: T) => void): Promise<number>;
+    /** Replace the root outright. Asynchronous for the same reason update is. */
+    set(value: unknown): Promise<number>;
+}
+/**
+ * The owner side store.
+ *
+ * Writes are queued and applied in order, and the promise resolves after the commit is
+ * published. Queuing rather than applying inline means a recipe cannot observe a half
+ * applied earlier write, and it makes the total order the contract promises explicit rather
+ * than incidental.
+ */
+export declare class OwnerStore implements WritableStore {
+    #private;
+    readonly owner: ArenaOwner;
+    private constructor();
+    static create(initial: unknown, options?: OwnerOptions): OwnerStore;
+    get buffer(): SharedArrayBuffer;
+    get version(): number;
+    get(): unknown;
+    select(path: readonly (string | number)[]): unknown;
+    snapshot(): Snapshot;
+    update<T>(recipe: (draft: T) => void): Promise<number>;
+    set(value: unknown): Promise<number>;
+    subscribe(listener: () => void): () => void;
+    close(): void;
+}
+/**
+ * The reader side store.
+ *
+ * It has no write method at all. A window that needs to write does it through the intent
+ * channel the integration supplies, which is asynchronous by construction.
+ */
+export declare class ReaderStore implements ReadableStore {
+    #private;
+    readonly reader: ArenaReader;
+    constructor(buffer: SharedArrayBuffer, options?: ReaderOptions);
+    get version(): number;
+    get(): unknown;
+    select(path: readonly (string | number)[]): unknown;
+    snapshot(): Snapshot;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Tell the store a commit happened.
+     *
+     * The integration calls this when the owner notifies it. Deliberately not a poll: nothing
+     * on the read path may depend on a message arriving, so this only drives rerenders.
+     */
+    notify(): void;
+    close(): void;
+}
+export type { OwnerStats, Snapshot };
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE7E;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,GAAG,IAAI,OAAO,CAAC;IACf,8DAA8D;IAC9D,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC;IACpD,0FAA0F;IAC1F,QAAQ,IAAI,QAAQ,CAAC;IACrB,kEAAkE;IAClE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,6EAA6E;IAC7E,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,qBAAa,UAAW,YAAW,aAAa;;IAC9C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAI3B,OAAO,eAEN;IAED,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,UAAU,CAItE;IAED,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,GAAG,IAAI,OAAO,CAEb;IAED,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAElD;IAED,QAAQ,IAAI,QAAQ,CAEnB;IAaD,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAErD;IAED,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnC;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAkBD,KAAK,IAAI,IAAI,CAIZ;CACF;AAED;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,aAAa;;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAI7B,YAAY,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,aAAkB,EAGjE;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,GAAG,IAAI,OAAO,CAEb;IAED,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAElD;IAED,QAAQ,IAAI,QAAQ,CAEnB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAED;;;;;OAKG;IACH,MAAM,IAAI,IAAI,CAKb;IAED,KAAK,IAAI,IAAI,CAGZ;CACF;AAED,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}

package/dist/src/store.js

@@ -0,0 +1,127 @@
+import { ArenaOwner } from "./owner.js";
+import { ArenaReader } from "./reader.js";
+/**
+ * The owner side store.
+ *
+ * Writes are queued and applied in order, and the promise resolves after the commit is
+ * published. Queuing rather than applying inline means a recipe cannot observe a half
+ * applied earlier write, and it makes the total order the contract promises explicit rather
+ * than incidental.
+ */
+export class OwnerStore {
+    owner;
+    #listeners = new Set();
+    #queue = Promise.resolve();
+    constructor(owner) {
+        this.owner = owner;
+    }
+    static create(initial, options = {}) {
+        const owner = ArenaOwner.create(options);
+        owner.commit(initial);
+        return new OwnerStore(owner);
+    }
+    get buffer() {
+        return this.owner.buffer;
+    }
+    get version() {
+        return this.owner.versionId;
+    }
+    get() {
+        return this.snapshot().value;
+    }
+    select(path) {
+        return this.snapshot().get(path);
+    }
+    snapshot() {
+        return this.#reader().acquire();
+    }
+    #ownReader;
+    #reader() {
+        if (this.#ownReader === undefined) {
+            // The owner reads through an ordinary reader, on the same code path every window uses.
+            // A separate owner only read path would be a second implementation to keep correct.
+            this.#ownReader = ArenaReader.attach(this.owner.buffer);
+        }
+        return this.#ownReader;
+    }
+    update(recipe) {
+        return this.#enqueue(() => this.owner.update(recipe));
+    }
+    set(value) {
+        return this.#enqueue(() => this.owner.commit(value));
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #enqueue(work) {
+        const result = this.#queue.then(() => {
+            const version = work();
+            this.#notify();
+            return version;
+        });
+        // Keep the chain alive after a rejection, or one failed write would stall every later
+        // one behind it.
+        this.#queue = result.catch(() => undefined);
+        return result;
+    }
+    #notify() {
+        for (const listener of this.#listeners)
+            listener();
+    }
+    close() {
+        this.#ownReader?.detach();
+        this.#ownReader = undefined;
+        this.#listeners.clear();
+    }
+}
+/**
+ * The reader side store.
+ *
+ * It has no write method at all. A window that needs to write does it through the intent
+ * channel the integration supplies, which is asynchronous by construction.
+ */
+export class ReaderStore {
+    reader;
+    #listeners = new Set();
+    #lastSeen;
+    constructor(buffer, options = {}) {
+        this.reader = ArenaReader.attach(buffer, options);
+        this.#lastSeen = this.reader.publishedVersion();
+    }
+    get version() {
+        return this.reader.publishedVersion();
+    }
+    get() {
+        return this.reader.acquire().value;
+    }
+    select(path) {
+        return this.reader.acquire().get(path);
+    }
+    snapshot() {
+        return this.reader.acquire();
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /**
+     * Tell the store a commit happened.
+     *
+     * The integration calls this when the owner notifies it. Deliberately not a poll: nothing
+     * on the read path may depend on a message arriving, so this only drives rerenders.
+     */
+    notify() {
+        const version = this.reader.publishedVersion();
+        if (version === this.#lastSeen)
+            return;
+        this.#lastSeen = version;
+        for (const listener of this.#listeners)
+            listener();
+    }
+    close() {
+        this.reader.detach();
+        this.#listeners.clear();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}

package/dist/src/strings.d.ts

@@ -0,0 +1,37 @@
+import type { SharedArena } from "./arena.js";
+import type { Allocator } from "./allocator.js";
+export declare function stringRecordBytes(length: number): number;
+/** Owner side. Holds the intern map, which never leaves the writer process. */
+export declare class StringTable {
+    #private;
+    constructor(arena: SharedArena, allocator: Allocator);
+    get size(): number;
+    /**
+     * Return the offset of `text`, writing it into the arena the first time it is seen.
+     *
+     * When a journal is supplied, strings this call newly interned are recorded on it. A commit
+     * that fails part way passes the journal to `forget` so the records it created are
+     * released. Without that, a rejected write would consume arena permanently, and a window
+     * that could request writes could exhaust the arena with rejected ones.
+     */
+    intern(text: string, journal?: string[]): number;
+    /**
+     * Release strings interned during a commit that failed.
+     *
+     * Safe only for strings no published version references, which is exactly what the journal
+     * records: entries this commit created and no earlier one did.
+     */
+    forget(texts: readonly string[]): void;
+    /** Bytes held by interned strings. Reported by the soak harness. */
+    byteSize(): number;
+}
+/**
+ * Decode a string record. Every field is validated before it is used, so a wild offset
+ * produces an ArenaCorruptError rather than a very long string built from arbitrary bytes.
+ */
+export declare function decodeString(arena: SharedArena, offset: number): string;
+/** The stored hash, for callers comparing keys without materialising the string. */
+export declare function stringHash(arena: SharedArena, offset: number): number;
+/** Compare an interned record against a JavaScript string without allocating. */
+export declare function stringEquals(arena: SharedArena, offset: number, text: string): boolean;
+//# sourceMappingURL=strings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/strings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA8BhD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,+EAA+E;AAC/E,qBAAa,WAAW;;IAMtB,YAAY,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAGnD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAmB/C;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAOrC;IAED,oEAAoE;IACpE,QAAQ,IAAI,MAAM,CAIjB;CACF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA0BvE;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBtF"}

package/dist/src/strings.js

@@ -0,0 +1,144 @@
+import { ArenaCorruptError } from "./errors.js";
+import { WORD, align } from "./layout.js";
+import { hashString } from "./checksum.js";
+/**
+ * Interned strings.
+ *
+ * Record layout, at the payload offset returned by the allocator:
+ *
+ *   word 0   hash, so a comparison can reject in one integer compare
+ *   word 1   length in UTF-16 code units
+ *   word 2.. the code units, packed two per word
+ *
+ * Strings are stored as UTF-16 rather than UTF-8 because JavaScript strings are UTF-16 and
+ * the decode path is the hot one. Encoding to UTF-8 would halve the size of ASCII text and
+ * add a conversion to every read, which is the wrong trade for this library.
+ *
+ * The table is append only. A string is never freed while the arena lives, which is the
+ * documented cost of interning: equal keys share one record and comparison is an integer
+ * compare, at the price of holding every distinct string ever written. Workloads that churn
+ * through unbounded distinct strings should keep them in the asynchronous tier. Compaction
+ * is a phase 5 question, and the soak harness reports the table size so the decision has
+ * data behind it.
+ */
+const HEADER_WORDS = 2;
+const HASH_WORD = 0;
+const LENGTH_WORD = 1;
+export function stringRecordBytes(length) {
+    return align(HEADER_WORDS * WORD + length * 2);
+}
+/** Owner side. Holds the intern map, which never leaves the writer process. */
+export class StringTable {
+    #arena;
+    #allocator;
+    /** Interning map, keyed by the string itself. Only the owner has it. */
+    #interned = new Map();
+    constructor(arena, allocator) {
+        this.#arena = arena;
+        this.#allocator = allocator;
+    }
+    get size() {
+        return this.#interned.size;
+    }
+    /**
+     * Return the offset of `text`, writing it into the arena the first time it is seen.
+     *
+     * When a journal is supplied, strings this call newly interned are recorded on it. A commit
+     * that fails part way passes the journal to `forget` so the records it created are
+     * released. Without that, a rejected write would consume arena permanently, and a window
+     * that could request writes could exhaust the arena with rejected ones.
+     */
+    intern(text, journal) {
+        const existing = this.#interned.get(text);
+        if (existing !== undefined)
+            return existing;
+        journal?.push(text);
+        const offset = this.#allocator.allocate(stringRecordBytes(text.length));
+        const words = this.#arena.words;
+        const base = offset / WORD;
+        words[base + HASH_WORD] = hashString(text);
+        words[base + LENGTH_WORD] = text.length;
+        const units = this.#arena.units;
+        const unitBase = (offset + HEADER_WORDS * WORD) / 2;
+        for (let i = 0; i < text.length; i += 1) {
+            units[unitBase + i] = text.charCodeAt(i);
+        }
+        this.#interned.set(text, offset);
+        return offset;
+    }
+    /**
+     * Release strings interned during a commit that failed.
+     *
+     * Safe only for strings no published version references, which is exactly what the journal
+     * records: entries this commit created and no earlier one did.
+     */
+    forget(texts) {
+        for (const text of texts) {
+            const offset = this.#interned.get(text);
+            if (offset === undefined)
+                continue;
+            this.#interned.delete(text);
+            this.#allocator.free(offset);
+        }
+    }
+    /** Bytes held by interned strings. Reported by the soak harness. */
+    byteSize() {
+        let total = 0;
+        for (const text of this.#interned.keys())
+            total += stringRecordBytes(text.length);
+        return total;
+    }
+}
+/**
+ * Decode a string record. Every field is validated before it is used, so a wild offset
+ * produces an ArenaCorruptError rather than a very long string built from arbitrary bytes.
+ */
+export function decodeString(arena, offset) {
+    const byteSize = arena.checkBlock(offset, "string");
+    const words = arena.words;
+    const base = offset / WORD;
+    const length = words[base + LENGTH_WORD];
+    if (length < 0 || stringRecordBytes(length) > byteSize) {
+        throw new ArenaCorruptError(`string at ${offset} claims ${length} code units, which does not fit in ${byteSize} bytes`, { offset, actual: length });
+    }
+    const units = arena.units;
+    const unitBase = (offset + HEADER_WORDS * WORD) / 2;
+    // fromCharCode with a subarray is measurably faster than a loop for typical key lengths,
+    // and the chunking keeps the argument count away from the engine limit for long text.
+    if (length <= 2048) {
+        return String.fromCharCode(...units.subarray(unitBase, unitBase + length));
+    }
+    let out = "";
+    for (let start = 0; start < length; start += 2048) {
+        const end = Math.min(start + 2048, length);
+        out += String.fromCharCode(...units.subarray(unitBase + start, unitBase + end));
+    }
+    return out;
+}
+/** The stored hash, for callers comparing keys without materialising the string. */
+export function stringHash(arena, offset) {
+    arena.checkBlock(offset, "string hash");
+    return arena.words[offset / WORD + HASH_WORD];
+}
+/** Compare an interned record against a JavaScript string without allocating. */
+export function stringEquals(arena, offset, text) {
+    const byteSize = arena.checkBlock(offset, "string compare");
+    const words = arena.words;
+    const base = offset / WORD;
+    const length = words[base + LENGTH_WORD];
+    if (length !== text.length)
+        return false;
+    if (stringRecordBytes(length) > byteSize) {
+        throw new ArenaCorruptError(`string at ${offset} has an impossible length`, { offset });
+    }
+    if (words[base + HASH_WORD] !== hashString(text))
+        return false;
+    const units = arena.units;
+    const unitBase = (offset + HEADER_WORDS * WORD) / 2;
+    for (let i = 0; i < length; i += 1) {
+        if (units[unitBase + i] !== text.charCodeAt(i))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=strings.js.map

package/dist/src/strings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.js","sourceRoot":"","sources":["../../src/strings.ts"],"names":[],"mappings":"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"}