@graphty/graphty-element 2.5.1 → 2.6.0

package/dist/src/session/sets/dependencies.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @file What a definition depends on, and whether a chain of references loops
+ * (design/sets/sets-design.md sections 4.3 and 5.2).
+ *
+ * Dependencies are DERIVED from a definition, never stored. The walk:
+ *
+ * | Found                                                   | Dependency                          |
+ * |---------------------------------------------------------|-------------------------------------|
+ * | a `member` leaf `{ set: id }`                            | that set (follows it)               |
+ * | a `member` leaf `"visible"`, `"selection"`, `"search"`   | the visibility filter, the selection, the search |
+ * | a `member` leaf `"largest-component"`; `component`, `degree`, `neighborhood` | topology (the snapshot) |
+ * | a path `results.<run>.<field>` a query or `threshold` reads | that run (follows its current execution) |
+ * | an `item` leaf without `run`                            | that result (follows its current run) |
+ * | an `item` leaf with `run`                               | that run of the result (holds it)   |
+ * | any other path a query, `range`, `categories` or `threshold` reads | that top-level attribute field |
+ *
+ * A query's paths come from the compiled expression, which has no projections or wildcards, so
+ * every path is static. The visibility filter and the selection are nodes of this graph: that is
+ * what lets a door refuse a filter that reads `"visible"` through a kept set, and a set that
+ * reaches itself through the filter.
+ *
+ * The walk reads definitions this element could not validate (a loaded record holding an unknown
+ * leaf) as far as it can: a reference it recognises inside one still counts, so a stored set naming
+ * `"search"` is still caught.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { Path, Query, ResultItem, RuleTree, RunId, Scope, SetDefinition, SetId } from "../../catalog/types";
+import { GraphtyError } from "../../errors/GraphtyError";
+/** One thing a definition reads. */
+type Dependency = {
+    readonly kind: "set";
+    readonly id: SetId;
+} | {
+    readonly kind: "visible";
+} | {
+    readonly kind: "selection";
+} | {
+    readonly kind: "search";
+} | {
+    readonly kind: "topology";
+}
+/** `execution` present: the reference holds that execution; absent: it follows the run. */
+ | {
+    readonly kind: "run";
+    readonly run: RunId;
+    readonly execution?: string;
+} | {
+    readonly kind: "attribute";
+    readonly field: string;
+};
+/** A step of a reference chain: a set id, or one of the live keywords `"visible"`, `"selection"`, `"search"`. */
+export type ChainStep = string;
+/** Where the walk reads what a reference names. */
+export interface DependencySources {
+    /**
+     * What a `{ set: id }` names: a kept set's definition or a saved scope's specification.
+     * @param id - The id.
+     * @returns The definition or scope, or undefined when nothing holds the id.
+     */
+    readonly referent: (id: SetId) => SetDefinition | Scope | undefined;
+    /**
+     * The visibility filter in force, which is what `"visible"` depends on.
+     * @returns The filter, or null.
+     */
+    readonly visibility?: () => RuleTree | null;
+    /**
+     * The paths a query's compiled expression reads. Absent: a query's paths are not listed.
+     * @param where - The query.
+     * @returns The paths.
+     */
+    readonly pathsOf?: (where: Query) => readonly Path[];
+    /**
+     * The shape of a run's current result, which says whether an item's field is a partition
+     * group. Absent, or undefined for a run: nothing is known, and nothing is refused on it.
+     * @param run - The run.
+     * @returns The result shape.
+     */
+    readonly shapeOf?: (run: RunId) => string | undefined;
+    /**
+     * Which halves carry a value path, `results.<run>.<field>` or `data.<field>`, so a rule read
+     * `induced` over an edge field is refused. Absent: nothing is known.
+     * @param path - The path.
+     * @returns `"node"`, `"edge"` or both.
+     */
+    readonly fieldKinds?: (path: Path) => readonly string[];
+}
+/**
+ * What one path reads: a run's results, or a top-level attribute field.
+ * @param path - The path.
+ * @returns The run or the field.
+ */
+export declare function dependencyOf(path: Path): {
+    run: RunId;
+} | {
+    field: string;
+};
+/**
+ * What one definition, scope or rule tree reads directly, one of each, in the order met.
+ * @param value - A set definition, a scope, or a rule tree (the visibility filter).
+ * @param pathsOf - The paths a query reads; absent, queries list nothing.
+ * @returns The dependencies.
+ */
+export declare function dependenciesOf(value: SetDefinition | Scope | RuleTree, pathsOf?: (where: Query) => readonly Path[]): readonly Dependency[];
+/**
+ * The chain by which a definition written to set `id` would reach `id` itself, through `scope`
+ * leaves, saved scopes and the visibility filter.
+ * @param id - The set being written.
+ * @param definition - Its new definition.
+ * @param sources - Where references are looked up.
+ * @returns The chain, ending with `id`, or null when there is no cycle.
+ */
+export declare function setCycle(id: SetId, definition: SetDefinition, sources: DependencySources): ChainStep[] | null;
+/**
+ * The chain by which a visibility filter would read `"visible"` or `"search"`: what it computes.
+ * @param filter - The filter, or a scope inside one.
+ * @param sources - Where references are looked up.
+ * @returns The chain, ending with `"visible"` or `"search"`, or null.
+ */
+export declare function visibilityCycle(filter: RuleTree | Scope, sources: DependencySources): ChainStep[] | null;
+/**
+ * The chain by which a kept rule would read the live selection. Not followed through
+ * `"visible"`: a set may follow the visible graph whatever the filter reads.
+ * @param definition - The definition.
+ * @param sources - Where references are looked up.
+ * @returns The chain, ending with `"selection"`, or null.
+ */
+export declare function selectionChain(definition: SetDefinition, sources: DependencySources): ChainStep[] | null;
+/**
+ * How the set an id names reads, following saved scopes; undefined when nothing holds the id or
+ * the chain loops.
+ * @param sources - Where references are looked up.
+ * @returns The lookup.
+ */
+export declare function referentReading(sources: DependencySources): (id: SetId) => string | undefined;
+/**
+ * The first `item` leaf that follows a partition group across re-runs (the `group` field of a
+ * `community` result), in the value itself and the definitions it carries inline. A group number
+ * means nothing across re-runs, so such an item must hold its execution.
+ * @param value - A definition, a scope, or a rule tree.
+ * @param sources - Where a run's result shape is read; without `shapeOf` nothing is found.
+ * @returns The item, or null.
+ */
+export declare function followedGroup(value: SetDefinition | Scope | RuleTree, sources: DependencySources): ResultItem | null;
+/**
+ * The refusal of an item that follows a partition group.
+ * @param item - The item.
+ * @returns The error to throw.
+ */
+export declare function followsGroup(item: ResultItem): GraphtyError;
+/**
+ * Refuse a value that names a set id never issued in this session, at a write door. A removed
+ * set's id was issued, so it is accepted and reads as detached; only a typo, or an id from
+ * another session, is refused -- which would otherwise hide everything in a filter or paint
+ * nothing in a layer without a word.
+ * @param value - A set definition, a scope, a rule tree, or a selector's scope.
+ * @param ids - Which ids exist: the live records, and every id ever issued.
+ * @param ids.get - A live record by id.
+ * @param ids.register - Every id ever issued and committed.
+ * @param self - The id being written, which a definition may not name but is not unknown.
+ * @throws `E_BAD_COMMAND` with `details.reason` `"unknown-set"`.
+ */
+export declare function assertIssued(value: SetDefinition | Scope | RuleTree, ids: {
+    get(id: SetId): unknown;
+    register(): ReadonlySet<SetId>;
+}, self?: SetId): void;
+export {};

package/dist/src/session/sets/layers.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @file The live scopes style layers name (design/sets/sets-design.md section 11). Internal.
+ *
+ * A `{match:"member"}` layer tests one bit per element against its scope's live bitmap. Layers
+ * naming the same scope share one live entry, keyed by the scope's canonical form. An entry starts
+ * watching the first time a pass reads it: it subscribes to the session's change notifier with
+ * the scope's input signature, and holds the resolution it last took, pinned in the resolution
+ * cache so budget pressure never evicts what is on screen.
+ *
+ * When the scope moves on the same snapshot, the elements to repaint are exactly the old bitmap
+ * XOR the new one. Across a freeze the two bitmaps index different rows, so the old members are
+ * carried to the new rows by id, once per snapshot, and the repaint is the carried bitmap XOR the
+ * new resolution, on the scheduler's frame: a freeze that leaves the members alone repaints
+ * nothing. Until the frame the entry keeps its paint through the same carry, so a whole-graph pass
+ * that runs before it paints what was painted before.
+ *
+ * A scope that cannot be resolved -- a removed set, a cycle -- paints nothing, and the pass goes
+ * on. Nothing here throws into a pass.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import type { Scope } from "../../catalog/types";
+import type { LiveScope } from "../styles/predicate";
+import type { ElementIndices } from "../styles/repaint";
+import type { SetWatch } from "./notify";
+import type { Resolution } from "./resolve";
+/** What one entry holds: its resolution, or null for a scope that paints nothing. */
+interface Held {
+    readonly resolution: Resolution | null;
+    /** The snapshot it was resolved against. */
+    readonly graph: GraphSnapshot;
+    readonly problem?: string;
+}
+/** Everything the live scopes read from their session. */
+interface LayerScopeSources {
+    /**
+     * The snapshot the session holds now.
+     * @returns The snapshot.
+     */
+    snapshot(): GraphSnapshot;
+    /**
+     * Resolve a scope through the cache.
+     * @param scope - The scope.
+     * @returns The resolution and the snapshot it covers; throws a `GraphtyError` when it cannot.
+     */
+    resolve(scope: Scope): {
+        readonly resolution: Resolution;
+        readonly graph: GraphSnapshot;
+    };
+    /**
+     * The scope's input signature now.
+     * @param scope - The scope.
+     * @returns The signature, or null when its inputs cannot be enumerated.
+     */
+    signature(scope: Scope): string | null;
+    /**
+     * Watch through the session's notifier.
+     * @param watch - The watch.
+     * @returns Stops watching.
+     */
+    subscribe(watch: SetWatch<Held>): () => void;
+    /**
+     * Pin the scope's current cache entry.
+     * @param scope - The scope.
+     * @returns Releases the pin.
+     */
+    pin(scope: Scope): () => void;
+    /**
+     * Repaint elements whose membership moved.
+     * @param dirty - The indices, per half.
+     * @returns Settles when the repaint has finished, or nothing when it is not awaitable.
+     */
+    repaint(dirty: ElementIndices): Promise<unknown> | undefined;
+}
+/** The live scopes of one session's style layers. */
+export declare class LayerScopes {
+    #private;
+    /**
+     * Build over a session. Whole-graph repaints the entries ask for are coalesced: while one is
+     * running, every further request becomes one more pass after it, over the graph as it then
+     * stands. After a freeze each live set asks for one as its resolution arrives, frame by frame,
+     * so ten live sets would otherwise cost ten whole-graph passes.
+     * @param sources - The session.
+     */
+    constructor(sources: LayerScopeSources);
+    /**
+     * The live membership of a scope, shared by every layer naming it.
+     * @param scope - The scope, already checked.
+     * @returns Its live membership.
+     */
+    live(scope: Scope): LiveScope;
+    /**
+     * Keep only the entries the stack names; the rest stop watching and release their pins.
+     * @param scopes - The scopes the stack's layers name.
+     */
+    keep(scopes: Iterable<Scope>): void;
+    /** Stop every entry. */
+    dispose(): void;
+}
+export {};

package/dist/src/session/sets/notify.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file Change notification and the re-resolution scheduler (design/sets/sets-design.md sections
+ * 6.2 and 11). Internal.
+ *
+ * A live user of a set -- a style layer, the visibility filter -- WATCHES it: it hands in the input
+ * signature of everything it reads (`./signature`), how to resolve it, and where the new
+ * resolution goes. Six hooks tell the notifier that an input moved:
+ *
+ * - the sets store's committed diff (`SetsStore.onCommit`), before any `set:changed`;
+ * - a selection change and a visibility change, before their public events;
+ * - a run moving its result: queued for a re-run (the result is cleared), finished, or removed;
+ * - an attribute write after load (`Graph.updateNodes`), announced once per batch on the store
+ *   owner's input tick;
+ * - a snapshot replacement, announced on the same tick once a freeze has been delivered.
+ *
+ * Ingest writes attributes too, but announces nothing: it also touches the store, and the freeze
+ * that follows re-queues every watch. Announcing it would make a watch resolve mid-load and force
+ * a freeze per ingested chunk.
+ *
+ * On the SAME snapshot a notification is synchronous: every watch whose signature moved resolves
+ * at once and is handed the new resolution with the inputs that moved, so a layer can repaint the
+ * XOR of old and new before any public event fires. A watch whose signature did not move is not
+ * asked to resolve.
+ *
+ * A SNAPSHOT REPLACEMENT is not: every freeze moves every signature (the serial is in all of them),
+ * and re-resolving every live set in one turn would hold the thread. Each watch is queued and the
+ * queue is worked frame by frame within a per-frame work budget, counted in the elements each
+ * resolution walks as the watch estimates them, never timed. A watch keeps its previous resolution
+ * until its new one is ready. A second freeze mid-way adds nothing twice: a watch still queued is
+ * resolved once, against the newest snapshot, and a watch already done is queued again and
+ * resolved only if its signature moved again.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { RunId, SetId } from "../../catalog/types";
+/** One input that moved, as a watch is told. OPEN UNION. */
+export type MovedInput = {
+    readonly kind: "sets";
+    readonly ids: readonly SetId[];
+} | {
+    readonly kind: "selection";
+} | {
+    readonly kind: "visibility";
+} | {
+    readonly kind: "run";
+    readonly run: RunId;
+} | {
+    readonly kind: "attributes";
+    readonly element: "node" | "edge";
+    readonly fields: readonly string[];
+} | {
+    readonly kind: "snapshot";
+    readonly serial: number;
+};
+/** One live user of a set. */
+export interface SetWatch<R> {
+    /**
+     * The input signature of everything it reads now.
+     * @returns the signature, or null when its inputs cannot be enumerated (always re-resolved)
+     */
+    signature(): string | null;
+    /**
+     * Resolve now, against the current snapshot and inputs.
+     * @returns the new resolution
+     */
+    resolve(): R;
+    /**
+     * Take a new resolution.
+     * @param resolution - what {@link SetWatch.resolve} returned
+     * @param moved - every input reported since its previous resolution, oldest first
+     */
+    ready(resolution: R, moved: readonly MovedInput[]): void;
+    /**
+     * What one resolution costs against the per-frame budget.
+     * @returns the elements it walks, estimated
+     */
+    cost(): number;
+}
+/**
+ * Asks for one call on the next frame.
+ * @param callback - what to call
+ * @returns cancels the request
+ */
+type FrameSource = (callback: () => void) => () => void;
+/** The notifier and scheduler of one session. */
+export declare class SetsNotifier {
+    #private;
+    /**
+     * Start with nothing watched and nothing queued.
+     * @param options - the frame source and the per-frame budget, for tests
+     * @param options.frames - asks for the next frame; a timer by default
+     * @param options.budget - elements resolved per frame
+     */
+    constructor(options?: {
+        frames?: FrameSource;
+        budget?: number;
+    });
+    /**
+     * Watch a set. Its current resolution is the caller's; the signature it stands for is read now.
+     * @param watch - the watch
+     * @returns stops watching, and drops it from the queue
+     */
+    subscribe<R>(watch: SetWatch<R>): () => void;
+    /**
+     * Report that one input moved.
+     * @param input - what moved
+     */
+    notify(input: MovedInput): void;
+    /**
+     * Use another frame source from now on (the element's render loop).
+     * @param frames - the source
+     */
+    useFrames(frames: FrameSource): void;
+    /**
+     * Watches waiting for a frame.
+     * @returns how many
+     */
+    get pending(): number;
+    /** Cancel the queued work and drop every watch. */
+    dispose(): void;
+}
+export {};

package/dist/src/session/sets/offers.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file Offered sets and Memberships (design/sets/sets-design.md sections 8.2 and 15.2).
+ *
+ * A finished run's result OFFERS sets by its shape, never by its algorithm, so every registered
+ * algorithm gets them: one per group of a partition, one per level, one per category, one for a
+ * node or edge set, one for a path. An offer is a rule over one held item; using it as a scope
+ * writes nothing.
+ *
+ * Counting is split by what it reads. Node counts of an offer read `induced` need only the
+ * result's values, one pass over the nodes, cached per execution and snapshot. Everything that
+ * needs the edge list -- the edges of every item, and the nodes of an item read `listed`, which
+ * include its edges' endpoints -- comes from ONE pass over the edges, cached the same way and run
+ * by the first resolution of an offer, never by `offers`.
+ *
+ * MEMBERSHIPS answer "what holds this element" without resolving what they need not: a cached
+ * resolution is tested when there is one, a fixed set of nodes alone is a binary search of them, a
+ * rule of element-local leaves is compiled and tested at the one index, and anything else is
+ * resolved once through the cache.
+ *
+ * Node-safe.
+ */
+import type { EdgeId, NodeId, RunId } from "../../catalog/types";
+import type { RunResult } from "../results/types";
+import type { FilterRunResult } from "../visibility/filter";
+import { type ResolveContext } from "./resolve";
+import type { ElementSet, Memberships, SetOffer } from "./types";
+/** Counts the offers tests read. */
+export declare const offerCounters: {
+    nodeScans: number;
+    edgePasses: number;
+};
+/** One run as offers read it. */
+interface OfferRun {
+    readonly id: RunId;
+    readonly label: string;
+    /** Its current result, or undefined before it has one. */
+    readonly result: RunResult | undefined;
+}
+/** What offers and Memberships read from the session. */
+interface OfferSources {
+    /**
+     * A run.
+     * @param id - Its id.
+     * @returns The run, or undefined when the session holds none.
+     */
+    run(id: RunId): OfferRun | undefined;
+    /** Every run, in the session's order. */
+    runs(): readonly OfferRun[];
+    /**
+     * A run's current result by dense index, with its execution token.
+     * @param id - The run.
+     * @returns The values, or undefined when it has no result.
+     */
+    values(id: RunId): FilterRunResult | undefined;
+    /** What a resolution reads now: the snapshot, the cache, the readers. */
+    context(): ResolveContext;
+    /** The kept sets, in listing order. */
+    sets(): readonly ElementSet[];
+}
+/** Offers and Memberships over one session. */
+export interface Offering {
+    /**
+     * The offers of a run's result, largest first.
+     * @param run - The run.
+     * @param limit - The most to return.
+     * @returns The offers and how many were left out.
+     * @throws `E_UNKNOWN_RUN` for a run the session does not hold.
+     */
+    offers(run: RunId, limit?: number): {
+        readonly offers: readonly SetOffer[];
+        readonly more: number;
+    };
+    /**
+     * Run a run's edge-count pass over the current snapshot unless it is cached. The first
+     * resolution of an offer calls this.
+     * @param run - The run.
+     */
+    countEdges(run: RunId): void;
+    /**
+     * A path offer's node order: the `order` value of a node index.
+     * @param run - The run.
+     * @returns A reader of the value, or undefined when the run has no result.
+     */
+    orderOf(run: RunId): ((index: number) => unknown) | undefined;
+    /**
+     * What holds one element.
+     * @param element - The node or edge.
+     * @returns The memberships.
+     * @throws `E_BAD_COMMAND` for an element the graph does not hold.
+     */
+    memberships(element: {
+        readonly node: NodeId;
+    } | {
+        readonly edge: EdgeId;
+    }): Memberships;
+}
+/**
+ * Build offers and Memberships over a session.
+ * @param sources - What they read.
+ * @returns The offering.
+ */
+export declare function createOffering(sources: OfferSources): Offering;
+export {};

package/dist/src/session/sets/path.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Path resolution (design/sets/sets-design.md section 4.4).
+ *
+ * A path set resolves to its distinct nodes and the edges its steps name, read `listed`. A step
+ * that names an edge or a group of edges contributes the ones bound in the snapshot (through the
+ * binding table, as a fixed set's edge members do); a `null` step, or a path with no `edges`,
+ * contributes every edge between its pair. Under `directed: true` only edges running from
+ * `nodes[i]` to `nodes[i + 1]` count. A step with no edge left counts missing. Nothing throws.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { PathKind, SetDefinition } from "../../catalog/types";
+import { type EdgeSeeds, type Resolution, type ResolveContext } from "./resolve";
+/** A path definition. */
+type PathDefinition = Extract<SetDefinition, {
+    kind: "path";
+}>;
+/**
+ * What a path covers in the context snapshot.
+ * @param definition - A canonical path definition.
+ * @param context - What the resolution reads.
+ * @param seeds - The set's seeds, for a kept set.
+ * @returns The resolution: `missingNodes` counts distinct walk nodes the graph does not hold,
+ *     `missingEdges` the steps with no edge, `ambiguousEdges` the named members two edges carry.
+ */
+export declare function resolvePath(definition: PathDefinition, context: ResolveContext, seeds?: EdgeSeeds): Resolution;
+/**
+ * What kind of walk a path is (design 4.4). Each step is one logical edge, keyed on the group of
+ * edges it names, or on its end pair for a `null` step (unordered unless `directed`). `trail`: no
+ * logical edge repeats; `simple`: no node repeats; `cycle`: a closed trail of at least one step
+ * whose only repeated node is the first, equal to the last; `walk`: anything else. The most
+ * specific kind is returned. Derived from the definition alone: never resolves.
+ * @param definition - A canonical path definition.
+ * @returns The kind.
+ */
+export declare function pathKind(definition: PathDefinition): PathKind;
+export {};