Every edge carries provenance: which extractor produced it, what evidence backs it, how confident that evidence is, and optionally where in the source it came from. That is the difference between a graph you can query and a graph you can defend.

npm install weavatrix-graph
# or
bun add weavatrix-graph

const { Graph } = require('weavatrix-graph')

const graph = new Graph({
  nodes: [
    { id: 'api', label: 'API', kind: 'service' },
    { id: 'db', label: 'Database', kind: 'table' },
  ],
  edges: [{
    source: 'api',
    target: 'db',
    kind: 'reads',
    provenance: { extractor: 'architecture', evidence: 'parsed', confidence: 'exact' },
  }],
})

graph.shortestPath('api', 'db')          // ['api', 'db']
graph.hasCycle()                          // false
graph.pageRank({ damping: 0.85 })         // [{ id, score }, …]
graph.outgoing('api')[0].provenance        // why that edge exists

Input

`GraphNode`

Field	Type	Notes
`id`	`string`	Stable identity. Must be unique.
`label`	`string`	Human-readable name.
`kind`	`string`	Free-form node category.
`language`	`string?`
`span`	`SourceSpan?`	`{ file, start: { line, column }, end: { line, column } }`
`attributes`	`Record<string, AttributeValue>?`	Nested JSON values are allowed.

`GraphEdge`

Field	Type	Notes
`source`, `target`	`string`	Must reference declared node ids.
`kind`	`string`	Relation type, such as `calls`, `reads`, `implements`.
`provenance`	`Provenance`	Required. `{ extractor, evidence, confidence, span?, detail? }` where `confidence` is `'exact' \| 'high' \| 'medium' \| 'low'`.
`attributes`	`Record<string, AttributeValue>?`

Requiring provenance on construction is deliberate: an edge nobody can justify never enters the graph.

API

`new Graph(input)`

Validates the whole input and throws on a duplicate node id, a dangling edge endpoint, or a malformed provenance record.

Member	Returns	Notes
`nodeCount`	`number`
`edgeCount`	`number`
`canonical()`	`GraphInput`	Deterministic serialization. Two graphs with equal content produce byte-identical output, which is what makes a graph diffable and cacheable.
`node(id)`	`GraphNode \| undefined`
`outgoing(id)`	`GraphEdge[]`	Edges leaving `id`, with provenance intact.
`incoming(id)`	`GraphEdge[]`	Edges arriving at `id`.
`bfs(start)`	`string[]`	Materialized breadth-first visit order.
`shortestPath(source, target)`	`string[] \| undefined`	Node ids inclusive of both ends; `undefined` when unreachable.
`stronglyConnectedComponents()`	`string[][]`	Each component in deterministic order.
`topologicalSort()`	`string[] \| undefined`	`undefined` when the graph has a cycle.
`hasCycle()`	`boolean`
`pageRank(options?)`	`{ id, score }[]`	`{ damping = 0.85, iterations = 20 }`. Deterministic for a given graph and settings.
`toDot()`	`string`	Deterministic Graphviz DOT.

Traversal methods throw InvalidArg for an unknown node id, rather than silently returning nothing.

Determinism

Component order, visit order, DOT output, and canonical serialization are all derived from content, never from insertion order or thread scheduling. The same input produces the same bytes on every platform and every run.

Errors

`code`	Cause
`InvalidArg`	Malformed input JSON, duplicate node id, edge endpoint that references no node, unknown node id passed to a traversal, invalid PageRank settings.

What ships


Runtimes	Node.js 18+ (Node-API 8), Bun 1.4+
Platforms	Windows x64/arm64, macOS x64/arm64, glibc Linux x64/arm64
Install script	none
Network at install	none
Runtime dependencies	none
Platform packages	none — all six bindings are in this one tarball

The Node-API 8 ABI keeps the addon independent of any single Node major version.

Measured

benchmark/RESULTS.md is generated from the weavatrix-benchmarks harness, which forces both sides to materialize the identical BFS visit order before either is timed. The competitor is graphology, the standard JavaScript graph library.

Medians of three independent runs over 50,000 nodes and 149,991 edges:

Contract	Node 24	Bun 1.3
Materialized directed BFS node ids	2.98x (2.91–3.14)	2.98x (2.82–3.20)

graphology stores a plain topology; the Weavatrix graph also retains typed provenance on every edge, so it is carrying more and still traversing faster. On a ten-node graph both sides sit in timer noise, and this project makes no small-graph claim.

Graph owns its repository, package, release evidence, and MIT license, and can be used entirely on its own.

Repository: Weavatrix/weavatrix-graph · Rust crate: crates.io/crates/weavatrix-graph · License: MIT