# @dxos/graph

> Low-level graph API

Latest version **0.16.0** (published 2026-10-19) · FSL-1.1-Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dxos/graph
pnpm add @dxos/graph
yarn add @dxos/graph
bun add @dxos/graph
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.16.0 |
| Published | 2026-10-19 |
| First published | 2025-01-07 |
| Weekly downloads | 0 |
| License | FSL-1.1-Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 7 |
| Unpacked size | 688.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 532 |
| Author | DXOS.org |
| Maintainers | richburdon, marik_d, wittjosiah, dxos-bot, mykola-vrmchk |

## Links

- npm: https://www.npmjs.com/package/@dxos/graph
- Repository: https://github.com/dxos/dxos
- Homepage: https://dxos.org
- Issues: https://github.com/dxos/dxos/issues
- npm.io page: https://npm.io/package/@dxos/graph

## Dependencies (7)

- [@dxos/log](https://npm.io/package/@dxos/log.md) 0.16.0
- [@dxos/util](https://npm.io/package/@dxos/util.md) 0.16.0
- [@dxos/async](https://npm.io/package/@dxos/async.md) 0.16.0
- [@dxos/debug](https://npm.io/package/@dxos/debug.md) 0.16.0
- [@dxos/effect](https://npm.io/package/@dxos/effect.md) 0.16.0
- [@dxos/errors](https://npm.io/package/@dxos/errors.md) 0.16.0
- [@dxos/invariant](https://npm.io/package/@dxos/invariant.md) 0.16.0

## Recent versions

- 0.16.0 (latest) — 2026-10-19
- 0.17.0-next-6a61a88494afb051ad9f12d6eedd1479c54b0cea (next) — 2026-11-18
- 0.9.1-main.c7dcc2e112 (main) — 2026-06-19
- 0.7.5-labs.d199c0f (labs) — 2025-03-12
- 0.16.0-next-60712ab191a99ba90316cc4be753e9e11b17100a — 2026-10-19
- 0.16.0-next-b440559823fb87ed1a4590dab21ae924d4d76c3a — 2026-10-19
- 0.14.0 — 2026-10-10
- 0.13.0 — 2026-10-07
- 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 — 2026-08-27
- 0.12.0-next-2800d0376abcc62d5544afdd744b16b2b960434e — 2026-08-27
- 0.12.0-next-2be9f24c465d98f4bd186aa03ece788902e6c17a — 2026-08-27
- 1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d — 2026-08-10
- 0.11.1 — 2026-08-05
- 0.11.0 — 2026-08-05
- 0.10.0 — 2026-07-02
- … 151 more at https://npm.io/package/@dxos/graph/versions

## README

# @dxos/graph

Low-level graph API: Effect Schemas for the persisted shape, and a reactive model over Effect's
`Graph`.

## Layers

- **Schema** (`Graph.Node` / `Graph.Edge` / `Graph.Graph`) — the storage and wire format. ECHO
  object types extend these, so the persisted shape is `{ id?, nodes, edges }`.
- **Model** (`GraphModel`) — a long-lived Effect `MutableGraph` plus id↔index maps. Mutations
  apply directly and bump a version atom; snapshots in the schema shape are encoded on demand.
- **Algorithms** — `traverse` (depth-first), `topoLevels` (layered topological sort) and
  `findCycle`, all id-translated.
- **Builder** (`GraphBuilder`) — lazy expansion: registered extensions contribute nodes when a
  relation is first read. `ModelGraphBuilder` builds into a `GraphModel`; any other store can be
  driven through the `Store` port, as `@dxos/app-graph` does.
- **Selection** (`SelectionModel`) — a reactive selection set, independent of the graph itself.

## Usage

```ts
const model = new GraphModel.GraphModel();
model.batch(() => {
  model.addNode({ id: 'a' });
  model.addNode({ id: 'b' });
  model.addEdge({ source: 'a', target: 'b' });
});

const unsubscribe = model.subscribe((_, graph) => render(graph));
const node = registry.get(model.nodeAtom('a'));
```

## Rules

- **Group mutations in `batch`.** Each batch emits one notification and rebuilds the derived
  indexes once, so a loop of bare `addNode` calls costs a rebuild per element.
- **Keep high-frequency data out of the graph.** Values that change per animation frame (layout
  positions) belong in their own atoms; the model holds structure.
- **Node indexes are session-local.** They are internal to the model and never persisted; ids are
  the only stable identity.
- **Replace node data, never mutate it in place**, when views depend on it — per-node atoms cut off
  on reference equality.

## Backing stores

Pass `change` alongside `graph` to mirror structural mutations into a backing object (an ECHO
document); the function owns the transaction. Changes that did not originate through the model
reach it via `sync()`, which rebuilds only when the source has structurally diverged. Field edits
need no reconciliation — the model holds the same objects the store does, so ECHO's own reactivity
already covers them.

## Prior art

- [Graphology](https://graphology.github.io) (TS, tree-shakable, multiple packages for extensions)
- [Graphlib](https://github.com/dagrejs/graphlib) (mature, extensive)
- [tiny-graph](https://github.com/avoidwork/tiny-graph)
- levelgraph (LevelDB)
- oxigraph (Rust WASM)
- Neo4J

---
_Source: https://npm.io/package/@dxos/graph · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
