frogql 0.2.0-rc.2

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the `frogql` npm package will be documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Released in lock-step with the [PyPI `frogql` package](https://pypi.org/project/frogql/).
+
+## [Unreleased]
+
+## [0.2.0-rc.2] — 2026-05-12
+
+### Added
+
+- Initial public release of the napi-rs Node.js bindings for froGQL.
+- Module surface: `open(path)`, `importJson(dbPath, jsonPath)`, `importCsv(dbPath, csvDir)`.
+- `Connection` class with `nodeCount`, `edgeCount`, `execute(query, limit?)`, `save()`, `schema()`, `graphTypes()`.
+- Strong TypeScript types for return shapes: `SchemaSummary`, `GraphTypeSummary`, `NodeRef`, `EdgeRef`, `DmCounters`, `DdlOk`, `IndexResult`, `IndexSummary`.
+- Polymorphic `execute()` typed as `unknown` with documented cast targets per statement kind.
+- Per-platform prebuilt binaries: macOS x64 + arm64, Linux x64 + arm64 (glibc), Windows x64.
+- Pre-release tag mapped to npm dist-tag `next`; stable releases land on `latest`.
+
+### Notes
+
+`-rc.x` indicates the release pipeline (build matrix, multi-package publish, provenance) is being validated. Surface and on-disk format are stable; the next release will be `0.2.0` without the suffix once the platform matrix has shipped one clean tag end-to-end.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matías Toro and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# frogql
+
+[![npm](https://img.shields.io/npm/v/frogql?color=blue)](https://www.npmjs.com/package/frogql)
+[![PyPI](https://img.shields.io/pypi/v/frogql?label=pypi)](https://pypi.org/project/frogql/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Embedded GQL graph database for Node.js. ISO GQL path-pattern queries, single-file `.gdb` storage, Leapfrog-Triejoin runtime, ships as a native addon. Designed to drop into a VSCode extension, an Electron app, or any Node service that needs an in-process graph DB without spinning up Neo4j.
+
+Rust core compiled to a native `.node` binary via [napi-rs](https://napi.rs). Sibling Python package on [PyPI](https://pypi.org/project/frogql/) shares the same engine + on-disk format.
+
+## Install
+
+```bash
+npm install frogql
+```
+
+Prebuilt binaries for macOS x64 + arm64, Linux x64 + arm64 (glibc), Windows x64. npm picks the right one for the host at install time via `optionalDependencies` — no compilation step, no build toolchain needed.
+
+## Quick start
+
+```ts
+import { open } from "frogql";
+
+const conn = open("examples/movies.gdb");
+
+// 1. Count nodes / edges
+console.log(conn.nodeCount, conn.edgeCount);
+
+// 2. Run a query — alias-keyed rows.
+const rows = conn.execute(
+  `MATCH (m:Movie {released: 1999})<-[:ACTED_IN]-(p:Person)
+   RETURN p.name AS actor, m.title AS film`,
+  20
+) as Array<{ actor: string; film: string }>;
+
+console.log(rows);
+// [
+//   { actor: "Keanu Reeves",      film: "The Matrix" },
+//   { actor: "Carrie-Anne Moss",  film: "The Matrix" },
+//   ...
+// ]
+```
+
+## Why frogql
+
+- **ISO/IEC 39075:2024 path patterns.** Real Graph Query Language, not Cypher-flavoured pseudocode. Union (`|`), concat, repetition (`{n,m}`), `OPTIONAL MATCH`, `EXISTS`, `WHERE`, aggregates, `ORDER BY ... LIMIT`. Type system with subtyping, label algebra, and structural row types.
+- **Worst-case-optimal join.** Leapfrog Triejoin over six sorted orderings of the edge set. 14×–4000× faster than pairwise hash-join on shape-heavy LDBC queries (numbers in [`docs/internals/JOIN_STRATEGY_NOTES.md`](https://github.com/pleiad/frogql/blob/main/docs/internals/JOIN_STRATEGY_NOTES.md)).
+- **Single-file storage** (`.gdb`). 4 KB pages, slotted layout, CSR adjacency, page-cached property store. One file moves with your app.
+- **Embeddable.** No server, no daemon, no HTTP. Open a path, run queries, close. Lives in the same process as your extension / Electron app / CLI.
+- **Secondary indexes.** Hash for equality, B-tree for ranges. Auto-built per `(label, property)` pair where values are unique within a label. Optional DDL: `CREATE INDEX ... ON :Label(prop)`.
+- **Data modification.** ISO §13 `INSERT`, `SET`, `REMOVE`, `DELETE`, `DETACH DELETE`. Overlay-on-disk model: mutations live in RAM until you call `conn.save()`, SQLite-style.
+
+## API
+
+### `open(path: string): Connection`
+
+Open or create a `.gdb`. Eagerly warms the LTJ TripleIndex so the first query runs at warm-cache speed.
+
+### `importJson(dbPath: string, jsonPath: string): void`
+
+Build a fresh `.gdb` from a JSON file shaped `{ nodes: [...], edges: [...] }`. Overwrites the destination.
+
+### `importCsv(dbPath: string, csvDir: string): void`
+
+Build a fresh `.gdb` from a directory of CSVs configured via `spanner_import_config.json`. Used by the LDBC ingest pipeline; see [Cloud Spanner import format docs](https://cloud.google.com/spanner/docs/import).
+
+### `class Connection`
+
+| Member | Returns | Notes |
+|---|---|---|
+| `nodeCount` | `number` | Live count (base + overlay). |
+| `edgeCount` | `number` | Live count (base + overlay). |
+| `execute(query, limit?)` | `unknown` | Polymorphic — see [Return shapes](#executequery-limit-return-shapes). |
+| `save()` | `void` | Persist base + overlay to the file the connection was opened from. |
+| `schema()` | `SchemaSummary` | Sorted node / edge label sets + counts. |
+| `graphTypes()` | `GraphTypeSummary[]` | Catalog entries with active markers. |
+
+### `execute(query, limit?)` return shapes
+
+`execute` returns `unknown` because the shape depends on the statement kind. Cast at the call site:
+
+```ts
+import type {
+  NodeRef, EdgeRef, DmCounters, DdlOk, IndexResult, IndexSummary,
+  GraphTypeSummary, SchemaSummary,
+} from "frogql";
+```
+
+| Statement | Cast target |
+|---|---|
+| Query with `RETURN` | `Array<Record<string, unknown>>` keyed by alias |
+| Query without `RETURN` | `Array<{ _paths: unknown[]; [v: string]: unknown }>` |
+| `CREATE / USE / DROP GRAPH TYPE` | `DdlOk` |
+| `SHOW GRAPH TYPES` | `GraphTypeSummary[]` |
+| `SHOW GRAPH TYPE <name>` | object with `name`, `active`, `nodes`, `edges`, `formatted`, optional `validation` |
+| `CREATE / DROP INDEX` | `IndexResult` |
+| `SHOW INDEXES` | `IndexSummary[]` |
+| `INSERT / SET / REMOVE / DELETE / DETACH DELETE` | `DmCounters` |
+
+Node and edge references inside row values use `NodeRef` / `EdgeRef`. The `props` field on `EdgeRef` is optional: present when returned via `RETURN e` at the top level, omitted in path-internal context to keep payloads small.
+
+## Examples
+
+### Pattern matching with repetition
+
+```ts
+const friends = conn.execute(
+  `MATCH (p:Person {id: 12345})~[:knows]~{1,2}(f:Person)
+   WHERE p <> f
+   RETURN f.firstName AS name, f.lastName AS surname
+   LIMIT 20`,
+  20
+) as Array<{ name: string; surname: string }>;
+```
+
+Bounded repetition `{1,2}` unrolls to a worst-case-optimal join per length. See [perf series](https://github.com/pleiad/frogql/blob/main/docs/internals/implemented-optimizations.md) for the optimizer pipeline.
+
+### Aggregation + ordering
+
+```ts
+const top = conn.execute(
+  `MATCH (m:Movie)<-[:ACTED_IN]-(p:Person)
+   RETURN m.title AS film, COUNT(p) AS cast
+   GROUP BY m.title
+   ORDER BY cast DESC, film ASC
+   LIMIT 10`,
+  10
+) as Array<{ film: string; cast: number }>;
+```
+
+`ORDER BY ... LIMIT` drives through a btree-backed top-k path when an index exists on the sort key; otherwise pdqsort.
+
+### Optional match
+
+```ts
+const rows = conn.execute(
+  `MATCH (p:Person)
+   OPTIONAL MATCH (p)-[:ACTED_IN]->(m:Movie)
+   RETURN p.name AS actor, m.title AS film
+   LIMIT 50`,
+  50
+) as Array<{ actor: string; film: string | null }>;
+```
+
+Left-outer join with bind-pushdown: per outer row, pin shared variables and pin-execute the inner. SQLite-style nested-loop. ~93× speedup vs the global-evaluate-and-join baseline on LDBC IS5.
+
+### Insert, modify, persist
+
+```ts
+import type { DmCounters } from "frogql";
+
+const a = conn.execute("INSERT (:Person {name: 'Alice', age: 30})") as DmCounters;
+console.log(a.nodesInserted); // 1
+
+conn.execute("MATCH (p:Person {name: 'Alice'}) SET p.age = 31");
+conn.execute("MATCH (p:Person {name: 'Alice'}) REMOVE p.age");
+
+// Until you save(), mutations live in the in-memory overlay only.
+conn.save();
+```
+
+### Schema introspection
+
+```ts
+const s = conn.schema();
+// { nodeLabels: ['Movie', 'Person'], edgeLabels: ['ACTED_IN', ...], nodeCount: 171, edgeCount: 253 }
+
+const types = conn.graphTypes();
+// [{ name: 'DEFAULT', active: true, nodes: 2, edges: 6 }]
+```
+
+### Indexes
+
+```ts
+const r = conn.execute("CREATE INDEX ON :Person(name) USING HASH") as IndexResult;
+const r2 = conn.execute("CREATE INDEX ON :Person(age) USING BTREE") as IndexResult;
+const idx = conn.execute("SHOW INDEXES") as IndexSummary[];
+// auto-built indexes appear here too (auto: true).
+```
+
+`HASH` accelerates equality lookups (`x.name = 'Alice'`); `BTREE` powers range scans (`x.age >= 18`) and ORDER BY top-k.
+
+## Use in a VSCode extension
+
+The Node addon runs in-process inside the extension host (which is Node.js). No subprocess, no IPC, no serialisation overhead.
+
+```ts
+import * as vscode from "vscode";
+import { open } from "frogql";
+import type { NodeRef } from "frogql";
+
+export function activate(ctx: vscode.ExtensionContext) {
+  const dbPath = ctx.asAbsolutePath("data/movies.gdb");
+  const conn = open(dbPath);
+
+  ctx.subscriptions.push(
+    vscode.commands.registerCommand("frogql.queryActors", async () => {
+      const film = await vscode.window.showInputBox({ prompt: "Movie title" });
+      if (!film) return;
+      const rows = conn.execute(
+        `MATCH (m:Movie {title: '${film.replace(/'/g, "\\'")}'})<-[:ACTED_IN]-(p:Person)
+         RETURN p.name AS actor`,
+        50
+      ) as Array<{ actor: string }>;
+      vscode.window.showInformationMessage(rows.map(r => r.actor).join(", "));
+    })
+  );
+}
+```
+
+Add `frogql` to `dependencies` in `package.json`. `vsce package` bundles the platform `.node` into the `.vsix`.
+
+**Caveats**
+
+- Desktop only. Native addons don't load in `vscode.dev` / github.dev / Codespaces web. Use a WASM build for web targets.
+- Per-platform packaging. A `.vsix` carries one platform binary. To ship for every OS, run `vsce package --target darwin-arm64`, `--target win32-x64`, etc. and publish per-platform on the marketplace.
+
+## Platforms
+
+| OS | Arch | npm package |
+|---|---|---|
+| macOS | x64 | `frogql-darwin-x64` |
+| macOS | arm64 (Apple Silicon) | `frogql-darwin-arm64` |
+| Linux | x64 (glibc) | `frogql-linux-x64-gnu` |
+| Linux | arm64 (glibc) | `frogql-linux-arm64-gnu` |
+| Windows | x64 | `frogql-win32-x64-msvc` |
+
+Other targets (musl Linux, FreeBSD, Windows arm64) aren't built today. If you need one, open an issue at [pleiad/frogql](https://github.com/pleiad/frogql/issues).
+
+## Performance
+
+Numbers from `bench/data/ldbc-sf0.1.gdb` (LDBC Social Network scale-factor 0.1: 327K nodes, 1.5M edges) on an Apple M-series laptop, lazy backend, three iterations, warm cache:
+
+| Query | gqlrust (with indexes) | GraphQLite (Cypher + SQLite reference) | Speedup |
+|---|---|---|---|
+| LDBC IC2 (recent messages) | **8.7 ms** | 32.8 ms | 3.8× |
+| LDBC IS5 (forum on creator) | varies, indexed lookup + bind-pushdown | — | — |
+
+Open time on the same DB: ~570 ms warm (string table 80 ms + topology 70 ms + secondary index auto-build 420 ms + TripleIndex 670 ms — the last two are memory-only and rebuild each open).
+
+For the full benchmark suite see [`docs/internals/JOIN_STRATEGY_NOTES.md`](https://github.com/pleiad/frogql/blob/main/docs/internals/JOIN_STRATEGY_NOTES.md) and [`bench/cross-system/`](https://github.com/pleiad/frogql/tree/main/bench/cross-system).
+
+## Versioning
+
+Released in lock-step with the PyPI `frogql` package: a single `v*` git tag fires both release workflows. Same Rust core, same `.gdb` format, fully interoperable.
+
+Pre-releases (`0.2.0-rc.1`, `-rc.2`, …) publish to dist-tag `next` so `npm install frogql` keeps pointing at the latest stable. Install a pre-release explicitly with `npm install frogql@next`.
+
+## Develop locally
+
+```bash
+git clone https://github.com/pleiad/frogql.git
+cd frogql/node
+npm install
+npm run build       # produces frogql.<platform>.node + index.js + index.d.ts
+npm test            # runtime smoke tests (node --test)
+npm run typecheck   # tsc --noEmit against __test__/types.test.ts
+```
+
+Requires Node ≥ 16 and a stable Rust toolchain.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Related
+
+- [`frogql` on PyPI](https://pypi.org/project/frogql/) — Python bindings, same engine.
+- [`pleiad/frogql`](https://github.com/pleiad/frogql) — main repository, Rust core, CLI (`frogql` binary modelled on `sqlite3`), benchmark suite, architecture docs.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "frogql",
+  "version": "0.2.0-rc.2",
+  "description": "froGQL — embedded GQL graph database with ISO GQL path patterns (Rust core, Node.js bindings via napi-rs)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "Matías Toro <mtoro.cl@gmail.com>",
+  "homepage": "https://github.com/pleiad/frogql#readme",
+  "bugs": "https://github.com/pleiad/frogql/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pleiad/frogql.git",
+    "directory": "node"
+  },
+  "keywords": [
+    "gql",
+    "graph",
+    "database",
+    "query",
+    "ltj",
+    "leapfrog-triejoin",
+    "iso-gql",
+    "napi-rs"
+  ],
+  "engines": {
+    "node": ">= 16"
+  },
+  "napi": {
+    "name": "frogql",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "node --test __test__/smoke.mjs",
+    "typecheck": "tsc --noEmit",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "optionalDependencies": {
+    "frogql-darwin-x64": "0.2.0-rc.2",
+    "frogql-darwin-arm64": "0.2.0-rc.2",
+    "frogql-linux-x64-gnu": "0.2.0-rc.2",
+    "frogql-linux-arm64-gnu": "0.2.0-rc.2",
+    "frogql-win32-x64-msvc": "0.2.0-rc.2"
+  }
+}