@graphty/graphty-element 2.5.2 → 2.6.1

package/dist/src/algorithms/utils/graphUtils.d.ts

@@ -1,5 +1,6 @@
 /**
- * @file Utility functions for building graph data structures from graphty-element Graph
+ * @file Helpers the adapters share: matching an `@graphty/algorithms` answer back onto an edge,
+ * and refusing a node option that names no node.
  */
 /**
  * The key an `@graphty/algorithms` result is matched back onto the element's edges by: the two
@@ -28,70 +29,3 @@ export declare function edgePairKey(source: string | number, target: string | nu
  * @throws A `GraphtyError` coded `E_OPTION_RANGE` when no node has that id.
  */
 export declare function requireNodeOption(algorithm: string, option: string, value: string | number, nodeIds: readonly (string | number)[]): string;
-/**
- * Minimal edge data interface required by graph utilities
- */
-export interface MinimalEdge {
-    srcId: string | number;
-    dstId: string | number;
-    data?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-/**
- * Minimal interface for graph-like objects
- * This allows the utilities to work with both real Graph instances and mock graphs in tests
- */
-export interface GraphLike {
-    getDataManager: () => {
-        nodes: Map<string | number, unknown>;
-        edges: Map<string | number, MinimalEdge>;
-    };
-}
-/**
- * Options for building adjacency lists
- */
-interface AdjacencyOptions {
-    /** Whether to treat the graph as directed (default: false for undirected) */
-    directed?: boolean;
-    /** Weight attribute name on edges (default: "value") */
-    weightAttribute?: string;
-}
-/**
- * Build an unweighted adjacency list from graph edges.
- *
- * Returns a Map where keys are node IDs (as strings) and values are Sets of neighbor node IDs.
- * For undirected graphs, both directions are added automatically.
- * @param graph - The graphty-element Graph instance
- * @param options - Configuration options
- * @returns Map of node ID to Set of neighbor IDs
- * @example
- * ```typescript
- * // Undirected graph
- * const adj = buildAdjacencyList(graph);
- * adj.get("A")?.has("B"); // true if A-B edge exists
- *
- * // Directed graph
- * const directedAdj = buildAdjacencyList(graph, { directed: true });
- * ```
- */
-export declare function buildAdjacencyList(graph: GraphLike, options?: AdjacencyOptions): Map<string, Set<string>>;
-/**
- * Build a weighted adjacency list from graph edges.
- *
- * Returns a Map where keys are node IDs (as strings) and values are Maps of neighbor ID to edge weight.
- * For undirected graphs, both directions are added automatically with the same weight.
- * @param graph - The graphty-element Graph instance
- * @param options - Configuration options
- * @returns Map of node ID to Map of neighbor ID to weight
- * @example
- * ```typescript
- * // Get weighted adjacency (weights from 'value' attribute)
- * const adj = buildWeightedAdjacencyList(graph);
- * const weight = adj.get("A")?.get("B"); // edge weight from A to B
- *
- * // Use custom weight attribute
- * const adj = buildWeightedAdjacencyList(graph, { weightAttribute: "weight" });
- * ```
- */
-export declare function buildWeightedAdjacencyList(graph: GraphLike, options?: AdjacencyOptions): Map<string, Map<string, number>>;
-export {};

package/dist/src/algorithms/utils/snapshotGraph.d.ts

@@ -4,6 +4,7 @@
  */
 import { Graph as AlgorithmGraph } from "@graphty/algorithms";
 import type { DataManager } from "../../managers/DataManager";
+import { type ScopedInput } from "../input/ScopedInput";
 /**
  * How an algorithm wants the reader's graph presented to `@graphty/algorithms`.
  *
@@ -39,9 +40,10 @@ export type AlgorithmGraphView = AlgorithmGraph;
  * than the part of it the scene has caught up with.
  * @param data - the element's data manager, which owns the one snapshot
  * @param mode - the shape this algorithm needs; see {@link AlgorithmGraphMode}
+ * @param input - what the run reads, from `Algorithm.input`; the whole graph when absent
  * @returns a freshly built Graph for `@graphty/algorithms`
  */
-export declare function toAlgorithmGraph(data: DataManager, mode: AlgorithmGraphMode): AlgorithmGraph;
+export declare function toAlgorithmGraph(data: DataManager, mode: AlgorithmGraphMode, input?: ScopedInput): AlgorithmGraph;
 /**
  * How many parallel edges an algorithm run over this graph merges before it can run.
  *

package/dist/src/catalog/algorithms.d.ts

@@ -74,6 +74,9 @@ export interface BuiltInAlgorithmDescriptor extends AlgorithmDescriptor {
  * shortest-path engines are one key with a `method` parameter, and the two component algorithms
  * are one key with a `strength` parameter. Each descriptor's `legacyKeys` names the 1.10 keys it
  * replaces and the parameters that reproduce them.
+ *
+ * `scopeInput` is read from the classes rather than written here, so it cannot disagree with what
+ * a run computes over: a folded key computes over its scope only when every class behind it does.
  */
 export declare const BUILT_IN_ALGORITHMS: readonly BuiltInAlgorithmDescriptor[];
 /**

package/dist/src/catalog/layouts.d.ts

@@ -47,6 +47,8 @@ export interface LayoutImplementation {
      * catalogue cannot claim a weight channel an engine does not have.
      */
     honoursWeights: boolean;
+    /** Whether this engine accepts a scope, read off the engine class's own `static scoped`. */
+    scoped: boolean;
     /**
      * What has to be true before this engine can run at all, in the same shape an algorithm
      * declares it.

package/dist/src/catalog/sets/canonical.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file The canonical form of a set definition: one spelling for every definition that means the
+ * same thing.
+ *
+ * Every door, the loader and the revision hash go through this one function, so two definitions
+ * that hold the same members compare equal as JSON and hash to the same revision. The rules
+ * (design/sets/sets-design.md section 12.1):
+ *
+ * - Object keys sorted by UTF-16 code unit. Absent optional fields omitted, never `null`, except
+ *   a path step's `null`, which means "every edge between that pair". An empty edge list and a
+ *   path's `directed: false` are the defaults, so they are omitted too.
+ * - Member arrays (a fixed set's nodes and edges, a path step's edge group) sorted by one
+ *   comparator and de-duplicated: numbers before strings, numbers by value, strings by code unit.
+ *   The number `1` and the string `"1"` are different ids. `-0` is stored as `0`.
+ * - Path nodes and steps keep their order; `all` and `any` keep their operand order, because the
+ *   user wrote it.
+ * - A rule whose tree is one expression leaf becomes the bare query; a fixed `clipped` becomes
+ *   `listed`, which holds the same members.
+ * - Unknown kinds are left exactly as they are. A known node carrying a field this element does
+ *   not know keeps that field's value; a fixed set carrying one also keeps its member order, so a
+ *   newer element's parallel array (such as `weights`) is never left misaligned.
+ *
+ * Pure and Node-safe: nothing here reaches a graph, a renderer or the DOM.
+ */
+import type { EdgeMember, NodeId, SetDefinition } from "../types";
+/** The fields each definition kind defines; anything else is unknown to this element. */
+export declare const DEFINITION_FIELDS: {
+    readonly fixed: readonly ["kind", "nodes", "edges", "reading"];
+    readonly rule: readonly ["kind", "where", "reading"];
+    readonly path: readonly ["kind", "nodes", "edges", "directed"];
+};
+/** The fields an edge member defines, in its sort order after the endpoints. */
+export declare const EDGE_MEMBER_FIELDS: readonly ["source", "target", "id", "key", "ordinal", "among"];
+/**
+ * The member comparator: numbers before strings, numbers by value, strings by UTF-16 code unit.
+ * @param a - One id.
+ * @param b - The other.
+ * @returns Negative, zero or positive.
+ */
+export declare function compareIds(a: unknown, b: unknown): number;
+/**
+ * Members the element built itself from a snapshot (known fields only, integers, no `-0`) in the
+ * canonical order, de-duplicated, without the per-member key sort a caller's members need.
+ * Internal: for the materialising doors.
+ * @param members - Element-built members.
+ * @returns A fresh sorted array.
+ */
+export declare function sortElementEdgeMembers(members: readonly EdgeMember[]): EdgeMember[];
+/**
+ * Node ids in the canonical order, de-duplicated. Internal: for the materialising doors.
+ * @param ids - Element-built ids.
+ * @returns A fresh sorted array.
+ */
+export declare function sortElementNodeIds(ids: readonly NodeId[]): NodeId[];
+/**
+ * The run id a result item names: the id itself, or the id of a `Run` or `RunResult` handle a
+ * door was passed, so every stored item holds a plain id.
+ * @param run - The item's `result`.
+ * @returns The id, or the value as it was when it is neither.
+ */
+export declare function runIdOfRef(run: unknown): unknown;
+/**
+ * The canonical form of a set definition. Never modifies its input. Accepts a definition holding
+ * content this element does not know and keeps that content exactly.
+ * @param definition - The definition, already validated or loaded.
+ * @returns A fresh canonical definition.
+ */
+export declare function canonicalSetDefinition(definition: SetDefinition): SetDefinition;

package/dist/src/catalog/sets/hash.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @file Member hashes, the member sum and the `r1:` revision of a set definition.
+ *
+ * The rules are persisted contract (design/sets/sets-design.md section 12.2); a change to any of
+ * them bumps the revision prefix to `r2`:
+ *
+ * - `H` is two independent 32-bit FNV-1a lanes. Lane A starts at 0x811c9dc5 and multiplies by
+ *   0x01000193, lane B starts at 0x1b873593 and multiplies by 0x85ebca6b. Each step is
+ *   `lane = Math.imul(lane ^ unit, multiplier) >>> 0` on both lanes, and each lane ends with the
+ *   MurmurHash3 32-bit finaliser, so member hashes can be summed without inheriting FNV's
+ *   near-linear structure.
+ * - A string part is the unit 0x24 then each UTF-16 code unit as one step. A numeric part is the
+ *   unit 0x23 then the eight little-endian bytes of its float64 value, `-0` fed as `+0`. No string
+ *   is ever built for a number, so `1` and `"1"` differ and `1e21` is never "1e+21".
+ * - An edge member combines its endpoint hashes (a lane-wise sum when undirected, so the order of
+ *   the ends cannot matter; an ordered hash when the graph was directed at ingest) with the hash of
+ *   its one discriminator.
+ * - The member sum is the lane-wise sum of member hashes mod 2^32, order-free, so a member delta
+ *   updates it by one add or subtract per member.
+ *
+ * Pure and Node-safe.
+ */
+import type { EdgeMember, NodeId, SetDefinition } from "../types";
+/** A 64-bit hash as its two 32-bit lanes, each an unsigned integer. */
+export interface LanePair {
+    readonly a: number;
+    readonly b: number;
+}
+/** The sum of no members. */
+export declare const EMPTY_SUM: LanePair;
+/**
+ * Invocation counts the complexity tests read: member hashes computed, and member hashes added to
+ * a sum. Internal; never reset by this module.
+ */
+export declare const hashCounters: {
+    memberHashes: number;
+    sums: number;
+};
+/**
+ * A node member's hash.
+ * @param id - The node id.
+ * @returns `H` of its one part.
+ */
+export declare function hashNodeId(id: NodeId): LanePair;
+/**
+ * An edge member's hash. Undirected, the endpoints combine by a lane-wise sum, so swapping them
+ * changes nothing; directed at ingest, they are hashed in order.
+ * @param member - The member, with exactly one discriminator.
+ * @param directed - Whether the graph was declared directed at ingest.
+ * @returns The member hash.
+ */
+export declare function hashEdgeMember(member: EdgeMember, directed: boolean): LanePair;
+/**
+ * An edge member's hash from its endpoints' node hashes, equal to {@link hashEdgeMember} of the
+ * member those ends and that discriminator spell. The completion pass calls it with hashes it
+ * has already computed, so no member object is built and no endpoint id is hashed twice.
+ * @param source - `hashNodeId` of the source (or lower end)
+ * @param target - `hashNodeId` of the target (or upper end)
+ * @param directed - Whether the graph was declared directed at ingest.
+ * @param id - The file or minted id; when undefined, `ordinal` and `among` discriminate.
+ * @param ordinal - The edge's position among its pair's edges.
+ * @param among - Its pair's edge count.
+ * @returns The member hash.
+ */
+export declare function hashEdgeEnds(source: LanePair, target: LanePair, directed: boolean, id: string | number | undefined, ordinal: number, among: number): LanePair;
+/**
+ * Add a member hash to a sum.
+ * @param sum - The sum.
+ * @param hash - The member hash.
+ * @returns The new sum, each lane mod 2^32.
+ */
+export declare function addToSum(sum: LanePair, hash: LanePair): LanePair;
+/**
+ * Take a member hash out of a sum.
+ * @param sum - The sum.
+ * @param hash - A member hash the sum holds.
+ * @returns The new sum, each lane mod 2^32.
+ */
+export declare function subtractFromSum(sum: LanePair, hash: LanePair): LanePair;
+/**
+ * The order-free sum of member hashes.
+ * @param hashes - The member hashes.
+ * @returns Their lane-wise sum.
+ */
+export declare function memberSum(hashes: Iterable<LanePair>): LanePair;
+/**
+ * A hash as 16 lower-case hex digits, lane A first.
+ * @param hash - The hash.
+ * @returns The hex text.
+ */
+export declare function hashHex(hash: LanePair): string;
+/** A member array as the revision sees it: how many members, and the sum of their hashes. */
+export interface MemberSummary {
+    readonly count: number;
+    readonly sum: LanePair;
+}
+/**
+ * The revision of a fixed definition that carries no field this element does not know, from its
+ * member summaries alone, so a member delta can re-derive it without touching the other members.
+ * Equal to {@link revisionOf} of the same definition.
+ * @param reading - The stored reading, `induced` or `listed`.
+ * @param nodes - The node members' summary.
+ * @param edges - The edge members' summary; absent or empty when no edge is listed.
+ * @returns `r1:` and 16 hex digits.
+ */
+export declare function fixedRevision(reading: string, nodes: MemberSummary, edges?: MemberSummary): string;
+/**
+ * The revision of a definition: `r1:` and `H` of its canonical JSON as one string part, in which a fixed set's
+ * member arrays are replaced by `{"count":k,"sum":"<hex>"}`. A fixed set's edge members are hashed
+ * in the order they are written (the directed rule): the revision digests the definition, and
+ * the definition's JSON tells `a -> b` from `b -> a`. Unknown kinds hash as their JSON.
+ * @param definition - A validated or loaded definition.
+ * @returns `r1:` and 16 hex digits.
+ */
+export declare function revisionOf(definition: SetDefinition): string;
+/**
+ * The `d1:` membership digest (design section 6.4): `H` of six numeric parts, the node count, the
+ * node sum's lanes A and B, the edge count, the edge sum's lanes A and B, where each sum is the
+ * member sum of the resolved members' column hashes (`graphty.nodeHash`, `graphty.edgeHash`, the
+ * undirected rule while pairs are unordered). The counts keep a node half and an edge half apart
+ * even when their sums happen to agree. Comparable only within one session and store.
+ * @param nodes - The resolved nodes' count and member sum.
+ * @param edges - The resolved edges' count and member sum.
+ * @returns `d1:` and 16 hex digits.
+ */
+export declare function membershipDigestOf(nodes: MemberSummary, edges: MemberSummary): string;

package/dist/src/catalog/sets/parse.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @file The one validator for set definitions, in two modes.
+ *
+ * DOOR MODE (`parseSetDefinition`, published) refuses anything malformed, unknown or reserved
+ * with `E_BAD_COMMAND`, and returns the canonical definition. Every write door, and any caller
+ * that wants to check a definition before handing it over, uses it.
+ *
+ * LOAD MODE (`loadSetDefinition`, internal) is what reading stored state uses. It still refuses
+ * a malformed node of a kind this element knows, but an unknown kind, an unknown field or a
+ * reserved field is kept instead of refused, and the definition is flagged OPAQUE with the first
+ * such name. Ignoring it instead would be wrong in both directions: an older element that
+ * dropped a rule's `scope` or an item key's `op` would resolve silently wrong members, and would
+ * lose the field on the next save. The whole definition is the opaque unit
+ * (design/sets/sets-design.md section 12.5): it round-trips value-identical, resolves to nothing
+ * and reads `unresolvable`.
+ *
+ * One walker serves both modes, so the two can never disagree about what a known node is.
+ *
+ * Reserved fields -- names a later release will give a meaning, refused at the doors until then:
+ * `weights` on a fixed set, `scope` on a rule, `key` and `dataSource` on an edge member, `graph` on
+ * `{ set }`, `percentile`, `z` and `population` on a threshold, `op` on an item key. Reserved kinds:
+ * the scope keyword `"search"`, and the item key forms `{ smallestNode }`, `{ edges }`, `{ binds }`.
+ *
+ * `parseScope` is the same validator for a `Scope`, which may carry a definition inline.
+ *
+ * Pure and Node-safe: nothing here reaches a graph, a renderer or the DOM.
+ */
+import { GraphtyError } from "../../errors/GraphtyError";
+import type { EdgeReading, Scope, SetDefinition } from "../types";
+/** Every edge reading this element knows. */
+export declare const EDGE_READINGS: readonly EdgeReading[];
+/**
+ * How a scope reads, as far as the scope itself says: `"visible"` is clipped, an inline definition
+ * reads as it is stored (a path `listed`), and every other form is node-induced. A `{ set }` names
+ * a set this module cannot see: `referent` answers for it, and without one it reads induced.
+ * @param scope - A validated scope.
+ * @param referent - The reading of the set an id names, when the caller can look it up.
+ * @returns The reading.
+ */
+export declare function readingOfScope(scope: unknown, referent?: (id: string) => string | undefined): string;
+/**
+ * Whether a rule tree holds a leaf that speaks about edges: an `edges` leaf, a `member` leaf whose
+ * set is read `listed` or `clipped`, or an `item` or `threshold` leaf over a field edges carry.
+ * @param node - A validated tree node, or a query.
+ * @param referent - The reading of the set an id names, when the caller can look it up.
+ * @param fieldKinds - Which halves carry a value path (`results.<run>.<field>` or `data.<field>`),
+ * when the caller can look it up; without it an `item` or `threshold` leaf is not known to.
+ * @returns True when some leaf speaks the edge half.
+ */
+export declare function speaksEdges(node: unknown, referent?: (id: string) => string | undefined, fieldKinds?: (path: string) => readonly string[]): boolean;
+/**
+ * The refusal of a rule read `induced` that holds an edge-speaking leaf.
+ * @returns The error to throw.
+ */
+export declare function inducedEdgeLeaf(): GraphtyError;
+/**
+ * Check a set definition and return its canonical form.
+ *
+ * Door mode: anything malformed, and any kind or field this element does not know or has only
+ * reserved, is refused. Edge members must be in stable form; a write door that accepts a session
+ * edge id converts it before calling this.
+ * @param value - The candidate definition, from any source.
+ * @returns The canonical definition.
+ * @throws A `GraphtyError` with code `E_BAD_COMMAND`. `details.reason` is `"induced-edge-leaf"`
+ * for a rule read `induced` that holds an edge leaf; a reserved field is named in `details.field`.
+ */
+export declare function parseSetDefinition(value: unknown): SetDefinition;
+/**
+ * Check a stored set definition, keeping what this element does not know.
+ *
+ * Internal: the loader's mode. A malformed node of a known kind is still refused.
+ * @param value - The stored definition.
+ * @returns The canonical definition, and when it holds anything unknown or reserved, the first
+ * such kind or field (`<node>.<field>` for a field).
+ * @throws A `GraphtyError` with code `E_BAD_COMMAND` for a malformed known node.
+ */
+export declare function loadSetDefinition(value: unknown): {
+    definition: SetDefinition;
+    opaque?: {
+        first: string;
+    };
+};
+/**
+ * Check a rule tree in door mode, as the visibility filter's door does for the leaves it shares
+ * with rule sets. Internal.
+ * @param value - The candidate tree.
+ * @throws A `GraphtyError` with code `E_BAD_COMMAND`.
+ */
+export declare function assertRuleTree(value: unknown): void;
+/**
+ * Check a scope and return its canonical form: an inline definition canonical, every other form
+ * as given.
+ *
+ * Door mode: anything malformed, unknown or reserved (the keyword `"search"`) is refused. Edge
+ * members inside `{ define }` must be in stable form; a write door that accepts session edge ids
+ * converts them first.
+ * @param value - The candidate scope, from any source.
+ * @returns The scope.
+ * @throws A `GraphtyError` with code `E_BAD_COMMAND`, with `details.reason` as
+ * {@link parseSetDefinition} gives it for an inline definition.
+ */
+export declare function parseScope(value: unknown): Scope;
+/**
+ * A write door's value with every edge reference inside an inline definition passed through
+ * `stable` (a session edge id becomes its stable member; an object member is handed over as
+ * given, for the door to canonicalise), at any depth: a scope's `{ define }`, a fixed or path definition's edges, a
+ * rule's tree, the `member` leaves of a rule tree and a `{ match: "member" }` selector. Everything
+ * else is returned as given for the validator to judge, and a value `stable` changes nothing in is
+ * returned unchanged (the same object).
+ * @param value - A scope, a set definition, a rule tree or a selector, as given.
+ * @param stable - The stable member of a session edge id or an object member; throws for an edge
+ * the graph lacks.
+ * @returns The value, stable.
+ */
+export declare function stabiliseEdgeRefs<T>(value: T, stable: (ref: string) => unknown): T;