@issuegraph/store 0.1.0

package/dist/store.js

@@ -0,0 +1,529 @@
+/**
+ * The store: the one stateful module, and the only place IO happens.
+ *
+ * Everything it decides is decided by the pure modules beside it — validity,
+ * the write ledger and projection, the order diff. What lives here is the state
+ * itself, the calls into the injected data source, and the notification.
+ *
+ * **The rule the structure exists to enforce:** the selection order is derived
+ * from `landed` and from nothing else. `projected` — the landed document plus
+ * every unsettled edit — is built in one place and is not in scope where the
+ * deriver is called, so an optimistic edge cannot reach the order by anyone
+ * forgetting a filter.
+ */
+import { sameEdgeSet, } from "./model.js";
+import { diffOrder } from "./change.js";
+import { sameValue } from "./equality.js";
+import { anyPending, project } from "./write.js";
+import { nextDocument, structuralRefusal } from "./validity.js";
+// Frozen because every store starts on this one object, and a shared mutable
+// default is a cross-instance leak waiting for the first caller who sorts in
+// place.
+const EMPTY_DOCUMENT = Object.freeze({
+    issues: Object.freeze([]),
+    edges: Object.freeze([]),
+});
+/**
+ * Take ownership of a list the store is about to publish: copy it, then freeze.
+ *
+ * The arrays a snapshot hands out ARE the store's state — `landed` and `issues`
+ * arrive from the adapter, `order.rows` from the deriver — and `Object.freeze`
+ * on the snapshot object protects none of them. A consumer calling `.sort()` on
+ * one (the common slip; `[...list].sort()` is the careful form) would reorder
+ * store state with no dispatch, no re-derivation and no notification, and the
+ * next order would derive from a document nobody wrote.
+ *
+ * COPIED BEFORE FREEZING, not frozen in place, because these arrive from the
+ * host: freezing an adapter's own array would freeze it out of its own storage
+ * for handing one over.
+ *
+ * THE CONTAINERS ONLY. The elements stay as the host made them — the store owns
+ * which edges and rows it holds, the host owns what each one is — because
+ * freezing those would reach into objects an adapter or a deriver may still be
+ * using. `readonly` in the types is what discourages touching them; nothing at
+ * runtime can promise it without taking objects that are not ours.
+ */
+function own(list) {
+    return Object.freeze([...list]);
+}
+/** A host-supplied document the store is taking on: its containers become ours. */
+function ownDocument(document) {
+    return Object.freeze({ issues: own(document.issues), edges: own(document.edges) });
+}
+/**
+ * Rows from the injected deriver, with their nested container taken on too.
+ *
+ * `holdReasons` is the deriver's array, so it is copied for the same reason the
+ * top-level list is: the store must be able to freeze what it publishes without
+ * freezing a host out of its own storage.
+ */
+function ownRows(rows) {
+    return own(rows.map((row) => ({ ...row, holdReasons: own(row.holdReasons) })));
+}
+/**
+ * Freeze every array reachable from a published value.
+ *
+ * `own` at each entry point covers the containers the store adopts directly,
+ * and that is exactly as far as it went — one level, when the predicate was
+ * never one level. Arrays nested inside published values (a conflict document's
+ * edges, an edge's state list, a row's hold reasons) are reachable from
+ * `getSnapshot()` just the same, and a consumer splicing one of those changes
+ * store state as surely as splicing `landed` would.
+ *
+ * ARRAYS ONLY: objects are walked but not frozen. That is the boundary the
+ * store can honestly keep — it owns which edges and rows it holds, the host
+ * owns what each one IS — and freezing the contents would seize objects an
+ * adapter or a deriver may still be using.
+ *
+ * Not short-circuited on an already-frozen array: `own` freezes a container
+ * without touching what is inside it, so stopping at the first frozen array
+ * would skip exactly the nested ones this exists to reach.
+ */
+function freezeArrays(value) {
+    if (Array.isArray(value)) {
+        Object.freeze(value);
+        for (const item of value)
+            freezeArrays(item);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        for (const nested of Object.values(value))
+            freezeArrays(nested);
+    }
+}
+const NO_PROJECTION = Object.freeze([]);
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+ * Create a store over one data source.
+ *
+ * Nothing is loaded until `hydrate()` is called, so a host can construct the
+ * store during render and start the load where it wants to.
+ */
+export function createStore(config) {
+    const { source, derive, guard } = config;
+    let landed = EMPTY_DOCUMENT;
+    let status = 'idle';
+    let hydrationError;
+    let records = [];
+    let selection = [];
+    let rows = [];
+    let lastChange;
+    let orderError;
+    let sequence = 0;
+    /**
+     * The edit the summary would belong to.
+     *
+     * A summary is written when a write LANDS, which can be after a newer edit
+     * has already started — and the contract is that a summary lasts until the
+     * next edit. Without this, a host shows the previous edit's blast radius
+     * beside the one the user is making now.
+     */
+    let currentProposal;
+    const queue = [];
+    let draining = false;
+    const listeners = new Set();
+    const settlers = new Map();
+    const initial = {
+        status,
+        issues: landed.issues,
+        landed: landed.edges,
+        projected: NO_PROJECTION,
+        order: Object.freeze({ rows: ownRows(rows), status: 'settled' }),
+        writes: own(records),
+        selection: own(selection),
+    };
+    let published = Object.freeze(initial);
+    /**
+     * Adopt a document, reusing the arrays already held where the new ones say
+     * the same thing.
+     *
+     * Not an optimisation: `landed` is what everything downstream compares
+     * against, so an adapter returning an equal-but-fresh array on every call
+     * would make every slice of the snapshot look changed and defeat the "update
+     * only if something changed" rule at its source rather than at its edge.
+     */
+    function adopt(next) {
+        const adopted = {
+            issues: sameValue(landed.issues, next.issues) ? landed.issues : own(next.issues),
+            edges: sameEdgeSet(landed.edges, next.edges) ? landed.edges : own(next.edges),
+        };
+        landed = adopted;
+    }
+    /**
+     * Rebuild the snapshot, reusing every slice that has not changed, and notify
+     * only if the result differs from what is already published.
+     *
+     * Per-slice reuse rather than one all-or-nothing comparison, so a host
+     * memoising on `snapshot.order.rows` is not re-rendered by an unrelated
+     * selection change — and `getSnapshot()` returns the identical reference when
+     * nothing at all moved, which is what `useSyncExternalStore` requires.
+     */
+    function publish() {
+        // CALL THIS ONLY ONCE THE OPERATION IS FULLY COMMITTED. Subscribers run
+        // synchronously and may call straight back into the store, so anything left
+        // undone at this point can be overtaken by the re-entrant call — which is
+        // how a follow-up edit once jumped the queue ahead of the edit that
+        // triggered it. Every other call site already commits first; keep it that
+        // way rather than making each one rediscover the rule.
+        const nextProjected = project(landed, records, new Set(selection));
+        const nextOrderStatus = anyPending(records) ? 'held' : 'settled';
+        // One comparison for every slice. Nothing here names a field, so a field
+        // added to any of these shapes is compared without this block changing.
+        const projected = sameValue(published.projected, nextProjected)
+            ? published.projected
+            : own(nextProjected);
+        // The rows keep their identity across a status-only change. Rebuilding the
+        // view is cheap; handing a host a new array when the ranking did not move
+        // defeats whatever it memoised on, and the status flips on every write.
+        const orderRows = sameValue(published.order.rows, rows) ? published.order.rows : rows;
+        const order = published.order.status === nextOrderStatus && published.order.rows === orderRows
+            ? published.order
+            : Object.freeze({ rows: orderRows, status: nextOrderStatus });
+        const writes = sameValue(published.writes, records) ? published.writes : own(records);
+        const selected = sameValue(published.selection, selection) ? published.selection : own(selection);
+        const unchanged = published.status === status &&
+            published.hydrationError === hydrationError &&
+            published.issues === landed.issues &&
+            published.landed === landed.edges &&
+            published.projected === projected &&
+            published.order === order &&
+            published.writes === writes &&
+            published.lastChange === lastChange &&
+            published.orderError === orderError &&
+            published.selection === selected;
+        if (unchanged)
+            return;
+        // Optional keys are omitted rather than set to `undefined`, because
+        // `exactOptionalPropertyTypes` is on and a host testing `'lastChange' in
+        // snapshot` must not find an empty one.
+        published = Object.freeze({
+            status,
+            ...(hydrationError === undefined ? {} : { hydrationError }),
+            issues: landed.issues,
+            landed: landed.edges,
+            projected,
+            order,
+            writes,
+            ...(lastChange === undefined ? {} : { lastChange }),
+            ...(orderError === undefined ? {} : { orderError }),
+            selection: selected,
+        });
+        freezeArrays(published);
+        // Isolated, and for the same reason as the guard and the deriver: a host
+        // callback that throws must not break the store. Rethrown asynchronously so
+        // it still surfaces as an unhandled error rather than being swallowed.
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (thrown) {
+                queueMicrotask(() => {
+                    throw thrown;
+                });
+            }
+        }
+    }
+    /**
+     * Recompute the order from `landed`, and record what moved.
+     *
+     * A deriver that throws is a HOST callback failing, and the write it followed
+     * has already landed — so this cannot become a failed write and must not
+     * escape into the dispatch queue, where it would strand every edit behind it.
+     * The previously derived rows stand, `orderError` says why they are stale, and
+     * no change summary is emitted for an order nobody computed.
+     */
+    function reDerive(cause) {
+        const previous = rows;
+        let next;
+        try {
+            next = derive(landed);
+        }
+        catch (thrown) {
+            orderError = messageOf(thrown);
+            return;
+        }
+        // RECOVERING FROM A STALE BASELINE EMITS NO SUMMARY. While `orderError`
+        // stood, the published rows were the ones from before the edit that broke
+        // the deriver — so diffing the recovered order against them would credit
+        // that edit's movement to this one. There is no baseline that would make
+        // the attribution true, so none is claimed.
+        const recovering = orderError !== undefined;
+        orderError = undefined;
+        rows = ownRows(next);
+        // Only for the edit that is still the current one. A landing that a newer
+        // proposal has already overtaken has no summary to publish — the newer edit
+        // owns that slot, and will fill it when it lands.
+        const overtaken = cause !== undefined && cause.mutationId !== currentProposal;
+        if (cause !== undefined && !recovering && !overtaken)
+            lastChange = diffOrder(previous, rows, cause);
+    }
+    function recordFor(mutationId) {
+        return records.find((record) => record.mutationId === mutationId);
+    }
+    function putRecord(next) {
+        records = recordFor(next.mutationId) === undefined
+            ? [...records, next]
+            : records.map((record) => (record.mutationId === next.mutationId ? next : record));
+    }
+    function dropRecord(mutationId) {
+        records = records.filter((record) => record.mutationId !== mutationId);
+    }
+    function settle(mutationId) {
+        const resolve = settlers.get(mutationId);
+        settlers.delete(mutationId);
+        resolve?.();
+    }
+    /**
+     * Why this edit cannot happen — structurally, then by the injected guard.
+     *
+     * A guard that throws reached no verdict, and an unknown verdict is not
+     * permission to write: it refuses, fail-closed, with the thrown message as
+     * the reason. Letting it escape would strand the whole dispatch queue behind
+     * an edit that stayed pending for ever.
+     */
+    function refusalFor(mutation) {
+        const structural = structuralRefusal(landed, mutation);
+        if (structural !== undefined)
+            return structural;
+        if (guard === undefined)
+            return undefined;
+        try {
+            return guard({ mutation, current: landed, next: nextDocument(landed, mutation) });
+        }
+        catch (thrown) {
+            return { code: 'guard-failed', message: messageOf(thrown) };
+        }
+    }
+    async function dispatch(mutation) {
+        let result;
+        try {
+            result = await source.dispatch(mutation);
+        }
+        catch (thrown) {
+            // A crashing adapter must not leave the edit pending for ever, and must
+            // not look like a success. It is the same fact as a rejection — the write
+            // did not land — so it gets the same state and the same retry.
+            putRecord({
+                mutationId: mutation.mutationId,
+                mutation,
+                state: 'failed',
+                reason: messageOf(thrown),
+            });
+            settle(mutation.mutationId);
+            publish();
+            return;
+        }
+        switch (result.outcome) {
+            case 'applied': {
+                adopt(result.document);
+                dropRecord(mutation.mutationId);
+                reDerive(mutation);
+                break;
+            }
+            case 'unchanged': {
+                // Adopted like `applied`, because it is the same kind of claim about the
+                // document — and often said BECAUSE the store is out of date, which is
+                // exactly when not adopting it loses an edge that genuinely exists.
+                //
+                // Re-derived with NO cause: whatever moved was somebody else's doing, so
+                // attributing it to this edit would be wrong. `adopt` no-ops when the
+                // document already matches, so the ordinary case changes nothing.
+                adopt(result.document);
+                dropRecord(mutation.mutationId);
+                reDerive(undefined);
+                break;
+            }
+            case 'rejected': {
+                putRecord({
+                    mutationId: mutation.mutationId,
+                    mutation,
+                    state: 'failed',
+                    reason: result.reason,
+                });
+                break;
+            }
+            case 'conflict': {
+                putRecord({
+                    mutationId: mutation.mutationId,
+                    mutation,
+                    state: 'conflict',
+                    // Taken on rather than retained by reference: it is exposed through
+                    // `snapshot.writes`, so a consumer must not be able to edit the
+                    // adapter's own arrays through it.
+                    upstream: ownDocument(result.upstream),
+                });
+                break;
+            }
+        }
+        settle(mutation.mutationId);
+        publish();
+    }
+    /**
+     * Refuse or dispatch, and put the record in the ledger either way.
+     *
+     * A refusal is recorded and NEVER dispatched — "refused before any write" is
+     * a fact about the adapter not being called, not just about the colour of the
+     * edge, and that is what the tests assert.
+     */
+    function start(mutation) {
+        // The summary is evidence for ONE edit, and the contract is that it lasts
+        // until the next edit or an explicit dismissal. Clearing it here is what
+        // makes that true: left standing, a host would show the previous edit's
+        // blast radius beside the edit the user is making now.
+        lastChange = undefined;
+        currentProposal = mutation.mutationId;
+        const settled = new Promise((resolve) => settlers.set(mutation.mutationId, resolve));
+        const refusal = refusalFor(mutation);
+        if (refusal !== undefined) {
+            putRecord({ mutationId: mutation.mutationId, mutation, state: 'invalid', reason: refusal });
+            settle(mutation.mutationId);
+            publish();
+            return { mutationId: mutation.mutationId, settled };
+        }
+        putRecord({ mutationId: mutation.mutationId, mutation, state: 'pending' });
+        // ENQUEUE BEFORE NOTIFYING. `publish` runs subscribers synchronously, so a
+        // subscriber proposing a follow-up re-enters here — and if the queue does
+        // not yet hold this edit, the nested one takes its place in line and goes
+        // out first. Two edits on the same edge then apply in the reverse of the
+        // order the user made them.
+        queue.push({ kind: 'dispatch', mutation });
+        publish();
+        void drain();
+        return { mutationId: mutation.mutationId, settled };
+    }
+    /**
+     * Run the queue, one authoritative operation at a time — dispatches and
+     * document reads alike, since both answer with a document.
+     *
+     * An edit that WAITED is re-checked before it goes out, because `landed` may
+     * have moved under it — a sibling edit can delete the relationship this one
+     * retypes, and dispatching against a document that no longer admits it would
+     * defeat "refused before any write". An edit that did not wait keeps the
+     * verdict `start` already reached, so the guard is called once per edit in
+     * the ordinary case and twice only when the document genuinely moved.
+     */
+    async function drain() {
+        if (draining)
+            return;
+        draining = true;
+        try {
+            for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+                if (next.kind === 'load') {
+                    next.done(await runLoad(next.first));
+                    continue;
+                }
+                // ALWAYS re-checked, not only when something is known to have moved.
+                // Knowing that needs bookkeeping about document freshness, and every
+                // version of that bookkeeping this store has had was wrong in a way
+                // nobody could see. `refusalFor` is pure and cheap; asking it twice
+                // costs a great deal less than being wrong about when to ask.
+                const refusal = refusalFor(next.mutation);
+                if (refusal !== undefined) {
+                    putRecord({
+                        mutationId: next.mutation.mutationId,
+                        mutation: next.mutation,
+                        state: 'invalid',
+                        reason: refusal,
+                    });
+                    settle(next.mutation.mutationId);
+                    publish();
+                    continue;
+                }
+                await dispatch(next.mutation);
+            }
+        }
+        finally {
+            draining = false;
+        }
+    }
+    /** Queue a read of the document, behind whatever is already in flight. */
+    function load(first) {
+        return new Promise((resolve) => {
+            queue.push({ kind: 'load', first, done: resolve });
+            void drain();
+        });
+    }
+    /** A handle for a call that had nothing to act on. Already settled. */
+    function noop(mutationId) {
+        return { mutationId, settled: Promise.resolve() };
+    }
+    /** Read the document. Only ever called from the queue. */
+    /** Read the document. Resolves `true` when the read succeeded. */
+    async function runLoad(first) {
+        if (first) {
+            status = 'hydrating';
+            hydrationError = undefined;
+            publish();
+        }
+        try {
+            const document = await source.hydrate();
+            adopt(document);
+            status = 'ready';
+            hydrationError = undefined;
+            reDerive(undefined);
+        }
+        catch (thrown) {
+            hydrationError = messageOf(thrown);
+            // A failed refresh keeps the last good document and stays `ready`; only a
+            // first load that never produced one reports `failed`.
+            if (first)
+                status = 'failed';
+            publish();
+            return false;
+        }
+        publish();
+        return true;
+    }
+    return {
+        getSnapshot: () => published,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        hydrate: async () => {
+            await load(true);
+        },
+        rehydrate: async () => {
+            await load(false);
+        },
+        propose(proposal) {
+            sequence += 1;
+            // A per-store counter, not a random identifier: identities only have to
+            // be unique within one store, and a deterministic one keeps every test
+            // that reads a mutation id reproducible.
+            return start({ ...proposal, mutationId: `m${sequence}` });
+        },
+        retry(mutationId) {
+            const record = recordFor(mutationId);
+            if (record === undefined || record.state === 'pending')
+                return noop(mutationId);
+            return start(record.mutation);
+        },
+        /**
+         * Single-step on purpose: it reads the record and acts on it with no
+         * `await` in between, so nothing can change underneath it. A resolution
+         * that had to refresh first could not have that property, which is why the
+         * store does not offer one.
+         */
+        discardMine(mutationId) {
+            const record = recordFor(mutationId);
+            if (record === undefined || record.state === 'pending')
+                return;
+            dropRecord(mutationId);
+            publish();
+        },
+        select(edgeIds) {
+            selection = [...edgeIds];
+            publish();
+        },
+        dismissChange() {
+            lastChange = undefined;
+            publish();
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/validity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The document algebra, and the half of `invalid` that needs no graph walk.
+ *
+ * Pure and synchronous throughout: everything here answers "what would this
+ * edit produce" or "why can it not happen", and neither question has any
+ * business touching a network, a clock or the store's state.
+ *
+ * The split with {@link ../source.ts EdgeGuard} is by what the answer NEEDS TO
+ * SEE. A self-edge, an unknown reference and a duplicate are visible in the
+ * edit itself; a cycle is only visible by walking the graph, and the walk
+ * belongs with the derivation so the package family has one of it. Both halves
+ * produce the same refusal, and neither ever reaches `dispatch`.
+ */
+import { type EdgeId, type GraphDocument, type StoredEdge } from './model.ts';
+import type { InvalidReason, Mutation } from './mutation.ts';
+/**
+ * What an edit does to the projection: which landed edges it replaces, which
+ * edges it introduces, and which of them carry its state.
+ *
+ * A `delete` draws nothing and hides nothing — it MARKS the edge it is removing
+ * and leaves it visible. That is deliberate rather than a missing case: the
+ * design draws `failed` as a ghost with a ✕ terminal, and there is no ghost to
+ * draw if an optimistic delete has already taken the edge off the canvas. The
+ * edge leaves the document when the write lands, not when it is proposed.
+ */
+export interface EdgeChange {
+    readonly hidden: readonly EdgeId[];
+    readonly drawn: readonly StoredEdge[];
+    readonly marked: readonly EdgeId[];
+}
+/** The edge an edit produces, or `undefined` for one that produces none. */
+export declare function resultingEdge(document: GraphDocument, mutation: Mutation): StoredEdge | undefined;
+/** How an edit shows up in the projection while it is unlanded. */
+export declare function edgeChangeFor(document: GraphDocument, mutation: Mutation): EdgeChange;
+/** The document an edit would produce, if it landed exactly as proposed. */
+export declare function nextDocument(document: GraphDocument, mutation: Mutation): GraphDocument;
+/**
+ * Why this edit cannot happen, from the edit and the document alone.
+ *
+ * Returns `undefined` when nothing structural stands in the way — which is not
+ * the same as "valid": an injected guard runs afterwards and may still refuse.
+ */
+export declare function structuralRefusal(document: GraphDocument, mutation: Mutation): InvalidReason | undefined;
+//# sourceMappingURL=validity.d.ts.map

package/dist/validity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validity.d.ts","sourceRoot":"","sources":["../src/validity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EACL,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,UAAU,EAIhB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAejG;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,CA2BrF;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,aAAa,CASvF;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,QAAQ,GACjB,aAAa,GAAG,SAAS,CA2C3B"}