@net-mesh/browser 0.37.0

package/dist/store/core.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The local half of a store: state, subscriptions, status and the
+ * synchronous transaction.
+ *
+ * This is deliberately transport-free. Both the authoritative host and
+ * a joined replica are this object plus a network layer, which is why
+ * every rule that does *not* need a peer lives here and is testable
+ * without a mesh: immutability, identity preservation, selector
+ * equality, notification counting, and the transaction contract.
+ *
+ * **The transaction contract is the sharp part.** A handler runs
+ * synchronously, stages changes, and either commits one revision or
+ * discards everything:
+ *
+ * - `getState()` inside a handler reads the *staged* value, so a
+ *   handler sees its own writes.
+ * - A throw discards the staged changes. Nothing is published.
+ * - Returning a thenable is refused, because an `async` handler would
+ *   commit after its transaction closed — the TypeScript signature
+ *   already says `undefined`, and JavaScript callers bypass types.
+ * - The context is valid only for that transaction. A retained context
+ *   cannot write from a later microtask.
+ * - Read-only callbacks (validators, `authorize`, `project`, update
+ *   functions) may not reenter a setter.
+ * - A public owner `setState` called synchronously *inside* a handler
+ *   joins the same staged transaction rather than committing beside it,
+ *   so a handler's rollback cannot be defeated by going through the
+ *   public handle.
+ */
+import { type PatchOutcome } from './patch.js';
+import type { WireOp } from './wire.js';
+import type { Cancel, ReadonlyState, SelectorOptions, StateUpdate, StoreDefinition, StorePhase, StoreStatus, ActionContext, ActionSpec, InputSpec } from './types.js';
+/**
+ * The transport-free store.
+ *
+ * `S` is the validated state shape. The definition is held for its
+ * `state` validator, which every commit passes through — an owner
+ * cannot publish state its own schema rejects.
+ */
+export declare class StoreCore<S extends object, A extends ActionSpec, I extends InputSpec> {
+    #private;
+    constructor(options: {
+        definition: StoreDefinition<S, A, I>;
+        initialState: S;
+        phase?: StorePhase;
+    });
+    /** The current immutable snapshot. Never initiates I/O. */
+    getState(): ReadonlyState<S>;
+    /** Monotone count of applied transactions. Unchanged updates do not move it. */
+    get revision(): number;
+    /**
+     * Whether a synchronous transaction is open on this store.
+     *
+     * The owner's public `commit` reads this to DEFER its delta
+     * emission to the transaction's commit: no frame may leave for
+     * state the transaction may still discard (#5).
+     */
+    get inTransaction(): boolean;
+    subscribe(listener: (state: ReadonlyState<S>, previous: ReadonlyState<S>) => void): Cancel;
+    subscribe<T>(selector: (state: ReadonlyState<S>) => T, listener: (selected: T, previous: T) => void, options?: SelectorOptions<T>): Cancel;
+    getStatus(): StoreStatus;
+    subscribeStatus(listener: (status: StoreStatus, previous: StoreStatus) => void): Cancel;
+    /**
+     * Move readiness. A transition to an identical status is not a
+     * transition: the object keeps its identity and nobody is notified.
+     */
+    setStatus(patch: Partial<StoreStatus>): void;
+    /**
+     * Run one handler as a transaction and commit its staged changes.
+     *
+     * Returns whatever the handler returned. A throw propagates with
+     * nothing published.
+     */
+    transact<R>(run: (context: ActionContext<S>) => R, peer: string): R;
+    /**
+     * The owner's public write. Inside a handler it joins that handler's
+     * transaction; outside one it is its own single-revision transaction.
+     */
+    applyOwnerUpdate(update: StateUpdate<S>): void;
+    /**
+     * Apply a full snapshot: validate, then reconcile.
+     *
+     * An equivalent snapshot is a no-op — same root reference, no
+     * notifications — which is what stops a periodic resynchronization
+     * from looking like a world change to every selector.
+     *
+     * Inside a handler it JOINS the open transaction, exactly as
+     * `applyOwnerUpdate` does: the owner's public `setState` reaches
+     * here through `commit`, and committing beside the transaction
+     * published a handler's world while `transact` then reported
+     * `action-rejected` for it — or, on the committing path, silently
+     * reverted the nested write after subscribers had seen it.
+     */
+    applySnapshot(raw: unknown): void;
+    /**
+     * Write entities of one declared collection: each changed entity
+     * validated by its PER-ENTITY parser (`definition.entities`), and the
+     * document committed WITHOUT the whole-document validator.
+     *
+     * `changes` maps an id to its new value, or to `undefined` to remove
+     * it. The untouched entities keep their identity, so reconciliation
+     * and every downstream diff short-circuit on them. What is not free:
+     * rebuilding the collection object, O(entities) shallow and with no
+     * parsing.
+     *
+     * Inside a handler it JOINS the open transaction, like
+     * {@link applySnapshot}. The whole-document validator is skipped by
+     * contract: declaring the collection in `entities` says `state`
+     * imposes nothing on it beyond each entity passing its parser.
+     */
+    applyEntities(collection: string, changes: Readonly<Record<string, unknown>>): void;
+    /**
+     * Apply a replica delta: the owner's patch operations, at this
+     * document, validated by this definition.
+     *
+     * This lives here rather than in the replica because the store owns
+     * the document, its validator and its revision. A replica that read
+     * the state out, patched it outside and pushed the result back would
+     * validate twice per delta and would be free to publish something
+     * the definition never saw.
+     *
+     * Refusals are returned, not thrown: a delta that does not apply is
+     * a recoverable divergence (§1.8 resynchronization), not a caller
+     * error.
+     */
+    applyDelta(ops: readonly WireOp[]): PatchOutcome<S>;
+    /**
+     * Run a read-only callback with setters fenced off.
+     *
+     * The host layer routes `authorize` and `project` through this, so a
+     * callback that is documented as read-only cannot quietly mutate.
+     */
+    runReadOnly<R>(run: () => R): R;
+    /** Fence the handle: closed, stale, no listeners retained. */
+    close(): void;
+}

package/dist/store/core.js

@@ -0,0 +1,477 @@
+/**
+ * The local half of a store: state, subscriptions, status and the
+ * synchronous transaction.
+ *
+ * This is deliberately transport-free. Both the authoritative host and
+ * a joined replica are this object plus a network layer, which is why
+ * every rule that does *not* need a peer lives here and is testable
+ * without a mesh: immutability, identity preservation, selector
+ * equality, notification counting, and the transaction contract.
+ *
+ * **The transaction contract is the sharp part.** A handler runs
+ * synchronously, stages changes, and either commits one revision or
+ * discards everything:
+ *
+ * - `getState()` inside a handler reads the *staged* value, so a
+ *   handler sees its own writes.
+ * - A throw discards the staged changes. Nothing is published.
+ * - Returning a thenable is refused, because an `async` handler would
+ *   commit after its transaction closed — the TypeScript signature
+ *   already says `undefined`, and JavaScript callers bypass types.
+ * - The context is valid only for that transaction. A retained context
+ *   cannot write from a later microtask.
+ * - Read-only callbacks (validators, `authorize`, `project`, update
+ *   functions) may not reenter a setter.
+ * - A public owner `setState` called synchronously *inside* a handler
+ *   joins the same staged transaction rather than committing beside it,
+ *   so a handler's rollback cannot be defeated by going through the
+ *   public handle.
+ */
+import { StoreError } from './errors.js';
+import { mergeShallow, reconcile } from './state.js';
+import { isEntityMap } from './definition.js';
+import { applyPatch } from './patch.js';
+/**
+ * The transport-free store.
+ *
+ * `S` is the validated state shape. The definition is held for its
+ * `state` validator, which every commit passes through — an owner
+ * cannot publish state its own schema rejects.
+ */
+export class StoreCore {
+    #definition;
+    #subscriptions = new Set();
+    #statusListeners = new Set();
+    #state;
+    #status;
+    #revision = 0;
+    #transaction = null;
+    #readOnlyDepth = 0;
+    #closed = false;
+    constructor(options) {
+        this.#definition = options.definition;
+        // Validate and freeze once at construction: from here on the only
+        // way in is a commit, and every commit reconciles against this.
+        this.#state = reconcile(undefined, this.#validate(options.initialState));
+        this.#status = Object.freeze({
+            phase: options.phase ?? 'ready',
+            stale: false,
+            error: null,
+        });
+    }
+    /** The current immutable snapshot. Never initiates I/O. */
+    getState() {
+        return this.#state;
+    }
+    /** Monotone count of applied transactions. Unchanged updates do not move it. */
+    get revision() {
+        return this.#revision;
+    }
+    /**
+     * Whether a synchronous transaction is open on this store.
+     *
+     * The owner's public `commit` reads this to DEFER its delta
+     * emission to the transaction's commit: no frame may leave for
+     * state the transaction may still discard (#5).
+     */
+    get inTransaction() {
+        return this.#transaction !== null && this.#transaction.active;
+    }
+    subscribe(first, second, options) {
+        const subscription = second === undefined
+            ? this.#rootSubscription(first)
+            : this.#selectorSubscription(first, second, options);
+        this.#subscriptions.add(subscription);
+        let live = true;
+        return () => {
+            if (!live)
+                return;
+            live = false;
+            this.#subscriptions.delete(subscription);
+        };
+    }
+    getStatus() {
+        return this.#status;
+    }
+    subscribeStatus(listener) {
+        this.#statusListeners.add(listener);
+        let live = true;
+        return () => {
+            if (!live)
+                return;
+            live = false;
+            this.#statusListeners.delete(listener);
+        };
+    }
+    /**
+     * Move readiness. A transition to an identical status is not a
+     * transition: the object keeps its identity and nobody is notified.
+     */
+    setStatus(patch) {
+        const previous = this.#status;
+        const candidate = {
+            phase: patch.phase ?? previous.phase,
+            stale: patch.stale ?? previous.stale,
+            error: patch.error === undefined ? previous.error : patch.error,
+        };
+        if (candidate.phase === previous.phase &&
+            candidate.stale === previous.stale &&
+            Object.is(candidate.error, previous.error)) {
+            return;
+        }
+        this.#status = Object.freeze(candidate);
+        for (const listener of [...this.#statusListeners]) {
+            // Same rule as the state pass: a cancellation that has already
+            // returned is honoured for the rest of this pass.
+            if (!this.#statusListeners.has(listener))
+                continue;
+            dispatch(() => listener(this.#status, previous));
+        }
+    }
+    /**
+     * Run one handler as a transaction and commit its staged changes.
+     *
+     * Returns whatever the handler returned. A throw propagates with
+     * nothing published.
+     */
+    transact(run, peer) {
+        this.#refuseWhenClosed();
+        if (this.#transaction !== null) {
+            throw new StoreError('action-rejected', 'a store transaction is already open on this store; handlers are synchronous and must not nest');
+        }
+        const transaction = { staged: this.#state, active: true };
+        this.#transaction = transaction;
+        try {
+            const result = run(this.#context(transaction, peer));
+            if (isThenable(result)) {
+                throw new StoreError('action-rejected', 'a store handler returned a thenable; handlers are synchronous so that a throw can discard the whole transaction');
+            }
+            this.#commit(transaction.staged);
+            return result;
+        }
+        finally {
+            // Invalidate before clearing, so a context captured by the
+            // handler is dead even if the handler stashed it somewhere.
+            transaction.active = false;
+            this.#transaction = null;
+        }
+    }
+    /**
+     * The owner's public write. Inside a handler it joins that handler's
+     * transaction; outside one it is its own single-revision transaction.
+     */
+    applyOwnerUpdate(update) {
+        this.#refuseWhenClosed();
+        const open = this.#transaction;
+        if (open !== null && open.active) {
+            open.staged = this.#stage(open.staged, update);
+            return;
+        }
+        const staged = this.#stage(this.#state, update);
+        this.#commit(staged);
+    }
+    /**
+     * Apply a full snapshot: validate, then reconcile.
+     *
+     * An equivalent snapshot is a no-op — same root reference, no
+     * notifications — which is what stops a periodic resynchronization
+     * from looking like a world change to every selector.
+     *
+     * Inside a handler it JOINS the open transaction, exactly as
+     * `applyOwnerUpdate` does: the owner's public `setState` reaches
+     * here through `commit`, and committing beside the transaction
+     * published a handler's world while `transact` then reported
+     * `action-rejected` for it — or, on the committing path, silently
+     * reverted the nested write after subscribers had seen it.
+     */
+    applySnapshot(raw) {
+        this.#refuseWhenClosed();
+        const open = this.#transaction;
+        if (open !== null && open.active) {
+            open.staged = this.#validate(raw);
+            return;
+        }
+        this.#commit(this.#validate(raw));
+    }
+    /**
+     * Write entities of one declared collection: each changed entity
+     * validated by its PER-ENTITY parser (`definition.entities`), and the
+     * document committed WITHOUT the whole-document validator.
+     *
+     * `changes` maps an id to its new value, or to `undefined` to remove
+     * it. The untouched entities keep their identity, so reconciliation
+     * and every downstream diff short-circuit on them. What is not free:
+     * rebuilding the collection object, O(entities) shallow and with no
+     * parsing.
+     *
+     * Inside a handler it JOINS the open transaction, like
+     * {@link applySnapshot}. The whole-document validator is skipped by
+     * contract: declaring the collection in `entities` says `state`
+     * imposes nothing on it beyond each entity passing its parser.
+     */
+    applyEntities(collection, changes) {
+        this.#refuseWhenClosed();
+        const parse = this.#definition.entities?.[collection];
+        if (parse === undefined || !Object.prototype.hasOwnProperty.call(this.#definition.entities, collection)) {
+            throw new StoreError('invalid-data', `store '${this.#definition.id}' declares no per-entity parser for '${collection}'; declare it in \`entities\` or write through setState`);
+        }
+        const open = this.#transaction;
+        const from = open !== null && open.active ? open.staged : this.#state;
+        const current = from[collection];
+        if (current !== undefined && !isEntityMap(current)) {
+            throw new StoreError('invalid-data', `store '${this.#definition.id}': '${collection}' is not an entity map in the current state`);
+        }
+        // Every change parsed BEFORE anything is built: a refusal on the last
+        // id publishes nothing.
+        const parsed = [];
+        for (const id of Object.keys(changes)) {
+            if (id.length === 0) {
+                throw new StoreError('invalid-data', `store '${this.#definition.id}': an entity id in '${collection}' is empty`);
+            }
+            const raw = changes[id];
+            if (raw === undefined) {
+                parsed.push([id, undefined]);
+                continue;
+            }
+            try {
+                parsed.push([id, this.runReadOnly(() => parse(raw))]);
+            }
+            catch (error) {
+                if (error instanceof StoreError)
+                    throw error;
+                throw new StoreError('invalid-data', `entity '${collection}.${id}' failed the '${this.#definition.id}' entity validator: ${String(error)}`, { cause: error });
+            }
+        }
+        if (open !== null && open.active) {
+            // A staged document need not be reconciled yet (a `setState` inside
+            // the handler stages the validator's raw output), so the transaction
+            // gets the general merge; its commit validates the document anyway.
+            const draft = { ...(current ?? {}) };
+            for (const [id, entity] of parsed) {
+                if (entity === undefined)
+                    delete draft[id];
+                else
+                    defineData(draft, id, entity);
+            }
+            open.staged = mergeShallow(from, { [collection]: draft });
+            return;
+        }
+        // Outside a transaction `from` is the committed state: reconciled and
+        // frozen all the way down. So only the CHANGED entities are reconciled,
+        // the collection is rebuilt by a spread (which defines own properties,
+        // `__proto__` included, and parses nothing), and the result is
+        // installed without a second whole-tree reconcile — `reconcile` over the
+        // collection is exactly the O(world) walk this path exists to skip.
+        let changed = false;
+        const reconciled = [];
+        for (const [id, entity] of parsed) {
+            const present = current !== undefined && Object.prototype.hasOwnProperty.call(current, id);
+            const before = present ? current[id] : undefined;
+            if (entity === undefined) {
+                if (present)
+                    changed = true;
+                reconciled.push([id, undefined]);
+                continue;
+            }
+            const next = reconcile(before, entity);
+            if (!Object.is(before, next))
+                changed = true;
+            reconciled.push([id, next]);
+        }
+        if (!changed)
+            return;
+        const map = { ...(current ?? {}) };
+        for (const [id, entity] of reconciled) {
+            if (entity === undefined)
+                delete map[id];
+            else
+                defineData(map, id, entity);
+        }
+        const root = { ...from };
+        defineData(root, collection, Object.freeze(map));
+        this.#install(Object.freeze(root));
+    }
+    /**
+     * Apply a replica delta: the owner's patch operations, at this
+     * document, validated by this definition.
+     *
+     * This lives here rather than in the replica because the store owns
+     * the document, its validator and its revision. A replica that read
+     * the state out, patched it outside and pushed the result back would
+     * validate twice per delta and would be free to publish something
+     * the definition never saw.
+     *
+     * Refusals are returned, not thrown: a delta that does not apply is
+     * a recoverable divergence (§1.8 resynchronization), not a caller
+     * error.
+     */
+    applyDelta(ops) {
+        this.#refuseWhenClosed();
+        const outcome = applyPatch(this.#state, ops, raw => this.#validate(raw));
+        // `applyPatch` has ALREADY run the validator on the patched
+        // document — that is what it was handed one for. Committing
+        // through the validating path ran it a second time, and a
+        // validator is not required to be idempotent: a parser that
+        // derives or normalizes a field applied its transformation twice,
+        // so the outcome this returns and the document a subscriber sees
+        // were different values. One validation per document.
+        if (outcome.ok && outcome.changed)
+            this.#publish(outcome.next);
+        return outcome;
+    }
+    /**
+     * Run a read-only callback with setters fenced off.
+     *
+     * The host layer routes `authorize` and `project` through this, so a
+     * callback that is documented as read-only cannot quietly mutate.
+     */
+    runReadOnly(run) {
+        this.#readOnlyDepth += 1;
+        try {
+            return run();
+        }
+        finally {
+            this.#readOnlyDepth -= 1;
+        }
+    }
+    /** Fence the handle: closed, stale, no listeners retained. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.setStatus({ phase: 'closed', stale: true });
+        this.#subscriptions.clear();
+        this.#statusListeners.clear();
+    }
+    #context(transaction, peer) {
+        return {
+            peer,
+            getState: () => {
+                this.#refuseEscapedContext(transaction);
+                return transaction.staged;
+            },
+            setState: (update) => {
+                this.#refuseEscapedContext(transaction);
+                if (this.#readOnlyDepth > 0) {
+                    throw new StoreError('action-rejected', 'a read-only store callback may not write state; validators, authorize, project and update functions run with setters fenced');
+                }
+                transaction.staged = this.#stage(transaction.staged, update);
+            },
+        };
+    }
+    #stage(from, update) {
+        const patch = typeof update === 'function'
+            ? this.runReadOnly(() => update(from))
+            : update;
+        return mergeShallow(from, patch);
+    }
+    #commit(candidate) {
+        this.#publish(this.#validate(candidate));
+    }
+    /**
+     * Reconcile and publish a document that has ALREADY been validated.
+     *
+     * Split from {@link #commit} so a caller that validated can say so
+     * instead of validating again. Everything below this line is
+     * reconciliation, revision and notification — never validation.
+     */
+    #publish(validated) {
+        const next = reconcile(this.#state, validated);
+        if (Object.is(next, this.#state))
+            return;
+        this.#install(next);
+    }
+    /**
+     * Install a document that is ALREADY reconciled against the current one
+     * and frozen, and tell the subscribers. Only {@link applyEntities}
+     * builds such a document itself; everything else comes through
+     * {@link #publish}.
+     */
+    #install(next) {
+        const previous = this.#state;
+        this.#state = next;
+        this.#revision += 1;
+        // The snapshot keeps a listener added DURING this pass out of it,
+        // and re-checking membership keeps a listener CANCELLED during it
+        // out too. Both are the same question asked at the right moment: a
+        // `cancel()` that has already returned must not be followed by a
+        // call, or a listener that has torn down its own scene graph gets
+        // handed one more frame of state it no longer expects.
+        for (const subscription of [...this.#subscriptions]) {
+            if (!this.#subscriptions.has(subscription))
+                continue;
+            subscription.notify(next, previous);
+        }
+    }
+    #validate(raw) {
+        try {
+            return this.runReadOnly(() => this.#definition.state(raw));
+        }
+        catch (error) {
+            if (error instanceof StoreError)
+                throw error;
+            throw new StoreError('invalid-data', `state failed the '${this.#definition.id}' validator: ${String(error)}`, { cause: error });
+        }
+    }
+    #rootSubscription(listener) {
+        return {
+            notify: (next, previous) => {
+                dispatch(() => listener(next, previous));
+            },
+        };
+    }
+    #selectorSubscription(selector, listener, options) {
+        const equality = options?.equality ?? Object.is;
+        let last = this.runReadOnly(() => selector(this.#state));
+        if (options?.fireImmediately === true) {
+            dispatch(() => listener(last, last));
+        }
+        return {
+            notify: next => {
+                const selected = this.runReadOnly(() => selector(next));
+                const previous = last;
+                // An unchanged selection is not an event. This is what makes a
+                // 60 Hz render loop cheap, and it is asserted, not assumed.
+                if (equality(selected, previous))
+                    return;
+                last = selected;
+                dispatch(() => listener(selected, previous));
+            },
+        };
+    }
+    #refuseEscapedContext(transaction) {
+        if (transaction.active)
+            return;
+        throw new StoreError('action-rejected', 'this store transaction has already ended; its context cannot read or write from a later turn');
+    }
+    #refuseWhenClosed() {
+        if (!this.#closed)
+            return;
+        throw new StoreError('closed', 'this store handle is closed');
+    }
+}
+function isThenable(value) {
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return false;
+    }
+    return typeof value.then === 'function';
+}
+/**
+ * Run one listener in isolation.
+ *
+ * A listener's bug is not the store's: report it where a page can see
+ * it and keep the remaining listeners — and the cleanup that follows
+ * them — running. Same convention as the event hub in `events.ts`.
+ */
+function dispatch(deliver) {
+    try {
+        deliver();
+    }
+    catch (error) {
+        console.error('[@net-mesh/browser] store listener threw', error);
+    }
+}
+/** Store a caller's key as data: an id of `__proto__` is not a prototype. */
+function defineData(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}

package/dist/store/definition.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `defineStore` — the reusable typed description.
+ *
+ * It holds validators, never authority handlers, so a client bundle
+ * that joins a store does not carry the owner's gameplay code.
+ *
+ * It is not a pass-through. It checks the two properties whose
+ * violation is invisible until much later:
+ *
+ * 1. `empty()` must itself be a valid state. `empty()` is what a
+ *    replica installs when it loses visibility, so an `empty()` the
+ *    schema would reject means audience clearing fails at the worst
+ *    possible moment — mid-transition, with the old projection already
+ *    fenced.
+ * 2. `id` and `version` must be usable as an incarnation identity.
+ *    They travel in every envelope and a blank id or a non-integer
+ *    version turns a version-mismatch refusal into a confusing parse
+ *    error at the far end.
+ */
+import type { ActionSpec, InputSpec, StoreDefinition } from './types.js';
+export declare function defineStore<S extends object, A extends ActionSpec, I extends InputSpec>(definition: StoreDefinition<S, A, I>): StoreDefinition<S, A, I>;
+/** A plain object: what an entity map is. */
+export declare function isEntityMap(value: unknown): value is Readonly<Record<string, unknown>>;