@nicia-ai/typegraph 0.18.0 → 0.20.0

package/dist/{store-B_JzzHwb.d.cts → store-DRRvALu8.d.cts}

@@ -2,7 +2,7 @@ import { S as SqlSchema, G as GraphBackend, T as TransactionBackend, E as EdgeRo
 import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Bj1UEnhE.cjs';
 import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.cjs';
 import { z } from 'zod';
-import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-Bh2NDeaK.cjs';
+import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection$1, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-Bh2NDeaK.cjs';
 import { SQL } from 'drizzle-orm';
 
 /**
@@ -273,7 +273,7 @@ type BatchResults<Queries extends readonly BatchableQuery<unknown>[]> = {
  * // ValidEdgeTargets<G, "worksAt", "out"> = "Company" | "Organization"
  * // ValidEdgeTargets<G, "worksAt", "in"> = "Person"
  */
-type ValidEdgeTargets<G extends GraphDef, EK extends keyof G["edges"] & string, Dir extends TraversalDirection> = G["edges"][EK] extends EdgeRegistration ? Dir extends "out" ? G["edges"][EK]["to"][number]["kind"] : G["edges"][EK]["from"][number]["kind"] : never;
+type ValidEdgeTargets<G extends GraphDef, EK extends keyof G["edges"] & string, Dir extends TraversalDirection$1> = G["edges"][EK] extends EdgeRegistration ? Dir extends "out" ? G["edges"][EK]["to"][number]["kind"] : G["edges"][EK]["from"][number]["kind"] : never;
 /**
  * A node alias with its associated type.
  */
@@ -1485,6 +1485,13 @@ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends Nod
     direction?: "out" | "both";
     /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
     cyclePolicy?: RecursiveCyclePolicy;
+    /**
+     * Temporal mode applied to both nodes and edges along the traversal and in
+     * the hydrated result. Defaults to `graph.defaults.temporalMode`.
+     */
+    temporalMode?: TemporalMode;
+    /** ISO-8601 timestamp used when `temporalMode === "asOf"`. */
+    asOf?: string;
     /**
      * Optional field-level projection per node/edge kind.
      *
@@ -1497,13 +1504,26 @@ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends Nod
      */
     project?: P;
 }>;
+/**
+ * Union of all node result types in a subgraph, respecting projection.
+ */
+type SubgraphNodeResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, P = undefined> = {
+    [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
+}[NK];
+/**
+ * Union of all edge result types in a subgraph, respecting projection.
+ */
+type SubgraphEdgeResult<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>, P = undefined> = {
+    [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
+}[EK];
 type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
-    nodes: readonly {
-        [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
-    }[NK][];
-    edges: readonly {
-        [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
-    }[EK][];
+    /** The root node, or undefined if the root was not found or excluded. */
+    root: SubgraphNodeResult<G, NK, P> | undefined;
+    nodes: ReadonlyMap<string, SubgraphNodeResult<G, NK, P>>;
+    /** Forward adjacency: fromId → edgeKind → edges to targets. */
+    adjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
+    /** Reverse adjacency: toId → edgeKind → edges from sources. */
+    reverseAdjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
 }>;
 
 /**
@@ -1853,7 +1873,7 @@ interface VariableLengthState {
  * Type parameters track the edge kind and direction to constrain
  * which node kinds are valid targets in the `to()` method.
  */
-declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, EK extends keyof G["edges"] & string = keyof G["edges"] & string, EA extends string = string, Dir extends TraversalDirection = "out", Optional extends boolean = false, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = {}> {
+declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, EK extends keyof G["edges"] & string = keyof G["edges"] & string, EA extends string = string, Dir extends TraversalDirection$1 = "out", Optional extends boolean = false, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = {}> {
     #private;
     constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, inverseEdgeKinds?: readonly string[], optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
     /**
@@ -2060,6 +2080,198 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
     pipe<OutAliases extends AliasMap, OutEdgeAliases extends EdgeAliasMap = EdgeAliases, OutRecAliases extends RecursiveAliasMap = RecursiveAliases>(fragment: (builder: QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>) => QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>): QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>;
 }
 
+/**
+ * Shared types for Tier 1 graph algorithms.
+ *
+ * Algorithms operate over one or more edge kinds and may traverse edges
+ * in the forward direction ("out"), reverse ("in"), or undirected ("both").
+ */
+
+/**
+ * Direction of edge traversal.
+ *
+ * - `"out"` — follow edges from source to target (default)
+ * - `"in"` — follow edges from target back to source
+ * - `"both"` — undirected traversal over either endpoint
+ */
+type TraversalDirection = "out" | "in" | "both";
+/**
+ * Cycle-handling strategy during recursive traversal.
+ *
+ * - `"prevent"` — skip any node already on the current path (default).
+ *   Guarantees termination even in cyclic graphs.
+ * - `"allow"` — permit revisiting nodes. Only safe with a bounded `maxHops`.
+ *
+ * Aliased to `RecursiveCyclePolicy` so algorithms and query-builder traversals
+ * share a single canonical union.
+ */
+type AlgorithmCyclePolicy = RecursiveCyclePolicy;
+/**
+ * Temporal filter options shared by every algorithm.
+ *
+ * Algorithms honor the same temporal model as the rest of the store: both
+ * nodes and edges are filtered according to the resolved mode. `asOf` is
+ * only consulted when the resolved mode is `"asOf"`. If neither option is
+ * supplied, the algorithm falls back to `graph.defaults.temporalMode`.
+ */
+type TemporalAlgorithmOptions = Readonly<{
+    /** Temporal mode. Defaults to the graph's configured default. */
+    temporalMode?: TemporalMode;
+    /**
+     * ISO-8601 timestamp used when `temporalMode` is `"asOf"`. Required in that
+     * mode; ignored in all others.
+     */
+    asOf?: string;
+}>;
+/**
+ * Base options for traversal-style algorithms.
+ */
+type BaseTraversalOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /** Edge kinds to follow. At least one kind is required. */
+    edges: readonly EdgeKinds<G>[];
+    /**
+     * Maximum number of hops to traverse. Defaults to 10.
+     * Must be between 1 and 1000.
+     */
+    maxHops?: number;
+    /** Direction of traversal (default: `"out"`). */
+    direction?: TraversalDirection;
+    /** Cycle policy (default: `"prevent"`). */
+    cyclePolicy?: AlgorithmCyclePolicy;
+}>;
+/**
+ * A node reached during traversal, annotated with the shortest depth at which
+ * it was first discovered.
+ */
+type ReachableNode = Readonly<{
+    id: string;
+    kind: string;
+    /** Number of edges traversed from the source. 0 for the source itself. */
+    depth: number;
+}>;
+/**
+ * A node along a shortest path. Endpoints are included.
+ */
+type PathNode = Readonly<{
+    id: string;
+    kind: string;
+}>;
+/**
+ * Result of `shortestPath`: the ordered node sequence and its length in hops.
+ */
+type ShortestPathResult = Readonly<{
+    /** Ordered nodes from source to target (inclusive). */
+    nodes: readonly PathNode[];
+    /** Number of edges traversed. Equals `nodes.length - 1`. */
+    depth: number;
+}>;
+/**
+ * Options for `shortestPath` and `canReach`. Reuses the base traversal
+ * options; cycle policy defaults to `"prevent"` since both algorithms only
+ * care about the first time a target is reached.
+ */
+type ShortestPathOptions<G extends GraphDef> = BaseTraversalOptions<G>;
+/**
+ * Options for `reachable`.
+ *
+ * Returns every node reachable from the source within `maxHops`, each
+ * annotated with its minimum discovered depth. `depth: 0` refers to the
+ * source itself and is included unless `excludeSource` is `true`.
+ */
+type ReachableOptions<G extends GraphDef> = BaseTraversalOptions<G> & Readonly<{
+    /** Exclude the source node from the result set (default: `false`). */
+    excludeSource?: boolean;
+}>;
+/**
+ * Options for `neighbors`.
+ *
+ * Like `reachable`, but the parameter is named `depth` for readability —
+ * "2-hop neighbors" reads more naturally than "reachable with maxHops=2".
+ * The source is always excluded.
+ */
+type NeighborsOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /** Edge kinds to follow. At least one kind is required. */
+    edges: readonly EdgeKinds<G>[];
+    /** Maximum neighborhood depth (default: 1). Must be between 1 and 1000. */
+    depth?: number;
+    /** Direction of traversal (default: `"out"`). */
+    direction?: TraversalDirection;
+    /** Cycle policy (default: `"prevent"`). */
+    cyclePolicy?: AlgorithmCyclePolicy;
+}>;
+/**
+ * Options for `degree`.
+ *
+ * Counts active edges incident to a node. With `direction: "both"`, an edge
+ * that happens to be a self-loop (from === to) is counted once, not twice.
+ */
+type DegreeOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /**
+     * Edge kinds to count. If omitted, counts across all edge kinds in the
+     * graph.
+     */
+    edges?: readonly EdgeKinds<G>[];
+    /** Direction (default: `"both"`). */
+    direction?: TraversalDirection;
+}>;
+
+/**
+ * Raw node id or any object with an `id: string` field. Covers `Node`,
+ * `NodeRef`, and the lightweight `ReachableNode` / `PathNode` shapes
+ * returned by the algorithms themselves.
+ *
+ * Deliberately kind-agnostic: graph algorithms don't constrain the source
+ * node's kind — you can start a traversal from any node reachable via the
+ * given edge kinds. `NodeRef<N>` exists for the edge-endpoint case where
+ * kind *is* load-bearing; using it here would paint a constraint onto a
+ * contract that doesn't need one and would reject common patterns like
+ * passing `ReachableNode` / cache entries / `{ id }` records straight
+ * through.
+ */
+type NodeIdentifier = string | Readonly<{
+    id: string;
+}>;
+type GraphAlgorithms<G extends GraphDef> = Readonly<{
+    /**
+     * Finds the shortest directed path from `from` to `to` using the given
+     * edge kinds. Returns `undefined` when no path exists within `maxHops`.
+     *
+     * @example
+     * ```typescript
+     * const path = await store.algorithms.shortestPath(alice, bob, {
+     *   edges: ["knows"],
+     *   maxHops: 6,
+     * });
+     * if (path) {
+     *   console.log(`${path.depth} hops via`, path.nodes.map((n) => n.id));
+     * }
+     * ```
+     */
+    shortestPath: (from: NodeIdentifier, to: NodeIdentifier, options: ShortestPathOptions<G>) => Promise<ShortestPathResult | undefined>;
+    /**
+     * Returns every node reachable from `from` within `maxHops` edges of the
+     * allowed kinds. Each node carries its minimum discovered depth.
+     */
+    reachable: (from: NodeIdentifier, options: ReachableOptions<G>) => Promise<readonly ReachableNode[]>;
+    /**
+     * Fast boolean check: is `to` reachable from `from` within `maxHops`
+     * edges? Short-circuits the underlying recursive CTE with `LIMIT 1`.
+     */
+    canReach: (from: NodeIdentifier, to: NodeIdentifier, options: BaseTraversalOptions<G>) => Promise<boolean>;
+    /**
+     * Returns the k-hop neighborhood of a node. The source is always
+     * excluded. `depth` defaults to 1, matching the common "immediate
+     * neighbors" interpretation.
+     */
+    neighbors: (node: NodeIdentifier, options: NeighborsOptions<G>) => Promise<readonly ReachableNode[]>;
+    /**
+     * Counts active edges incident to `node`.
+     *
+     * With `direction: "both"` (default), self-loops contribute once.
+     */
+    degree: (node: NodeIdentifier, options?: DegreeOptions<G>) => Promise<number>;
+}>;
+
 /**
  * Main Store implementation for TypeGraph.
  *
@@ -2148,6 +2360,27 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     get edges(): GraphEdgeCollections<G>;
+    /**
+     * Tier 1 graph algorithms: shortest path, reachability, neighborhoods, and
+     * degree centrality.
+     *
+     * Each call compiles to a single recursive-CTE query against the backend.
+     * The facade is built lazily on first access and cached for the lifetime
+     * of the store.
+     *
+     * @example
+     * ```typescript
+     * const path = await store.algorithms.shortestPath(alice, bob, {
+     *   edges: ["knows"],
+     * });
+     *
+     * const friends = await store.algorithms.neighbors(alice, {
+     *   edges: ["knows"],
+     *   depth: 2,
+     * });
+     * ```
+     */
+    get algorithms(): GraphAlgorithms<G>;
     /**
      * Returns the node collection for the given kind, or undefined if the kind
      * is not registered in this graph.
@@ -2216,22 +2449,26 @@ declare class Store<G extends GraphDef> {
      * Extracts a typed subgraph by traversing from a root node.
      *
      * Performs a BFS traversal from `rootId` following the specified edge kinds,
-     * then returns all reachable nodes and the edges connecting them.
+     * returning an indexed result with adjacency maps for immediate traversal.
      *
      * @example
      * ```typescript
-     * const result = await store.subgraph(run.id, {
+     * const sg = await store.subgraph(run.id, {
      *   edges: ["has_task", "runs_agent", "uses_skill"],
      *   maxDepth: 4,
-     *   includeKinds: ["Run", "Task", "Agent", "Skill"],
      * });
      *
-     * for (const node of result.nodes) {
-     *   switch (node.kind) {
-     *     case "Task": console.log(node.name); break;
-     *     case "Agent": console.log(node.model); break;
-     *   }
-     * }
+     * // Root node (the traversal starting point)
+     * console.log(sg.root?.kind);
+     *
+     * // Lookup by ID
+     * const task = sg.nodes.get(taskId);
+     *
+     * // Forward adjacency: edges of a kind from a node
+     * const taskEdges = sg.adjacency.get(run.id)?.get("has_task") ?? [];
+     *
+     * // Reverse adjacency: edges of a kind pointing to a node
+     * const parentEdges = sg.reverseAdjacency.get(taskId)?.get("has_task") ?? [];
      * ```
      */
     subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
@@ -2337,4 +2574,4 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type StoreProjection as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type DynamicEdgeCollection as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type PaginatedResult as J, type Predicate as K, PreparedQuery as L, type PropsAccessor as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type QueryHookContext as R, type QueryOptions as S, TraversalBuilder as T, type RecursiveTraversalOptions as U, type SelectContext as V, type SelectableEdge as W, type SelectableNode as X, Store as Y, type StoreHooks as Z, type StoreOptions as _, type AggregateResult as a, type StreamOptions as a0, type SubgraphOptions as a1, type SubgraphResult as a2, type SubsetEdge as a3, type SubsetNode as a4, type TransactionContext as a5, type TypedEdgeCollection as a6, UnionableQuery as a7, type UpdateEdgeInput as a8, type UpdateNodeInput as a9, createStore as aa, createStoreWithSchema as ab, defineSubgraphProject as ac, embedding as ad, exists as ae, fieldRef as af, getEmbeddingDimensions as ag, inSubquery as ah, isEmbeddingSchema as ai, isParameterRef as aj, notExists as ak, notInSubquery as al, param as am, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type DynamicNodeCollection as h, type Edge as i, type EdgeAccessor as j, type EdgeCollection as k, type EdgeFindByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsOptions as m, type EdgeGetOrCreateByEndpointsResult as n, type EmbeddingSchema as o, type EmbeddingValue as p, ExecutableAggregateQuery as q, ExecutableQuery as r, type GraphEdgeCollections as s, type GraphNodeCollections as t, type NodeAccessor as u, type NodeAlias as v, type NodeCollection as w, type NodeGetOrCreateByConstraintOptions as x, type NodeGetOrCreateByConstraintResult as y, type NodeRef as z };
+export { type ReachableNode as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, type DegreeOptions as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type NodeAlias as J, type NodeCollection as K, type NodeGetOrCreateByConstraintOptions as L, type NodeGetOrCreateByConstraintResult as M, type NeighborsOptions as N, type NodeIdentifier as O, type NodeRef as P, QueryBuilder as Q, type OperationHookContext as R, type PaginateOptions as S, TraversalBuilder as T, type PaginatedResult as U, type PathNode as V, type Predicate as W, PreparedQuery as X, type PropsAccessor as Y, type QueryHookContext as Z, type QueryOptions as _, type AggregateResult as a, type ReachableOptions as a0, type RecursiveTraversalOptions as a1, type SelectContext as a2, type SelectableEdge as a3, type SelectableNode as a4, type ShortestPathOptions as a5, type ShortestPathResult as a6, Store as a7, type StoreHooks as a8, type StoreOptions as a9, notInSubquery as aA, param as aB, type StoreProjection as aa, type StreamOptions as ab, type SubgraphEdgeResult as ac, type SubgraphNodeResult as ad, type SubgraphOptions as ae, type SubgraphResult as af, type SubsetEdge as ag, type SubsetNode as ah, type TemporalAlgorithmOptions as ai, type TransactionContext as aj, type TraversalDirection as ak, type TypedEdgeCollection as al, UnionableQuery as am, type UpdateEdgeInput as an, type UpdateNodeInput as ao, createStore as ap, createStoreWithSchema as aq, defineSubgraphProject as ar, embedding as as, exists as at, fieldRef as au, getEmbeddingDimensions as av, inSubquery as aw, isEmbeddingSchema as ax, isParameterRef as ay, notExists as az, type AlgorithmCyclePolicy as b, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DynamicEdgeCollection as j, type DynamicNodeCollection as k, type Edge as l, type EdgeAccessor as m, type EdgeCollection as n, type EdgeFindByEndpointsOptions as o, type EdgeGetOrCreateByEndpointsOptions as p, type EdgeGetOrCreateByEndpointsResult as q, type EmbeddingSchema as r, type EmbeddingValue as s, ExecutableAggregateQuery as t, ExecutableQuery as u, type GraphAlgorithms as v, type GraphEdgeCollections as w, type GraphNodeCollections as x, type Node as y, type NodeAccessor as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -155,17 +155,17 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24.12.0",
     "@types/pg": "^8.20.0",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.3",
     "better-sqlite3": "^12.8.0",
     "drizzle-orm": "^0.45.2",
-    "eslint": "^10.1.0",
+    "eslint": "^10.2.0",
     "fast-check": "^4.6.0",
     "pg": "^8.20.0",
-    "sqlite-vec": "^0.1.8",
+    "sqlite-vec": "^0.1.9",
     "tsd": "^0.33.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.2",
+    "vitest": "^4.1.3",
     "zod": "^4.3.6",
     "@typegraph/eslint-config": "0.1.0"
   },