New repo

Author: phpnode

.gitignore

@@ -0,0 +1,46 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+.pnpm-store
+.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+.wrangler
+
+# testing
+coverage
+
+# next.js
+.next/
+out/
+
+# production
+build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.claude
+.mcp.json

README.md

@@ -0,0 +1,286 @@
+# @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.
+
+## 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 |
+
+---
+
+## `@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/).
+
+### Features
+
+- **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.)
+- **Multiple index types** — hash (O(1) equality), B-tree (O(log n) range), and full-text (BM25-scored)
+- **Async/distributed graph** — `AsyncGraph` supports serializable operations for use across network boundaries
+- **Readonly mode** — parse queries with `readonly: true` to prevent mutation steps
+
+### Installation
+
+```bash
+pnpm add @codemix/graph
+```
+
+### Quick Start
+
+```typescript
+import { Graph, GraphSchema } from "@codemix/graph";
+import { InMemoryGraphStorage } from "@codemix/graph";
+import * as z from "zod";
+
+// 1. Define your schema
+const schema = {
+  vertices: {
+    Person: {
+      properties: {
+        name: { type: z.string() },
+        age: { type: z.number() },
+      },
+    },
+  },
+  edges: {
+    knows: { properties: {} },
+  },
+} as const satisfies GraphSchema;
+
+// 2. Create the graph
+const graph = new Graph({
+  schema,
+  storage: new InMemoryGraphStorage(),
+});
+
+// 3. Add data
+const alice = graph.addVertex("Person", { name: "Alice", age: 30 });
+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",
+);
+// [{ a: { name: "Alice" }, b: { name: "Bob" } }]
+```
+
+### Defining a Schema
+
+```typescript
+import { GraphSchema } from "@codemix/graph";
+import * as z from "zod";
+
+const schema = {
+  vertices: {
+    Product: {
+      properties: {
+        sku: { type: z.string() },
+        price: { type: z.number().positive() },
+        name: {
+          type: z.string(),
+          index: { type: "fulltext" }, // full-text search index
+        },
+      },
+      indexes: {
+        sku: { type: "hash", unique: true }, // unique hash index
+      },
+    },
+  },
+  edges: {
+    PURCHASED: {
+      properties: {
+        quantity: { type: z.number().int().positive() },
+      },
+    },
+  },
+} as const satisfies GraphSchema;
+```
+
+### Index Types
+
+| Type       | Lookup      | Use case                                                 |
+| ---------- | ----------- | -------------------------------------------------------- |
+| `hash`     | O(1)        | Equality (`=`) on high-cardinality properties            |
+| `btree`    | O(log n)    | Range queries (`>`, `<`, `>=`, `<=`, `BETWEEN`)          |
+| `fulltext` | BM25 scored | `CONTAINS` / free-text search via `@codemix/text-search` |
+
+All index types support a `unique: true` constraint that throws `UniqueConstraintViolationError` on duplicate values.
+
+### Supported Cypher Features
+
+- `MATCH` with node and relationship patterns, variable-length paths (`*1..5`), shortest path
+- `WHERE` with boolean logic, property access, `IN`, `STARTS WITH`, `ENDS WITH`, `CONTAINS`, `IS NULL`, `IS NOT NULL`, label expressions (`IS LABELED`)
+- `RETURN` with aliases (`AS`), `DISTINCT`, `ORDER BY`, `SKIP`, `LIMIT`
+- `CREATE`, `SET`, `DELETE`, `REMOVE`, `MERGE`
+- `WITH` (pipeline intermediate results)
+- `UNWIND`
+- `UNION` / `UNION ALL`
+- Multi-statement queries (semicolon-separated)
+- `CALL` procedures (built-in and custom via `ProcedureRegistry`)
+- Aggregation functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `COLLECT`
+- List comprehensions, pattern comprehensions, `REDUCE`, `EXISTS` subqueries
+- Temporal types: `date`, `datetime`, `localtime`, `localdatetime`, `duration`
+- Arithmetic, string functions, math functions, type conversion functions
+- `CASE` expressions (simple and searched)
+
+### Parsing Queries
+
+For advanced use cases, you can parse a query to a step plan without running it:
+
+```typescript
+import { parseQueryToSteps } from "@codemix/graph";
+
+const { steps, postprocess } = parseQueryToSteps(
+  "MATCH (n:Person) RETURN n.name",
+  { readonly: true }, // throws ReadonlyGraphError if query mutates
+);
+```
+
+### Custom Functions and Procedures
+
+```typescript
+import { functionRegistry, procedureRegistry } from "@codemix/graph";
+
+// Register a custom scalar function
+functionRegistry.register("myLib.greet", {
+  call: ([name]) => `Hello, ${name}!`,
+});
+
+// Register a custom procedure
+procedureRegistry.register("myLib.listItems", {
+  call: function* (ctx, [], yields) {
+    yield { item: "foo" };
+    yield { item: "bar" };
+  },
+});
+```
+
+### AsyncGraph
+
+`AsyncGraph` wraps a regular `Graph` and exposes mutations as serializable operation objects. This is useful for sending graph mutations over a network or message bus.
+
+```typescript
+import { AsyncGraph } from "@codemix/graph";
+
+const asyncGraph = new AsyncGraph({
+  schema,
+  storage: new InMemoryGraphStorage(),
+});
+
+// Subscribe to operations emitted by writes
+asyncGraph.on("operation", (op) => {
+  sendToRemote(op); // op is a plain JSON-serializable object
+});
+
+asyncGraph.addVertex("Person", { name: "Alice", age: 30 });
+```
+
+---
+
+## `@codemix/text-search`
+
+A lightweight, dependency-free full-text search library used internally by `@codemix/graph` for full-text indexes.
+
+### Features
+
+- BM25-inspired relevance scoring
+- English word stemming
+- Works on plain strings — no indexing infrastructure required
+
+### Usage
+
+```typescript
+import { createMatcher, rankDocuments } from "@codemix/text-search";
+
+// Score a single document
+const match = createMatcher("quick brown fox");
+match("The quick brown fox jumps over the lazy dog"); // ~0.85
+match("A slow gray elephant"); // ~0.0
+
+// Rank a list of documents
+const results = rankDocuments("database performance", [
+  "How to improve database query performance",
+  "Database connection pooling best practices",
+  "Unrelated article about cooking",
+]);
+// Returns documents sorted by relevance score descending
+```
+
+---
+
+## `@codemix/y-graph-storage`
+
+A [Yjs](https://yjs.dev/) CRDT-backed storage adapter for `@codemix/graph`. Enables real-time collaborative and offline-first graph databases that sync automatically between peers.
+
+### Features
+
+- Stores graph data inside a `Y.Doc` — compatible with any Yjs provider (WebSocket, WebRTC, IndexedDB, etc.)
+- Observable — subscribe to vertex/edge changes reactively
+- Zod integration via `ZodYTypes` helpers for schema validation
+
+### Usage
+
+```typescript
+import * as Y from "yjs";
+import { Graph } from "@codemix/graph";
+import { YGraphStorage } from "@codemix/y-graph-storage";
+
+const doc = new Y.Doc();
+const storage = new YGraphStorage(doc, schema);
+const graph = new Graph({ schema, storage });
+
+// Changes to the graph are automatically reflected in the Y.Doc
+// and will sync to connected peers via any Yjs provider
+graph.addVertex("Person", { name: "Alice", age: 30 });
+```
+
+---
+
+## Development
+
+This is a pnpm monorepo managed with [pnpm workspaces](https://pnpm.io/workspaces).
+
+### Prerequisites
+
+- Node.js 20+
+- pnpm 9+
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Common Commands
+
+| Command              | Description                                |
+| -------------------- | ------------------------------------------ |
+| `pnpm test`          | Run all tests across packages (watch mode) |
+| `pnpm test:coverage` | Run all tests with coverage report         |
+| `pnpm build`         | Build all packages                         |
+| `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:check`  | Check formatting                           |
+
+### Package-level commands
+
+```bash
+# Run tests for a single package
+pnpm --filter @codemix/graph test
+
+# Build a single package
+pnpm --filter @codemix/graph build
+```
+
+## License
+
+MIT

oxlint.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+  "rules": {}
+}

package.json

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

packages/graph/.gitignore

@@ -0,0 +1,2 @@
+dist
+coverage