@graview/core 0.1.0

package/dist/graph/graph.js

@@ -0,0 +1,284 @@
+import { humaniseField, labelOf } from "../schema/define-node.js";
+import { SchemaError } from "../schema/schema.js";
+import { diffSnapshots } from "./diff.js";
+import { isUnset } from "./primitives.js";
+import { edgeId } from "./types.js";
+/**
+ * A validator's complaint, said in words.
+ *
+ * Zod's own `message` is the whole issue list as JSON. Each issue already
+ * carries a readable sentence and the path it is about, so the field is
+ * named the way the rest of the interface names it and the sentences are
+ * joined — nothing else in the object is for a person.
+ */
+function readably(error) {
+    const issues = error
+        ?.issues;
+    if (!Array.isArray(issues) || issues.length === 0) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    return issues
+        .map((issue) => {
+        const field = issue.path?.length ? humaniseField(String(issue.path.at(-1))) : null;
+        const said = issue.message ?? "is not what the declaration allows";
+        return field ? `${field}: ${said}` : said;
+    })
+        .join("; ");
+}
+export class GraphError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(hint ? `${message}\n  ${hint}` : message);
+        this.hint = hint;
+        this.name = "GraphError";
+    }
+}
+/**
+ * The framework owns the reactive in-memory graph. Owning it — rather than
+ * reading someone else's store — is what makes invariants enforceable and
+ * agent attribution free; persistence is a pluggable adapter underneath.
+ */
+export class Graph {
+    schema;
+    nodes = new Map();
+    edges = new Map();
+    outIndex = new Map();
+    inIndex = new Map();
+    listeners = new Set();
+    validate;
+    constructor(schema, options = {}) {
+        this.schema = schema;
+        this.validate = options.validate ?? true;
+    }
+    static from(schema, snapshot, options = {}) {
+        const graph = new Graph(schema, options);
+        graph.load(snapshot);
+        return graph;
+    }
+    /** Replaces the whole graph without emitting a per-node diff storm. */
+    load(snapshot) {
+        const before = this.snapshot();
+        this.nodes.clear();
+        this.edges.clear();
+        this.outIndex.clear();
+        this.inIndex.clear();
+        for (const node of snapshot.nodes)
+            this.insertNode(node);
+        for (const edge of snapshot.edges)
+            this.insertEdge(edge);
+        const diff = diffSnapshots(before, this.snapshot());
+        this.emit(diff);
+        return diff;
+    }
+    // ---------------------------------------------------------------- reads
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    has(id) {
+        return this.nodes.has(id);
+    }
+    allNodes() {
+        return [...this.nodes.values()];
+    }
+    allEdges() {
+        return [...this.edges.values()];
+    }
+    nodesOfKind(kind) {
+        return this.allNodes().filter((node) => node.kind === kind);
+    }
+    edgesOfKind(kind) {
+        return this.allEdges().filter((edge) => edge.kind === kind);
+    }
+    out(id, kind) {
+        return this.resolve(this.outIndex.get(id), kind, "to");
+    }
+    in(id, kind) {
+        return this.resolve(this.inIndex.get(id), kind, "from");
+    }
+    neighbors(id) {
+        const seen = new Map();
+        for (const node of [...this.out(id), ...this.in(id)])
+            seen.set(node.id, node);
+        return [...seen.values()];
+    }
+    /** Edges leaving `id`, optionally of one kind. */
+    outEdges(id, kind) {
+        return this.edgesFrom(this.outIndex.get(id), kind);
+    }
+    /** Edges arriving at `id`, optionally of one kind. */
+    inEdges(id, kind) {
+        return this.edgesFrom(this.inIndex.get(id), kind);
+    }
+    snapshot() {
+        return { nodes: this.allNodes(), edges: this.allEdges() };
+    }
+    get size() {
+        return { nodes: this.nodes.size, edges: this.edges.size };
+    }
+    // ------------------------------------------------------------- writes
+    /**
+     * Applies primitives as one batch and emits a single diff. Nothing outside
+     * the op log should call this directly — attribution lives in the log.
+     */
+    applyPrimitives(primitives) {
+        const before = this.snapshot();
+        for (const primitive of primitives)
+            this.applyOne(primitive);
+        const diff = diffSnapshots(before, this.snapshot());
+        this.emit(diff);
+        return diff;
+    }
+    /** Applies primitives to a throwaway copy — used for previewing a diff. */
+    preview(primitives) {
+        const copy = Graph.from(this.schema, this.snapshot(), { validate: this.validate });
+        return copy.applyPrimitives(primitives);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    // ------------------------------------------------------------ internals
+    emit(diff) {
+        if (diff.addedNodes.length === 0 &&
+            diff.removedNodes.length === 0 &&
+            diff.changedNodes.length === 0 &&
+            diff.addedEdges.length === 0 &&
+            diff.removedEdges.length === 0) {
+            return;
+        }
+        for (const listener of this.listeners)
+            listener(diff);
+    }
+    applyOne(primitive) {
+        switch (primitive.op) {
+            case "add-node":
+                this.insertNode(primitive.node);
+                return;
+            case "remove-node": {
+                const id = primitive.node.id;
+                if (!this.nodes.has(id)) {
+                    throw new GraphError(`Cannot remove missing node "${id}"`);
+                }
+                for (const edge of [...this.outEdges(id), ...this.inEdges(id)]) {
+                    this.deleteEdge(edge);
+                }
+                this.nodes.delete(id);
+                this.outIndex.delete(id);
+                this.inIndex.delete(id);
+                return;
+            }
+            case "patch-node": {
+                const current = this.nodes.get(primitive.id);
+                if (!current) {
+                    throw new GraphError(`Cannot patch missing node "${primitive.id}"`);
+                }
+                const next = { ...current };
+                for (const [key, value] of Object.entries(primitive.after)) {
+                    // `undefined` in memory, `UNSET` once written down: both mean the
+                    // key goes away. See `normalise` in primitives.ts.
+                    if (isUnset(value))
+                        delete next[key];
+                    else
+                        next[key] = value;
+                }
+                this.nodes.set(primitive.id, this.check(next));
+                return;
+            }
+            case "add-edge":
+                this.insertEdge(primitive.edge);
+                return;
+            case "remove-edge": {
+                if (!this.edges.has(edgeId(primitive.edge))) {
+                    throw new GraphError(`Cannot remove missing edge ${edgeId(primitive.edge)}`);
+                }
+                this.deleteEdge(primitive.edge);
+                return;
+            }
+        }
+    }
+    check(node) {
+        if (!this.validate)
+            return node;
+        try {
+            return this.schema.parseNode(node);
+        }
+        catch (error) {
+            if (error instanceof SchemaError)
+                throw error;
+            const id = node?.id ?? "?";
+            const kind = node?.kind ?? "?";
+            /*
+             * A PERSON READS THIS. It is not only a developer's console message:
+             * a refused undo shows its reason in the activity rail, so the raw
+             * validator dump — `[ { "code": "invalid_value", "values": [ … ],
+             * "path": [ "urgency" ] … } ]` — went straight into the interface,
+             * beside a sentence about a thing called "Pay the deposit". The field
+             * is named in the app's own words and the node by its label.
+             */
+            const definition = this.schema.tryDefinition(kind);
+            const named = definition && node && typeof node === "object"
+                ? labelOf(definition, node)
+                : id;
+            throw new GraphError(`${named} does not match what ${kind} declares`, readably(error));
+        }
+    }
+    insertNode(node) {
+        if (this.nodes.has(node.id)) {
+            throw new GraphError(`Duplicate node id "${node.id}"`);
+        }
+        this.nodes.set(node.id, this.check(node));
+    }
+    insertEdge(edge) {
+        const from = this.nodes.get(edge.from);
+        const to = this.nodes.get(edge.to);
+        if (!from || !to) {
+            throw new GraphError(`Edge "${edge.kind}" references missing node "${from ? edge.to : edge.from}"`);
+        }
+        if (this.validate && !this.schema.edgeAllowed(edge.kind, from.kind, to.kind)) {
+            const declared = this.schema.edge(edge.kind);
+            throw new GraphError(`Edge "${edge.kind}" is not declared from ${from.kind} to ${to.kind}`, declared
+                ? `Declared: ${declared.from.join("|")} -> ${declared.to === "*" ? "*" : declared.to.join("|")}`
+                : `No edge kind "${edge.kind}" is declared in this schema`);
+        }
+        const id = edgeId(edge);
+        if (this.edges.has(id))
+            return;
+        this.edges.set(id, edge);
+        this.index(this.outIndex, edge.from, id);
+        this.index(this.inIndex, edge.to, id);
+    }
+    deleteEdge(edge) {
+        const id = edgeId(edge);
+        this.edges.delete(id);
+        this.outIndex.get(edge.from)?.delete(id);
+        this.inIndex.get(edge.to)?.delete(id);
+    }
+    index(map, key, id) {
+        const set = map.get(key);
+        if (set)
+            set.add(id);
+        else
+            map.set(key, new Set([id]));
+    }
+    edgesFrom(ids, kind) {
+        if (!ids)
+            return [];
+        const result = [];
+        for (const id of ids) {
+            const edge = this.edges.get(id);
+            if (edge && (kind === undefined || edge.kind === kind))
+                result.push(edge);
+        }
+        return result;
+    }
+    resolve(ids, kind, end) {
+        const result = [];
+        for (const edge of this.edgesFrom(ids, kind)) {
+            const node = this.nodes.get(edge[end]);
+            if (node)
+                result.push(node);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph/graph.js.map

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

package/dist/graph/primitives.d.ts

@@ -0,0 +1,52 @@
+import type { AnyGraphNode, GraphEdge } from "./types.js";
+/**
+ * The five primitive operations every mutation compiles down to. Keeping the
+ * primitive set this small is what makes inverses mechanical and the fold
+ * over the log total.
+ */
+export type Primitive = {
+    readonly op: "add-node";
+    readonly node: AnyGraphNode;
+} | {
+    readonly op: "remove-node";
+    readonly node: AnyGraphNode;
+} | {
+    readonly op: "patch-node";
+    readonly id: string;
+    readonly before: Readonly<Record<string, unknown>>;
+    readonly after: Readonly<Record<string, unknown>>;
+} | {
+    readonly op: "add-edge";
+    readonly edge: GraphEdge;
+} | {
+    readonly op: "remove-edge";
+    readonly edge: GraphEdge;
+};
+/**
+ * "THIS KEY GOES AWAY", written down.
+ *
+ * A patch says "remove this field" by carrying the key with the value
+ * `undefined` — which is fine in memory and vanishes the moment the op is
+ * written to JSON. So every persisted patch that cleared a field came back
+ * with an empty `before`, and its inverse — the whole promise of an op log —
+ * silently did nothing. A migration that added a field could be "undone"
+ * after a reload and leave the field exactly where it was.
+ *
+ * `UNSET` is that instruction as a value. It survives JSON, it survives an
+ * export bundle, and `normalise` puts it in front of every primitive on its
+ * way into an operation so nobody writing a mutation has to know.
+ */
+export declare const UNSET = "\0graview:unset";
+/** Whether a patch value means "take this key off the node". */
+export declare const isUnset: (value: unknown) => boolean;
+/**
+ * A primitive with every "remove this key" said as a value rather than as an
+ * absence. Applied where primitives become operations, so the log, the
+ * adapters and the export all carry the same instruction.
+ */
+export declare function normalise(primitive: Primitive): Primitive;
+/** Every primitive's inverse is another primitive — no special cases. */
+export declare function invert(primitive: Primitive): Primitive;
+/** Node ids a primitive writes to. */
+export declare function writesOf(primitive: Primitive): string[];
+//# sourceMappingURL=primitives.d.ts.map

package/dist/graph/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/graph/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC3D;IACE,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,oBAAwB,CAAC;AAE3C,gEAAgE;AAChE,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,OAAiD,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAOzD;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAkBtD;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,EAAE,CAWvD"}

package/dist/graph/primitives.js

@@ -0,0 +1,62 @@
+/**
+ * "THIS KEY GOES AWAY", written down.
+ *
+ * A patch says "remove this field" by carrying the key with the value
+ * `undefined` — which is fine in memory and vanishes the moment the op is
+ * written to JSON. So every persisted patch that cleared a field came back
+ * with an empty `before`, and its inverse — the whole promise of an op log —
+ * silently did nothing. A migration that added a field could be "undone"
+ * after a reload and leave the field exactly where it was.
+ *
+ * `UNSET` is that instruction as a value. It survives JSON, it survives an
+ * export bundle, and `normalise` puts it in front of every primitive on its
+ * way into an operation so nobody writing a mutation has to know.
+ */
+export const UNSET = "\u0000graview:unset";
+/** Whether a patch value means "take this key off the node". */
+export const isUnset = (value) => value === undefined || value === UNSET;
+/**
+ * A primitive with every "remove this key" said as a value rather than as an
+ * absence. Applied where primitives become operations, so the log, the
+ * adapters and the export all carry the same instruction.
+ */
+export function normalise(primitive) {
+    if (primitive.op !== "patch-node")
+        return primitive;
+    const said = (fields) => Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, value === undefined ? UNSET : value]));
+    return { ...primitive, before: said(primitive.before), after: said(primitive.after) };
+}
+/** Every primitive's inverse is another primitive — no special cases. */
+export function invert(primitive) {
+    switch (primitive.op) {
+        case "add-node":
+            return { op: "remove-node", node: primitive.node };
+        case "remove-node":
+            return { op: "add-node", node: primitive.node };
+        case "patch-node":
+            return {
+                op: "patch-node",
+                id: primitive.id,
+                before: primitive.after,
+                after: primitive.before,
+            };
+        case "add-edge":
+            return { op: "remove-edge", edge: primitive.edge };
+        case "remove-edge":
+            return { op: "add-edge", edge: primitive.edge };
+    }
+}
+/** Node ids a primitive writes to. */
+export function writesOf(primitive) {
+    switch (primitive.op) {
+        case "add-node":
+        case "remove-node":
+            return [primitive.node.id];
+        case "patch-node":
+            return [primitive.id];
+        case "add-edge":
+        case "remove-edge":
+            return [primitive.edge.from, primitive.edge.to];
+    }
+}
+//# sourceMappingURL=primitives.js.map

package/dist/graph/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/graph/primitives.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,qBAAqB,CAAC;AAE3C,gEAAgE;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK,CAAC;AAE3F;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAoB;IAC5C,IAAI,SAAS,CAAC,EAAE,KAAK,YAAY;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,MAAyC,EAA2B,EAAE,CAClF,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CACzF,CAAC;IACJ,OAAO,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,SAAoB;IACzC,QAAQ,SAAS,CAAC,EAAE,EAAE,CAAC;QACrB,KAAK,UAAU;YACb,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QACrD,KAAK,aAAa;YAChB,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QAClD,KAAK,YAAY;YACf,OAAO;gBACL,EAAE,EAAE,YAAY;gBAChB,EAAE,EAAE,SAAS,CAAC,EAAE;gBAChB,MAAM,EAAE,SAAS,CAAC,KAAK;gBACvB,KAAK,EAAE,SAAS,CAAC,MAAM;aACxB,CAAC;QACJ,KAAK,UAAU;YACb,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QACrD,KAAK,aAAa;YAChB,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;IACpD,CAAC;AACH,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,QAAQ,CAAC,SAAoB;IAC3C,QAAQ,SAAS,CAAC,EAAE,EAAE,CAAC;QACrB,KAAK,UAAU,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7B,KAAK,YAAY;YACf,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACxB,KAAK,UAAU,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;AACH,CAAC"}

package/dist/graph/tracked.d.ts

@@ -0,0 +1,31 @@
+import type { GraphEdge, GraphNodeBase, GraphReader } from "./types.js";
+/**
+ * Records every node a mutation looked at.
+ *
+ * Reads-tracking has to exist from the very first operation — historical
+ * reads are not recoverable, so this cannot be retrofitted onto an existing
+ * log. That constraint is why the mutation API hands out a reader rather
+ * than the graph itself.
+ */
+export declare class TrackedReader<N extends GraphNodeBase> implements GraphReader<N> {
+    private readonly inner;
+    private readonly seen;
+    constructor(inner: GraphReader<N>);
+    /** The ids this mutation read, in insertion order. */
+    reads(): string[];
+    private mark;
+    private markAll;
+    private markEdges;
+    getNode(id: string): N | undefined;
+    has(id: string): boolean;
+    allNodes(): N[];
+    allEdges(): GraphEdge[];
+    nodesOfKind<K extends N["kind"]>(kind: K): Extract<N, {
+        kind: K;
+    }>[];
+    edgesOfKind(kind: string): GraphEdge[];
+    out(id: string, kind?: string): N[];
+    in(id: string, kind?: string): N[];
+    neighbors(id: string): N[];
+}
+//# sourceMappingURL=tracked.d.ts.map

package/dist/graph/tracked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracked.d.ts","sourceRoot":"","sources":["../../src/graph/tracked.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;GAOG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,aAAa,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAG/D,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAEb,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;IAElD,sDAAsD;IACtD,KAAK,IAAI,MAAM,EAAE;IAIjB,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKlC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAKxB,QAAQ,IAAI,CAAC,EAAE;IAIf,QAAQ,IAAI,SAAS,EAAE;IAIvB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,EAAE;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IAItC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAKnC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAKlC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,EAAE;CAI3B"}

package/dist/graph/tracked.js

@@ -0,0 +1,69 @@
+/**
+ * Records every node a mutation looked at.
+ *
+ * Reads-tracking has to exist from the very first operation — historical
+ * reads are not recoverable, so this cannot be retrofitted onto an existing
+ * log. That constraint is why the mutation API hands out a reader rather
+ * than the graph itself.
+ */
+export class TrackedReader {
+    inner;
+    seen = new Set();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /** The ids this mutation read, in insertion order. */
+    reads() {
+        return [...this.seen];
+    }
+    mark(node) {
+        if (node)
+            this.seen.add(node.id);
+        return node;
+    }
+    markAll(nodes) {
+        for (const node of nodes)
+            this.seen.add(node.id);
+        return nodes;
+    }
+    markEdges(edges) {
+        for (const edge of edges) {
+            this.seen.add(edge.from);
+            this.seen.add(edge.to);
+        }
+        return edges;
+    }
+    getNode(id) {
+        this.seen.add(id);
+        return this.mark(this.inner.getNode(id));
+    }
+    has(id) {
+        this.seen.add(id);
+        return this.inner.has(id);
+    }
+    allNodes() {
+        return this.markAll(this.inner.allNodes());
+    }
+    allEdges() {
+        return this.markEdges(this.inner.allEdges());
+    }
+    nodesOfKind(kind) {
+        return this.markAll(this.inner.nodesOfKind(kind));
+    }
+    edgesOfKind(kind) {
+        return this.markEdges(this.inner.edgesOfKind(kind));
+    }
+    out(id, kind) {
+        this.seen.add(id);
+        return this.markAll(this.inner.out(id, kind));
+    }
+    in(id, kind) {
+        this.seen.add(id);
+        return this.markAll(this.inner.in(id, kind));
+    }
+    neighbors(id) {
+        this.seen.add(id);
+        return this.markAll(this.inner.neighbors(id));
+    }
+}
+//# sourceMappingURL=tracked.js.map

package/dist/graph/tracked.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracked.js","sourceRoot":"","sources":["../../src/graph/tracked.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IAGK;IAFZ,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE1C,YAA6B,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAG,CAAC;IAEtD,sDAAsD;IACtD,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAEO,IAAI,CAA0B,IAAO;QAC3C,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,OAAO,CAAc,KAAU;QACrC,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,SAAS,CAAC,KAAkB;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,WAAW,CAAsB,IAAO;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,GAAG,CAAC,EAAU,EAAE,IAAa;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,EAAE,CAAC,EAAU,EAAE,IAAa;QAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;CACF"}

package/dist/graph/types.d.ts

@@ -0,0 +1,34 @@
+export interface GraphEdge {
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** Stable identity for an edge — edges have no id of their own. */
+export declare function edgeId(edge: GraphEdge): string;
+export interface GraphNodeBase {
+    readonly id: string;
+    readonly kind: string;
+}
+export type AnyGraphNode = GraphNodeBase & Record<string, unknown>;
+/** The read surface a mutation sees. Every method here is instrumented. */
+export interface GraphReader<N extends GraphNodeBase = AnyGraphNode> {
+    getNode(id: string): N | undefined;
+    allNodes(): N[];
+    allEdges(): GraphEdge[];
+    nodesOfKind<K extends N["kind"]>(kind: K): Extract<N, {
+        kind: K;
+    }>[];
+    edgesOfKind(kind: string): GraphEdge[];
+    /** Nodes reached by following `kind` edges out of `id`. */
+    out(id: string, kind?: string): N[];
+    /** Nodes with a `kind` edge pointing at `id`. */
+    in(id: string, kind?: string): N[];
+    /** Every node one edge away, in either direction. */
+    neighbors(id: string): N[];
+    has(id: string): boolean;
+}
+export interface GraphSnapshot<N extends GraphNodeBase = AnyGraphNode> {
+    readonly nodes: readonly N[];
+    readonly edges: readonly GraphEdge[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnE,2EAA2E;AAC3E,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,aAAa,GAAG,YAAY;IACjE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,QAAQ,IAAI,CAAC,EAAE,CAAC;IAChB,QAAQ,IAAI,SAAS,EAAE,CAAC;IACxB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,EAAE,CAAC;IACrE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IACvC,2DAA2D;IAC3D,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IACpC,iDAAiD;IACjD,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IACnC,qDAAqD;IACrD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,aAAa,GAAG,YAAY;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC"}

package/dist/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"AAMA,mEAAmE;AACnE,MAAM,UAAU,MAAM,CAAC,IAAe;IACpC,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;AAChD,CAAC"}