Skip to content

feat!: return indexed subgraph result with adjacency maps#83

Merged
pdlug merged 1 commit into
mainfrom
feat/indexed-subgraph-result
Apr 7, 2026
Merged

feat!: return indexed subgraph result with adjacency maps#83
pdlug merged 1 commit into
mainfrom
feat/indexed-subgraph-result

Conversation

@pdlug
Copy link
Copy Markdown
Contributor

@pdlug pdlug commented Apr 7, 2026

  • BREAKING: store.subgraph() now returns { root, nodes: Map, adjacency, reverseAdjacency } instead of { nodes: Node[], edges: Edge[] }
  • Eliminates the adjacency-index-rebuilding boilerplate every consumer writes before traversing a subgraph result
  • Forward and reverse adjacency maps provide O(1) edge lookup by nodeId → edgeKind
  • root provides direct access to the traversal starting point

Migration

// Before
const nodeById = new Map(sg.nodes.map(n => [String(n.id), n]));
const items = sg.edges.filter(e => e.kind === "has_item" && e.fromId === orderId);

// After
const item = sg.nodes.get(itemId);
const itemEdges = sg.adjacency.get(orderId)?.get("has_item") ?? [];
const parentEdges = sg.reverseAdjacency.get(itemId)?.get("has_item") ?? [];

Closes #82

Replace the flat `{ nodes[], edges[] }` return type of `store.subgraph()`
with an indexed structure for immediate traversal:

  root: Node | undefined
  nodes: ReadonlyMap<string, Node>
  adjacency: ReadonlyMap<string, ReadonlyMap<EK, Edge[]>>
  reverseAdjacency: ReadonlyMap<string, ReadonlyMap<EK, Edge[]>>

Every consumer of the old API rebuilt adjacency indexes before doing
anything useful. The new shape eliminates that boilerplate — nodes are
keyed by ID for O(1) lookup, and edges are organized into forward/reverse
adjacency maps keyed by nodeId → edgeKind.

- Export new SubgraphNodeResult and SubgraphEdgeResult type aliases
- Add insertAdjacencyEntry helper for two-level Map construction
- Add collectAllEdges test utility to test-utils.ts
- Add type-level tests for root narrowing and adjacency map access
- Update benchmarks package to new result shape
- Update schemas-stores.md and types.md documentation

Closes #82
@pdlug pdlug force-pushed the feat/indexed-subgraph-result branch from 46dad5c to 73c4e12 Compare April 7, 2026 20:43
@pdlug pdlug merged commit 206f464 into main Apr 7, 2026
10 checks passed
@pdlug pdlug deleted the feat/indexed-subgraph-result branch April 7, 2026 20:47
@github-actions github-actions Bot mentioned this pull request Apr 7, 2026
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.

subgraph() should return indexed adjacency maps, not flat arrays

1 participant