`@codemix/graph` A real-time, type-safe graph database in a CRDT.

A graph database for TypeScript with full type safety, Gremlin and Cypher-style queries, full text search, and a pluggable storage layer—including a collaborative, offline-first Yjs backend.

Define your schema with Zod, Valibot, ArkType, and other Standard Schema libraries. Build type-safe traversals with a Gremlin-like API. Store the graph in Yjs for sync and realtime collaboration. Connect your LLM to the graph to let it execute Cypher-like queries.

Global airline routes demo

Load a snapshot of real airline routes into the graph and query it with TypeScript.

Routes Workbench

Airports: 3.5K
Routes: 50.6K
Countries: 237

Examples:

Longest routes
Shortest LBA -> SBA
Airports in a country
Routes from LHR

Installation

Install the package from npm — no native dependencies, runs anywhere Node or a bundler can.

$ pnpm add @codemix/graph

Note: This is alpha-quality software. We use it in production at codemix and it works well for our use cases, but please be careful using it with your own data.

Define your schema

Describe vertices, edges, and indexes in a plain object. Property types flow through every query, traversal, and mutation — no casts, no runtime surprises.

import { Graph, GraphSchema, InMemoryGraphStorage } from "@codemix/graph";
import { z } from "zod";

const schema = {
  vertices: {
    User: {
      properties: {
        email: { type: z.email(), index: { type: "hash", unique: true } },
        name:  { type: z.string() },
      },
    },
    Repo: {
      properties: {
        name:  { type: z.string() },
        stars: { type: z.number() },
      },
    },
  },
  edges: {
    OWNS:    { properties: {} },
    FOLLOWS: { properties: {} },
  },
} as const satisfies GraphSchema;

const graph = new Graph({ schema, storage: new InMemoryGraphStorage() });

→Any Standard Schema library— Zod, Valibot, ArkType, or your own.
→Validated on every mutation— properties are checked on addVertex, addEdge, and updateProperty.
→Indexes declared inline— hash, B-tree, and full-text; built lazily and maintained incrementally.

Add some data

Vertices and edges are added through the graph instance. Property arguments are checked against your schema at both compile time and runtime.

// add vertices — args are typed to each label's property schema
const alice  = graph.addVertex("User", { name: "Alice", email: "alice@example.com" });
const bob    = graph.addVertex("User", { name: "Bob",   email: "bob@example.com" });
const myRepo = graph.addVertex("Repo", { name: "my-repo", stars: 0 });

// add edges
graph.addEdge(alice, "OWNS",    myRepo, {});
graph.addEdge(bob,   "FOLLOWS", alice,  {});

// read properties — types come from the schema
alice.get("name");     // string
myRepo.get("stars");   // number

// update in place
graph.updateProperty(myRepo, "stars", 42);
// or via the element itself
myRepo.set("stars", 42);

Write type-safe queries

A Gremlin-style traversal API — familiar step names, but every label, property key, and hop is checked by TypeScript against your schema.

Start a traversal

import { GraphTraversal } from "@codemix/graph";

const g = new GraphTraversal(graph);

for (const path of g.V().hasLabel("User")) {
  path.value.get("name");  // string  ✓
  path.value.get("email"); // string  ✓
}

Filter by property

// exact match or predicate
const [alice] = g.V()
  .hasLabel("User")
  .has("email", "alice@example.com");

const seniors = g.V()
  .hasLabel("User")
  .where((v) => v.get("name").startsWith("A"));

Traverse edges

// follow OWNS edges from User → Repo
for (const path of g.V()
  .hasLabel("User")
  .has("email", "alice@example.com")
  .out("OWNS").hasLabel("Repo")) {
  path.value.get("stars"); // number — typed from Repo's schema
}

Label and select

// capture vertices at multiple hops and project them together
for (const { user, repo } of g.V()
  .hasLabel("User").as("user")
  .out("FOLLOWS")
  .out("OWNS").hasLabel("Repo").as("repo")
  .select("user", "repo")) {
  console.log(
    user.value.get("name"),  // string
    repo.value.get("stars")   // number
  );
}

Offline-first sync and realtime collaboration

Swap InMemoryGraphStorage for YGraph and the entire graph lives in a Yjs CRDT document. Every traversal, Cypher query, and index works unchanged — you just get conflict-free sync on top.

Plug in a provider

import * as Y from "yjs";
import { WebsocketProvider } from "y-websocket";
import { YGraph } from "@codemix/y-graph-storage";

const doc = new Y.Doc();
const graph = new YGraph({ schema, doc });

// Connect any Yjs provider — sync happens automatically.
// Every peer that joins the room sees the same graph.
const provider = new WebsocketProvider("wss://my-server", "graph-room", doc);

Subscribe to fine-grained changes

// Events fire for local and remote mutations alike
const unsubscribe = graph.subscribe({
  next(change) {
    // change.kind is one of:
    //   "vertex.added" | "vertex.deleted"
    //   "edge.added"   | "edge.deleted"
    //   "vertex.property.set" | "vertex.property.changed"
    console.log(change.kind, change.id);
  },
});

Live queries

// Wraps any traversal and re-fires when the result set could change
const topRepos = graph.query((g) =>
  g.V().hasLabel("Repo").order("stars", "desc").limit(10)
);

const unsubscribe = topRepos.subscribe({
  next() {
    for (const path of topRepos) {
      console.log(path.value.get("name"), path.value.get("stars"));
    }
  },
});

// Adding or updating a Repo elsewhere — even from a remote peer —
// triggers the subscriber automatically.
graph.updateProperty(myRepo, "stars", 99);

Collaborative property types

import { ZodYText, ZodYArray } from "@codemix/y-graph-storage";
import { z } from "zod";

// Declare Y.Text / Y.Array / Y.Map properties in the schema
const schema = {
  vertices: {
    Document: {
      properties: {
        title:   { type: ZodYText },          // collaborative string
        tags:    { type: ZodYArray(z.string()) }, // collaborative array
      },
    },
  },
  edges: {},
} as const satisfies GraphSchema;

// Plain values are auto-converted — no need to construct Y.* manually
const doc = graph.addVertex("Document", { title: "Hello", tags: ["crdt"] });

// Mutate in place — all peers see the change with no conflicts
doc.get("title").insert(5, ", world");
doc.get("tags").push(["graph"]);

Cypher queries for APIs and LLMs

The same graph is queryable via a Cypher-compatible string language — ideal for exposing data to LLMs via an MCP server, or accepting ad-hoc queries from external clients without bundling a traversal library.

Parse and execute

import { parseQueryToSteps, createTraverser } from "@codemix/graph";

const { steps, postprocess } = parseQueryToSteps(`
  MATCH (u:User)-[:OWNS]->(r:Repo)
  WHERE r.stars > 100
  RETURN u.name, r.name
  ORDER BY r.stars DESC
  LIMIT 10
`);

const traverser = createTraverser(steps);
for (const row of traverser.traverse(graph, [])) {
  console.log(postprocess(row));
  // { u: { name: "Alice" }, r: { name: "my-repo" } }
}

Parameterised queries

// Pass parameters to avoid string interpolation
const { steps, postprocess } = parseQueryToSteps(`
  MATCH (u:User { email: $email })-[:OWNS]->(r:Repo)
  RETURN r.name, r.stars
`);

const traverser = createTraverser(steps);
const rows = Array.from(
  traverser.traverse(graph, [{ email: "alice@example.com" }])
).map(postprocess);

Mutations

// CREATE, MERGE, SET, DELETE are all supported
const { steps } = parseQueryToSteps(`
  MATCH (r:Repo { name: $name })
  SET r.stars = r.stars + 1
`);

createTraverser(steps).traverse(graph, [{ name: "my-repo" }]);

// Enforce read-only — throws ReadonlyGraphError on any write clause
const { steps: safeSteps } = parseQueryToSteps(query, { readonly: true });

License & History

This package is licensed under the MIT license.

It was originally written as a research project by Charles Pick, founder of codemix and author of the infamous ts-sql demo. Later, when we were building codemix we needed a structured knowledge graph, so we adapted the code, added Y.js support and later, Opus 4.5 added a Cypher-like query language.

@codemix/graph A real-time, type-safe graph database in a CRDT.