Merge pull request #1 from codemix/docs

Enhance README with detailed descriptions of type-safe TinkerPop/Gremlin traversal API and its integration in the @codemix/graph package. Update package descriptions for clarity and consistency.

Author: phpnode

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Format check
+        run: pnpm run format:check
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Test
+        run: pnpm exec vitest run

.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "ignorePatterns": ["**/grammar.js", "**/grammar.d.ts"]
+}

README.md

@@ -1,23 +1,26 @@
 # @codemix/graph
 
-A full type safe,TypeScript-first in-memory property graph database with a Cypher query language parser, multiple index types, and pluggable storage adapters.
+A fully type-safe, TypeScript-first in-memory property graph database with a Cypher query language parser, a **type-safe [TinkerPop](https://tinkerpop.apache.org/) / [Gremlin](https://tinkerpop.apache.org/docs/current/reference/#gremlin)-style traversal API** (`GraphTraversal`), multiple index types, and pluggable storage adapters including a [Yjs](https://yjs.dev/) CRDT-based adapter for collaborative/realtime/offline-first use.
+
+This is the knowledge graph database for the [codemix](https://codemix.com/) product intelligence platform.
 
 ## Packages
 
-| Package                                                  | Version | Description                                                                      |
-| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
-| [`@codemix/graph`](./packages/graph)                     | 0.0.1   | Core graph database with Cypher query support                                    |
-| [`@codemix/text-search`](./packages/text-search)         | 0.0.1   | BM25-based full-text search with English stemming                                |
-| [`@codemix/y-graph-storage`](./packages/y-graph-storage) | 0.0.1   | [Yjs](https://yjs.dev/) CRDT storage adapter for collaborative/offline-first use |
+| Package                                                  | Version | Description                                                                                 |
+| -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| [`@codemix/graph`](./packages/graph)                     | 0.0.1   | Core graph database: Cypher queries + type-safe Gremlin-style traversals (`GraphTraversal`) |
+| [`@codemix/text-search`](./packages/text-search)         | 0.0.1   | BM25-based full-text search with English stemming                                           |
+| [`@codemix/y-graph-storage`](./packages/y-graph-storage) | 0.0.1   | [Yjs](https://yjs.dev/) CRDT storage adapter for collaborative/offline-first use            |
 
 ---
 
 ## `@codemix/graph`
 
-A fully typed, in-memory graph database. Vertices and edges are strongly typed against a user-defined schema. Queries are written in a subset of [Cypher](https://neo4j.com/docs/cypher-manual/current/).
+A fully typed, in-memory graph database. Vertices and edges are strongly typed against a user-defined schema. You can query with a subset of [Cypher](https://neo4j.com/docs/cypher-manual/current/) **or** with a fluent, **type-safe [Apache TinkerPop](https://tinkerpop.apache.org/) / [Gremlin](https://tinkerpop.apache.org/docs/current/reference/#gremlin)-style API** — see [`GraphTraversal`](./packages/graph/README.md#type-safe-tinkerpop--gremlin-traversal-api) in the package docs.
 
 ### Features
 
+- **Type-safe TinkerPop / Gremlin traversals** — `GraphTraversal` exposes familiar steps (`V()`, `E()`, `out()`, `in()`, `both()`, `hasLabel()`, `as()` / `select()`, `repeat()` …) with schema-derived typing on paths and properties; pairs with `AsyncGraph.query` for remote execution
 - **Cypher query language** — parsed via a PEG grammar, supporting `MATCH`, `WHERE`, `RETURN`, `CREATE`, `SET`, `DELETE`, `MERGE`, `UNWIND`, `UNION`, `WITH`, multi-statement queries, and more
 - **Strongly typed schema** — vertex/edge labels and their properties are defined once and inferred throughout
 - **Standard Schema validation** — property values are validated using [Standard Schema](https://standardschema.dev/) compatible validators (works with Zod, Valibot, etc.)
@@ -65,12 +68,25 @@ const bob = graph.addVertex("Person", { name: "Bob", age: 25 });
 graph.addEdge(alice, "knows", bob, {});
 
 // 4. Query with Cypher
-const results = graph.query(
-  "MATCH (a:Person)-[:knows]->(b:Person) RETURN a.name, b.name",
-);
+const results = graph.query("MATCH (a:Person)-[:knows]->(b:Person) RETURN a.name, b.name");
 // [{ a: { name: "Alice" }, b: { name: "Bob" } }]
 ```
 
+### Type-safe Gremlin-style traversals
+
+The same graph is navigable with a fluent API modeled on [Apache TinkerPop Gremlin](https://tinkerpop.apache.org/docs/current/reference/#gremlin); labels and properties stay typed end-to-end:
+
+```typescript
+import { GraphTraversal } from "@codemix/graph";
+
+const g = new GraphTraversal(graph);
+for (const path of g.V().hasLabel("Person").out("knows")) {
+  console.log(path.value.get("name"));
+}
+```
+
+See the [type-safe TinkerPop / Gremlin traversal API](./packages/graph/README.md#type-safe-tinkerpop--gremlin-traversal-api) section in `@codemix/graph` for the full step reference.
+
 ### Defining a Schema
 
 ```typescript
@@ -268,7 +284,7 @@ pnpm install
 | `pnpm typecheck`     | Type-check all packages                    |
 | `pnpm lint`          | Lint with oxlint                           |
 | `pnpm lint:fix`      | Lint and auto-fix                          |
-| `pnpm format`        | Format with Prettier                       |
+| `pnpm format`        | Format with oxfmt                          |
 | `pnpm format:check`  | Check formatting                           |
 
 ### Package-level commands

package.json

@@ -1,7 +1,10 @@
 {
   "name": "@codemix/graph-monorepo",
   "version": "1.0.0",
+  "private": true,
   "description": "The codemix graph database monorepo",
+  "keywords": [],
+  "license": "MIT",
   "workspaces": [
     "packages/*"
   ],
@@ -12,16 +15,13 @@
     "test:coverage": "vitest run --coverage",
     "lint": "oxlint --ignore-pattern '**/grammar.js' .",
     "lint:fix": "pnpm run lint --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check ."
   },
-  "keywords": [],
-  "license": "MIT",
-  "private": true,
   "devDependencies": {
     "@vitest/coverage-istanbul": "catalog:",
-    "oxlint": "^1.59.0",
     "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
     "typescript": "catalog:",
     "vitest": "catalog:"
   }

packages/graph/README.md

@@ -1,6 +1,6 @@
 # @codemix/graph
 
-A fully type safe, TypeScript-first in-memory property graph database with a Cypher-compatible query language, a fluent traversal API, lazy indexes, and async transport support.
+A fully type-safe, TypeScript-first in-memory property graph database with a Cypher-compatible query language, a **type-safe [Apache TinkerPop](https://tinkerpop.apache.org/) / [Gremlin](https://tinkerpop.apache.org/docs/current/reference/#gremlin)-style traversal API** (`GraphTraversal`), lazy indexes, and async transport support.
 
 ## Table of Contents
 
@@ -19,7 +19,7 @@ A fully type safe, TypeScript-first in-memory property graph database with a Cyp
   - [Supported Clauses](#supported-clauses)
   - [Supported Functions](#supported-functions)
   - [Supported Procedures](#supported-procedures)
-- [Traversal API](#traversal-api)
+- [Type-safe TinkerPop / Gremlin traversal API](#type-safe-tinkerpop--gremlin-traversal-api)
   - [Starting a Traversal](#starting-a-traversal)
   - [Navigation Steps](#navigation-steps)
   - [Filtering](#filtering)
@@ -44,7 +44,7 @@ A fully type safe, TypeScript-first in-memory property graph database with a Cyp
 
 - **TypeScript-first** — schema-derived types flow through the entire API; vertex/edge properties are fully typed.
 - **Cypher-compatible query language** — parse and execute `MATCH … WHERE … RETURN` queries, `UNION`, multi-statement queries, `CREATE`, `SET`, `DELETE`, `MERGE`, `UNWIND`, `CALL`, `FOREACH`, and more.
-- **Fluent traversal API** — a gremlin-inspired builder that produces strongly-typed `TraversalPath` chains (`V().out().hasLabel(…).as(…).select(…)`).
+- **Type-safe TinkerPop / Gremlin traversals** — `GraphTraversal` mirrors familiar Gremlin steps (`V`, `E`, `out` / `in` / `both`, `hasLabel`, `as` / `select`, `repeat`, …) with **schema-derived TypeScript types** on `TraversalPath` and property access, not untyped strings at every hop.
 - **Lazy indexes** — hash, B-tree, and full-text indexes are built on first use and maintained incrementally on every mutation.
 - **Unique constraints** — enforce uniqueness on any indexed property.
 - **Standard Schema validation** — property types are validated via the [Standard Schema](https://github.com/standard-schema/standard-schema) spec (compatible with Zod, Valibot, ArkType, etc.).
@@ -66,12 +66,7 @@ pnpm add @codemix/graph
 ## Quick Start
 
 ```ts
-import {
-  Graph,
-  GraphSchema,
-  InMemoryGraphStorage,
-  GraphTraversal,
-} from "@codemix/graph";
+import { Graph, GraphSchema, InMemoryGraphStorage, GraphTraversal } from "@codemix/graph";
 import * as v from "valibot"; // any Standard Schema library
 
 const schema = {
@@ -229,12 +224,7 @@ graph.deleteEdge(edge);
 Use `parseQueryToSteps` to compile a Cypher string and get back executable steps plus a result mapper:
 
 ```ts
-import {
-  Graph,
-  InMemoryGraphStorage,
-  parseQueryToSteps,
-  GraphTraversal,
-} from "@codemix/graph";
+import { Graph, InMemoryGraphStorage, parseQueryToSteps, GraphTraversal } from "@codemix/graph";
 
 const { steps, postprocess } = parseQueryToSteps(
   "MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE p.name = $name RETURN p.name, m.title",
@@ -330,7 +320,11 @@ procedureRegistry.register({
 
 ---
 
-## Traversal API
+## Type-safe TinkerPop / Gremlin traversal API
+
+`GraphTraversal` ([`src/Traversals.ts`](./src/Traversals.ts)) is the programmatic counterpart to Cypher: a **fluent, Gremlin-style** API in the spirit of [Apache TinkerPop](https://tinkerpop.apache.org/) — same mental model as `g.V().out('knows')` in Gremlin — but **fully typed** against your `GraphSchema` so labels, edge directions, and property keys are checked by TypeScript.
+
+If you already know Gremlin, the step names and composition will feel familiar; the main difference is that paths carry typed vertices/edges from your schema instead of generic maps.
 
 ### Starting a Traversal
 
@@ -373,12 +367,7 @@ g.V()
 ### Labeling and Selection
 
 ```ts
-g.V()
-  .hasLabel("Person")
-  .as("actor")
-  .out("ACTED_IN")
-  .as("movie")
-  .select("actor", "movie");
+g.V().hasLabel("Person").as("actor").out("ACTED_IN").as("movie").select("actor", "movie");
 // yields { actor: TraversalPath, movie: TraversalPath }
 ```
 
@@ -506,11 +495,7 @@ Duplicate inserts into a unique-indexed property throw `UniqueConstraintViolatio
 **Server side:**
 
 ```ts
-import {
-  Graph,
-  InMemoryGraphStorage,
-  handleAsyncCommand,
-} from "@codemix/graph";
+import { Graph, InMemoryGraphStorage, handleAsyncCommand } from "@codemix/graph";
 
 const graph = new Graph({ schema, storage: new InMemoryGraphStorage() });
 
@@ -549,12 +534,7 @@ for await (const path of remote.query((g) => g.V().hasLabel("Person"))) {
 Implement the `GraphStorage` interface to plug in any backend:
 
 ```ts
-import {
-  GraphStorage,
-  StoredVertex,
-  StoredEdge,
-  ElementId,
-} from "@codemix/graph";
+import { GraphStorage, StoredVertex, StoredEdge, ElementId } from "@codemix/graph";
 
 class MyStorage implements GraphStorage {
   getVertexById(id: ElementId): StoredVertex | undefined {
@@ -608,10 +588,7 @@ const graph = new Graph({ schema, storage: new MyStorage() });
 Generate a human (or LLM) readable description of the query language and your schema for use in prompts or documentation:
 
 ```ts
-import {
-  generateGrammarDescription,
-  generateSchemaGuide,
-} from "@codemix/graph";
+import { generateGrammarDescription, generateSchemaGuide } from "@codemix/graph";
 
 // Language grammar description (schema-agnostic)
 const grammar = generateGrammarDescription();

packages/graph/package.json

@@ -2,7 +2,9 @@
   "name": "@codemix/graph",
   "version": "0.0.1",
   "description": "The codemix graph database.",
+  "license": "MIT",
   "type": "module",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -11,23 +13,21 @@
       }
     }
   },
-  "types": "./dist/index.d.ts",
-  "license": "MIT",
   "scripts": {
     "build": "pnpm run build:grammar && tsc",
     "build:grammar": "peggy --format es src/grammar.peggy -o src/grammar.js --dts --return-types '{\"MultiStatement\": \"import('\\''./AST.js'\\'').Query | import('\\''./AST.js'\\'').UnionQuery | import('\\''./AST.js'\\'').MultiStatement\", \"CypherStatement\": \"import('\\''./AST.js'\\'').Query | import('\\''./AST.js'\\'').UnionQuery\"}' && mkdir -p dist && cp src/grammar.* dist",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:coverage": "vitest run --coverage"
   },
-  "devDependencies": {
-    "@vitest/coverage-istanbul": "catalog:",
-    "vitest": "catalog:",
-    "typescript": "catalog:",
-    "peggy": "^5.1.0"
-  },
   "dependencies": {
     "@codemix/text-search": "workspace:*",
     "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-istanbul": "catalog:",
+    "peggy": "^5.1.0",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   }
 }