Skip to content

feat: add store.subgraph() for typed neighborhood extraction#33

Merged
pdlug merged 2 commits into
mainfrom
feat/store-subgraph
Mar 9, 2026
Merged

feat: add store.subgraph() for typed neighborhood extraction#33
pdlug merged 2 commits into
mainfrom
feat/store-subgraph

Conversation

@pdlug
Copy link
Copy Markdown
Contributor

@pdlug pdlug commented Mar 9, 2026

Summary

  • Adds store.subgraph(rootId, options) for BFS subgraph extraction via recursive CTE
  • Supports multi-edge-kind traversal, bidirectional edges, includeKinds filtering, excludeRoot, cycle detection (prevent/allow), and soft-delete exclusion
  • Returns fully typed discriminated union results (SubsetNode<G, NK>[], SubsetEdge<G, EK>[]) with compile-time narrowing via includeKinds
  • Dialect-aware SQL: SQLite uses CROSS JOIN + INSTR path for worktable ordering; PostgreSQL uses standard JOIN ON + array-based cycle detection

What shipped

Type utilities (zero runtime cost):

  • AnyNode<G> — discriminated union of all runtime node instances
  • AnyEdge<G> — discriminated union of all runtime edge instances
  • SubsetNode<G, K> — narrowed to selected node kinds
  • SubsetEdge<G, K> — narrowed to selected edge kinds

store.subgraph(rootId, options):

  • BFS traversal via recursive CTE following a set of edge kinds
  • maxDepth (default 10, capped at MAX_RECURSIVE_DEPTH)
  • includeKinds — filter result nodes while still traversing through excluded kinds
  • excludeRoot — omit the root node from results
  • direction: "out" | "both" — unidirectional or bidirectional traversal
  • cyclePolicy: "prevent" | "allow" — dialect-aware cycle detection
  • Handles SQLite worktable join ordering (CROSS JOIN pattern)
  • 2 parallel SQL queries (nodes + edges), each self-contained with the CTE
  • Edges filtered to those where both endpoints are in the final node set

Closes #31

@pdlug pdlug force-pushed the feat/store-subgraph branch 2 times, most recently from 1c21f16 to d007daa Compare March 9, 2026 19:39
Implements BFS traversal from a root node via recursive CTE, returning
all reachable nodes and connecting edges as a typed discriminated union.
Supports multi-edge-kind traversal, bidirectional edges, includeKinds
filtering, excludeRoot, cycle detection, and soft-delete exclusion.
@pdlug pdlug force-pushed the feat/store-subgraph branch from d007daa to 1b10d83 Compare March 9, 2026 19:41
@pdlug pdlug merged commit da14806 into main Mar 9, 2026
10 checks passed
@pdlug pdlug deleted the feat/store-subgraph branch March 9, 2026 19:43
@github-actions github-actions Bot mentioned this pull request Mar 9, 2026
pdlug added a commit that referenced this pull request Mar 9, 2026
…ge, SubsetNode, SubsetEdge)

Adds compile-time and runtime tests verifying the discriminated union
type utilities introduced in #33. Compile-time tests assert type
assignability and subset rejection via @ts-expect-error. Runtime tests
verify kind-based narrowing exposes correct schema-specific properties.
pdlug added a commit that referenced this pull request Mar 9, 2026
…ge, SubsetNode, SubsetEdge) (#35)

Adds compile-time and runtime tests verifying the discriminated union
type utilities introduced in #33. Compile-time tests assert type
assignability and subset rejection via @ts-expect-error. Runtime tests
verify kind-based narrowing exposes correct schema-specific properties.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: store.subgraph() — typed subgraph extraction from a root node

1 participant