@loradb/lora-node 0.1.0

package/LICENSE

@@ -0,0 +1,87 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             LoraDB, Inc.
+Licensed Work:        LoraDB
+Change Date:          2029-04-19
+Change License:       Apache License, Version 2.0
+
+Additional Use Grant: You may use, copy, modify, create derivative works of,
+                      distribute, and make production use of the Licensed Work
+                      for internal business purposes and non-production
+                      purposes, provided that you do not use the Licensed Work
+                      to offer, operate, or make available a database-as-a-
+                      service, hosted API, managed database platform, or any
+                      substantially similar hosted service for third parties.
+
+                      The Additional Use Grant does not permit using the
+                      Licensed Work to provide a commercial or non-commercial
+                      hosted service that allows third parties to access LoraDB
+                      functionality, including as part of a competing managed
+                      database platform, backend-as-a-service, application
+                      platform, developer platform, or resale offering.
+
+Business Source License
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+3. To specify a Change Date.
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,130 @@
+# lora-node
+
+Node.js / TypeScript bindings for the [Lora](../../README.md) in-memory
+graph engine. The package exposes a first-class typed API: query results are
+modelled as discriminated unions, temporal values carry `kind` tags, and the
+`Database` class is strongly typed in both directions (params and rows).
+
+**Non-blocking:** `execute()` dispatches each query to the libuv threadpool via
+[`napi::Task`](https://napi.rs/docs/compat-mode/async-task). The JS event loop
+stays free for the full duration of a query — a 2 000-node MATCH happily
+interleaves with `setImmediate` ticks on the main thread (proven by a
+dedicated vitest).
+
+> **Status:** prototype / feasibility check. Not published to npm.
+
+## Install (local dev)
+
+```bash
+cd crates/lora-node
+npm install
+npm run build   # builds the Rust cdylib + TypeScript declarations
+npm test        # runs the vitest suite
+```
+
+The `npm run build:native` step uses [`@napi-rs/cli`](https://napi.rs/) and
+produces a platform-specific `lora-node.<platform>-<arch>.node` artifact next
+to `package.json`.
+
+## Usage
+
+`lora-node` is **async-only** — the sole initialization pattern is
+`createDatabase()`. There is no synchronous constructor and no
+`Database.create()` static; `Database` is a type-only export.
+
+```ts
+import { createDatabase, isNode, type LoraNode } from "lora-node";
+
+const db = await createDatabase();
+await db.execute("CREATE (:Person {name: $n, age: $a})", { n: "Alice", a: 30 });
+
+const res = await db.execute<{ n: LoraNode }>("MATCH (n:Person) RETURN n");
+for (const row of res.rows) {
+  if (isNode(row.n)) {
+    console.log(row.n.properties.name);
+  }
+}
+```
+
+The API matches `lora-wasm` verbatim — same shared types, same
+`createDatabase()` entry point, same async method signatures — so
+switching backends is a single import change.
+
+## Typed value model
+
+| TS type                 | Runtime shape                                                                 |
+|-------------------------|-------------------------------------------------------------------------------|
+| `null`/`boolean`/`number`/`string` | pass-through JS primitives                                                     |
+| `LoraValue[]` / object | homogeneous arrays and nested records                                          |
+| `LoraNode`            | `{ kind: "node", id, labels, properties }`                                      |
+| `LoraRelationship`    | `{ kind: "relationship", id, startId, endId, type, properties }`                |
+| `LoraPath`            | `{ kind: "path", nodes: number[], rels: number[] }`                             |
+| `LoraDate`…`LoraDuration` | `{ kind: "date", iso: "YYYY-MM-DD" }` etc.                              |
+| `LoraPoint`           | Discriminated union on `srid`, see below                                       |
+
+`LoraPoint` is a discriminated union over the four supported CRSes:
+
+| Shape                                                                                                        | Meaning              |
+|--------------------------------------------------------------------------------------------------------------|----------------------|
+| `{ kind: "point", srid: 7203, crs: "cartesian", x, y }`                                                      | Cartesian 2D         |
+| `{ kind: "point", srid: 9157, crs: "cartesian-3D", x, y, z }`                                                | Cartesian 3D         |
+| `{ kind: "point", srid: 4326, crs: "WGS-84-2D", x, y, longitude, latitude }`                                 | WGS-84 2D            |
+| `{ kind: "point", srid: 4979, crs: "WGS-84-3D", x, y, z, longitude, latitude, height }`                      | WGS-84 3D            |
+
+Helper constructors (`date("2025-01-15")`, `cartesian(1, 2)`, `cartesian3d(1, 2, 3)`,
+`wgs84(lon, lat)`, `wgs84_3d(lon, lat, height)`, `duration("P1M")`, …) and
+narrowing guards (`isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`)
+are exported from `lora-node`.
+
+> `distance()` on WGS-84-3D points ignores `height` — see
+> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the full spatial
+> reference and known limitations.
+
+## Architecture
+
+```
+lora-database (Rust)
+   └── lora-node (crate, cdylib)        <- napi-rs bindings, AsyncTask
+          └── ts/index.ts                 <- strongly-typed async wrapper
+                 └── ../shared-ts/types.ts  <- shared TS contract (with lora-wasm)
+```
+
+Query execution path:
+
+```
+JS main thread         libuv threadpool             Rust
+──────────────         ───────────────────          ────────────────
+db.execute(…)   ──►   ExecuteTask::compute()   ──►  parser → analyzer →
+                                                    compiler → executor →
+                                                    storage
+             ◄──   resolve() wraps serde_json::Value
+                   into JsUnknown and resolves the Promise
+```
+
+The Rust crate is added to the workspace root (`Cargo.toml`). The Node side is
+self-contained inside this directory. Only sub-millisecond operations
+(`clear`, `nodeCount`, `relationshipCount`) stay synchronous inside napi; the
+TS wrapper still exposes them as `Promise`-returning methods to keep the API
+identical to `lora-wasm`.
+
+## Errors
+
+`db.execute(...)` throws `LoraError` with a narrowed `code`:
+
+- `LORA_ERROR` — parse / analyze / execute failure
+- `INVALID_PARAMS` — a param value could not be mapped to a `LoraValue`
+
+## Known limitations
+
+- **Concurrent writes.** Each `execute()` hops through the threadpool and
+  serialises on the store mutex inside Rust, so concurrent read/read and
+  read/write traffic works. Firing many concurrent write queries against
+  the same `Database` (e.g. 2 000 parallel `CREATE`s via `Promise.all`)
+  can expose races in the underlying engine — treat the mutex as
+  per-operation, not per-query. Prefer `await`-in-a-loop or a single
+  batched query for heavy write workloads.
+- **I64 precision.** Integer values above `Number.MAX_SAFE_INTEGER`
+  (2^53) are returned as JS `number` and lose precision. A `bigint`-aware
+  path would require extending the value serializer.
+- **Cancellation.** The napi `Task` abstraction does not support
+  cancellation once dispatched; a runaway query runs to completion.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * lora-node — typed Node.js binding for the Lora graph engine.
+ *
+ * Thin wrapper over the N-API module. Query execution is delegated to the
+ * native layer, which runs each query on the libuv threadpool so the JS
+ * event loop stays responsive. This file only narrows the `unknown`-valued
+ * native surface into the strongly-typed `QueryResult<T>` / `LoraParams`
+ * shapes defined in the shared TS contract (`crates/shared-ts/types.ts`).
+ *
+ * **Initialization is async-only.** The one canonical entry point is
+ * `createDatabase()`; there is no synchronous constructor. See the docs at
+ * https://loradb.com/docs/getting-started/node for the full rationale.
+ */
+import type { LoraParams, LoraValue, QueryResult } from "./types.js";
+declare const NativeDatabase: typeof import("./native.js").Database;
+export * from "./types.js";
+/**
+ * In-memory Lora graph database instance.
+ *
+ * Obtained exclusively via `createDatabase()`. There is no public constructor
+ * and no synchronous factory — the async entry point lets the binding
+ * extend initialization later (lazy native loading, warmup, schema
+ * preflight) without breaking callers.
+ *
+ * Instances are independent — each owns its own in-memory graph. Multiple
+ * concurrent `execute()` calls against one instance run one at a time
+ * (serialised on the store mutex) but none of them block the event loop.
+ */
+declare class DatabaseImpl {
+    #private;
+    constructor(inner: InstanceType<typeof NativeDatabase>);
+    /**
+     * Execute a Lora query on the libuv threadpool. Returns a Promise that
+     * resolves with `{ columns, rows }`; errors surface as `LoraError`
+     * with a narrowed `code` (`LORA_ERROR` / `INVALID_PARAMS`).
+     */
+    execute<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): Promise<QueryResult<T>>;
+    /** Drop every node and relationship. Constant-time under the hood. */
+    clear(): Promise<void>;
+    /** Number of nodes currently in the graph. */
+    nodeCount(): Promise<number>;
+    /** Number of relationships currently in the graph. */
+    relationshipCount(): Promise<number>;
+}
+/**
+ * Public type for a LoraDB instance.
+ *
+ * Exported as a type only — there is no runtime `Database` value. To obtain
+ * an instance, always use `createDatabase()`:
+ *
+ * ```ts
+ * import { createDatabase, type Database } from "lora-node";
+ *
+ * const db: Database = await createDatabase();
+ * ```
+ */
+export type Database = DatabaseImpl;
+/**
+ * Create and initialize a new in-memory LoraDB instance.
+ *
+ * **This is the only supported initialization pattern** for `lora-node`.
+ * Synchronous construction is not available — the async factory guarantees
+ * the native layer is ready before the first query dispatches and keeps
+ * the Node and WASM surfaces symmetric.
+ *
+ * ```ts
+ * import { createDatabase } from "lora-node";
+ *
+ * const db = await createDatabase();
+ * const res = await db.execute(
+ *   "CREATE (n:Person {name: $name}) RETURN n",
+ *   { name: "Alice" },
+ * );
+ * ```
+ *
+ * Each call returns an independent graph — no shared state between instances.
+ */
+export declare function createDatabase(): Promise<Database>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAOpB,QAAA,MAAM,cAAc,EAAE,cAAc,aAAa,EAAE,QAA0B,CAAC;AAE9E,cAAc,YAAY,CAAC;AAE3B;;;;;;;;;;;GAWG;AACH,cAAM,YAAY;;gBAGJ,KAAK,EAAE,YAAY,CAAC,OAAO,cAAc,CAAC;IAItD;;;;OAIG;IACG,OAAO,CACX,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/D,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAS9D,sEAAsE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8CAA8C;IACxC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,sDAAsD;IAChD,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;CAG3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAExD"}

package/dist/index.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * lora-node — typed Node.js binding for the Lora graph engine.
+ *
+ * Thin wrapper over the N-API module. Query execution is delegated to the
+ * native layer, which runs each query on the libuv threadpool so the JS
+ * event loop stays responsive. This file only narrows the `unknown`-valued
+ * native surface into the strongly-typed `QueryResult<T>` / `LoraParams`
+ * shapes defined in the shared TS contract (`crates/shared-ts/types.ts`).
+ *
+ * **Initialization is async-only.** The one canonical entry point is
+ * `createDatabase()`; there is no synchronous constructor. See the docs at
+ * https://loradb.com/docs/getting-started/node for the full rationale.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabase = createDatabase;
+const types_js_1 = require("./types.js");
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - resolved at runtime via native.js loader
+const native_js_1 = __importDefault(require("./native.js"));
+const NativeDatabase = native_js_1.default.Database;
+__exportStar(require("./types.js"), exports);
+/**
+ * In-memory Lora graph database instance.
+ *
+ * Obtained exclusively via `createDatabase()`. There is no public constructor
+ * and no synchronous factory — the async entry point lets the binding
+ * extend initialization later (lazy native loading, warmup, schema
+ * preflight) without breaking callers.
+ *
+ * Instances are independent — each owns its own in-memory graph. Multiple
+ * concurrent `execute()` calls against one instance run one at a time
+ * (serialised on the store mutex) but none of them block the event loop.
+ */
+class DatabaseImpl {
+    #inner;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    /**
+     * Execute a Lora query on the libuv threadpool. Returns a Promise that
+     * resolves with `{ columns, rows }`; errors surface as `LoraError`
+     * with a narrowed `code` (`LORA_ERROR` / `INVALID_PARAMS`).
+     */
+    async execute(query, params) {
+        try {
+            const raw = await this.#inner.execute(query, params ?? null);
+            return raw;
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    /** Drop every node and relationship. Constant-time under the hood. */
+    async clear() {
+        this.#inner.clear();
+    }
+    /** Number of nodes currently in the graph. */
+    async nodeCount() {
+        return this.#inner.nodeCount();
+    }
+    /** Number of relationships currently in the graph. */
+    async relationshipCount() {
+        return this.#inner.relationshipCount();
+    }
+}
+/**
+ * Create and initialize a new in-memory LoraDB instance.
+ *
+ * **This is the only supported initialization pattern** for `lora-node`.
+ * Synchronous construction is not available — the async factory guarantees
+ * the native layer is ready before the first query dispatches and keeps
+ * the Node and WASM surfaces symmetric.
+ *
+ * ```ts
+ * import { createDatabase } from "lora-node";
+ *
+ * const db = await createDatabase();
+ * const res = await db.execute(
+ *   "CREATE (n:Person {name: $name}) RETURN n",
+ *   { name: "Alice" },
+ * );
+ * ```
+ *
+ * Each call returns an independent graph — no shared state between instances.
+ */
+async function createDatabase() {
+    return new DatabaseImpl(new NativeDatabase());
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;AAsGH,wCAEC;AAjGD,yCAAuC;AAEvC,6DAA6D;AAC7D,wDAAwD;AACxD,4DAAiC;AAEjC,MAAM,cAAc,GAA0C,mBAAM,CAAC,QAAQ,CAAC;AAE9E,6CAA2B;AAE3B;;;;;;;;;;;GAWG;AACH,MAAM,YAAY;IACP,MAAM,CAAsC;IAErD,YAAY,KAA0C;QACpD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAEX,KAAa,EAAE,MAAmB;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;YAC7D,OAAO,GAAqB,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,iBAAiB;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACzC,CAAC;CACF;AAgBD;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,cAAc;IAClC,OAAO,IAAI,YAAY,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/native.d.ts

@@ -0,0 +1,3 @@
+declare const _exports: any;
+export = _exports;
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../ts/native.js"],"names":[],"mappings":""}

package/dist/native.js

@@ -0,0 +1,85 @@
+// Native module loader. Picks the right platform-specific prebuilt binary if
+// present, otherwise falls back to the dev build produced by `napi build`.
+//
+// napi-rs appends an ABI suffix on some platforms:
+//   - Linux GNU:   lora-node.linux-x64-gnu.node
+//   - Linux musl:  lora-node.linux-x64-musl.node
+//   - Windows:     lora-node.win32-x64-msvc.node
+//   - macOS:       lora-node.darwin-arm64.node  (no ABI suffix)
+//   - FreeBSD:     lora-node.freebsd-x64.node
+//
+// Published installs resolve the binary through an optional platform
+// subpackage named `@loradb/lora-node-<triple>`; local dev builds drop the
+// `.node` at the crate root. We try both.
+"use strict";
+const { platform, arch } = process;
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+const { execSync } = require("node:child_process");
+function isMuslLibc() {
+    // glibc `ldd --version` mentions GNU; musl's mentions "musl".
+    try {
+        const out = execSync("ldd --version", { stdio: ["ignore", "pipe", "pipe"] })
+            .toString()
+            .toLowerCase();
+        return out.includes("musl");
+    }
+    catch {
+        // When ldd can't be run, fall back to Node's process report which
+        // exposes `glibcVersionRuntime` only on glibc systems.
+        try {
+            const header = process.report?.getReport()?.header;
+            if (header && "glibcVersionRuntime" in header)
+                return false;
+        }
+        catch {
+            /* ignore */
+        }
+        // Default to glibc — the common case on CI Linux runners.
+        return false;
+    }
+}
+function candidateTriples() {
+    if (platform === "linux") {
+        const libc = isMuslLibc() ? "musl" : "gnu";
+        return [`${platform}-${arch}-${libc}`, `${platform}-${arch}`];
+    }
+    if (platform === "win32") {
+        return [`${platform}-${arch}-msvc`, `${platform}-${arch}`];
+    }
+    // darwin, freebsd, etc — napi doesn't add an ABI suffix.
+    return [`${platform}-${arch}`];
+}
+function loadNative() {
+    const triples = candidateTriples();
+    // 1. Local dev build at the crate root (produced by `napi build`).
+    const localCandidates = [
+        ...triples.map((t) => `lora-node.${t}.node`),
+        "lora.node",
+        "lora-node.node",
+    ];
+    for (const name of localCandidates) {
+        const candidate = join(__dirname, "..", name);
+        if (existsSync(candidate)) {
+            return require(candidate);
+        }
+    }
+    // 2. Platform-specific npm subpackage (@loradb/lora-node-<triple>).
+    const subpackageNames = triples.map((t) => `@loradb/lora-node-${t}`);
+    for (const name of subpackageNames) {
+        try {
+            return require(name);
+        }
+        catch (err) {
+            if (err && err.code !== "MODULE_NOT_FOUND")
+                throw err;
+            // fall through to the next triple / final error.
+        }
+    }
+    throw new Error(`lora-node: no native binary found for ${platform}-${arch}. ` +
+        `Tried local: ${localCandidates.join(", ")}. ` +
+        `Tried npm: ${subpackageNames.join(", ")}. ` +
+        "For local development, run `npm run build` in the crate directory.");
+}
+module.exports = loadNative();
+//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../ts/native.js"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Canonical typed value model for the JS-facing Lora packages
+ * (`lora-node` and `lora-wasm`).
+ *
+ * Every structural value carries a `kind` discriminator. Temporal and
+ * spatial values are tagged so TypeScript can narrow safely after a
+ * query runs.
+ *
+ * Canonical source: `crates/shared-ts/types.ts`. Each JS-facing package
+ * (`lora-node`, `lora-wasm`) copies this file into its own `ts/` dir
+ * via its `sync:types` npm script. The `verify:types` script fails CI if
+ * the copies drift — do not edit the per-package copies directly.
+ */
+/**
+ * Values accepted as Lora query parameters. Mirrors `LoraValue` but
+ * also allows plain JS scalars / arrays / objects. Temporal and spatial
+ * values must be passed as tagged objects so the bridge can parse them
+ * without ambiguity.
+ */
+export type LoraParam = null | boolean | number | string | LoraParam[] | {
+    [key: string]: LoraParam;
+} | LoraDate | LoraTime | LoraLocalTime | LoraDateTime | LoraLocalDateTime | LoraDuration | LoraPoint;
+export type LoraParams = Record<string, LoraParam>;
+export interface LoraNode {
+    kind: "node";
+    id: number;
+    labels: string[];
+    properties: Record<string, LoraValue>;
+}
+export interface LoraRelationship {
+    kind: "relationship";
+    id: number;
+    startId: number;
+    endId: number;
+    type: string;
+    properties: Record<string, LoraValue>;
+}
+export interface LoraPath {
+    kind: "path";
+    nodes: number[];
+    rels: number[];
+}
+export interface LoraDate {
+    kind: "date";
+    /** `YYYY-MM-DD` */
+    iso: string;
+}
+export interface LoraTime {
+    kind: "time";
+    /** `HH:MM:SS[.nnn][Z|±HH:MM]` */
+    iso: string;
+}
+export interface LoraLocalTime {
+    kind: "localtime";
+    /** `HH:MM:SS[.nnn]` */
+    iso: string;
+}
+export interface LoraDateTime {
+    kind: "datetime";
+    /** `YYYY-MM-DDTHH:MM:SS[.nnn][Z|±HH:MM]` */
+    iso: string;
+}
+export interface LoraLocalDateTime {
+    kind: "localdatetime";
+    /** `YYYY-MM-DDTHH:MM:SS[.nnn]` */
+    iso: string;
+}
+export interface LoraDuration {
+    kind: "duration";
+    /** ISO-8601 duration, e.g. `P1Y2M3DT4H5M6S` */
+    iso: string;
+}
+export type TemporalKind = "date" | "time" | "localtime" | "datetime" | "localdatetime" | "duration";
+export type LoraTemporal = LoraDate | LoraTime | LoraLocalTime | LoraDateTime | LoraLocalDateTime | LoraDuration;
+/**
+ * Supported spatial-reference identifiers.
+ *
+ * - `7203` — Cartesian 2D
+ * - `9157` — Cartesian 3D
+ * - `4326` — WGS-84 Geographic 2D
+ * - `4979` — WGS-84 Geographic 3D
+ */
+export type LoraPointSrid = 7203 | 9157 | 4326 | 4979;
+/**
+ * Canonical CRS name string. Mirrors `srid` 1:1 on the output side; on
+ * the input side, `point({…, crs: "…"})` accepts these plus the alias
+ * `"WGS-84"` (equivalent to `"WGS-84-2D"`) — see the engine README.
+ */
+export type LoraPointCrs = "cartesian" | "cartesian-3D" | "WGS-84-2D" | "WGS-84-3D";
+/** Cartesian 2D point. */
+export interface LoraCartesianPoint {
+    kind: "point";
+    srid: 7203;
+    crs: "cartesian";
+    x: number;
+    y: number;
+}
+/** Cartesian 3D point. */
+export interface LoraCartesianPoint3D {
+    kind: "point";
+    srid: 9157;
+    crs: "cartesian-3D";
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * WGS-84 geographic 2D point.
+ *
+ * `x === longitude` and `y === latitude`. Both naming conventions are
+ * exposed so consumers can pick whichever is clearer at the call site.
+ */
+export interface LoraWgs84Point {
+    kind: "point";
+    srid: 4326;
+    crs: "WGS-84-2D";
+    x: number;
+    y: number;
+    longitude: number;
+    latitude: number;
+}
+/**
+ * WGS-84 geographic 3D point.
+ *
+ * `x === longitude`, `y === latitude`, `z === height` (metres).
+ *
+ * **Caveat:** `distance()` on WGS-84-3D points currently ignores
+ * `height` and computes the great-circle surface distance only. A full
+ * 3D geodesic distance is not implemented.
+ */
+export interface LoraWgs84Point3D {
+    kind: "point";
+    srid: 4979;
+    crs: "WGS-84-3D";
+    x: number;
+    y: number;
+    z: number;
+    longitude: number;
+    latitude: number;
+    height: number;
+}
+/**
+ * Any point value returned by the engine. Narrow via the `srid` or
+ * `crs` discriminator (or the `isPoint` guard plus `point.srid`).
+ */
+export type LoraPoint = LoraCartesianPoint | LoraCartesianPoint3D | LoraWgs84Point | LoraWgs84Point3D;
+export type LoraValue = null | boolean | number | string | LoraValue[] | {
+    [key: string]: LoraValue;
+} | LoraNode | LoraRelationship | LoraPath | LoraDate | LoraTime | LoraLocalTime | LoraDateTime | LoraLocalDateTime | LoraDuration | LoraPoint;
+export type QueryRow<T extends Record<string, LoraValue> = Record<string, LoraValue>> = T;
+export interface QueryResult<T extends Record<string, LoraValue> = Record<string, LoraValue>> {
+    columns: string[];
+    rows: QueryRow<T>[];
+}
+export declare function isNode(v: LoraValue): v is LoraNode;
+export declare function isRelationship(v: LoraValue): v is LoraRelationship;
+export declare function isPath(v: LoraValue): v is LoraPath;
+export declare function isPoint(v: LoraValue): v is LoraPoint;
+export declare function isTemporal(v: LoraValue): v is LoraTemporal;
+export declare const date: (iso: string) => LoraDate;
+export declare const time: (iso: string) => LoraTime;
+export declare const localtime: (iso: string) => LoraLocalTime;
+export declare const datetime: (iso: string) => LoraDateTime;
+export declare const localdatetime: (iso: string) => LoraLocalDateTime;
+export declare const duration: (iso: string) => LoraDuration;
+export declare const cartesian: (x: number, y: number) => LoraCartesianPoint;
+export declare const cartesian3d: (x: number, y: number, z: number) => LoraCartesianPoint3D;
+export declare const wgs84: (longitude: number, latitude: number) => LoraWgs84Point;
+export declare const wgs84_3d: (longitude: number, latitude: number, height: number) => LoraWgs84Point3D;
+/**
+ * Error codes emitted by the engine bridges.
+ *
+ * - `LORA_ERROR` — parse / analyze / execute failure
+ * - `INVALID_PARAMS` — a param value could not be mapped to a Lora value
+ * - `WORKER_ERROR` — worker transport / lifecycle failure (wasm worker only)
+ * - `UNKNOWN` — fall-through for unrecognised error shapes
+ */
+export type LoraErrorCode = "LORA_ERROR" | "INVALID_PARAMS" | "WORKER_ERROR" | "UNKNOWN";
+/**
+ * Error thrown by `Database.execute` when Lora parsing, analysis, or
+ * execution fails.
+ */
+export declare class LoraError extends Error {
+    readonly code: LoraErrorCode;
+    constructor(message: string, code?: LoraErrorCode);
+}
+/**
+ * Normalise a thrown value into a `LoraError` with a narrowed `code`
+ * when the message carries a recognised prefix; otherwise returns the
+ * original `Error` unchanged.
+ */
+export declare function wrapError(err: unknown): Error;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../ts/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Canonical typed value model for the JS-facing Lora packages
+ * (`lora-node` and `lora-wasm`).
+ *
+ * Every structural value carries a `kind` discriminator. Temporal and
+ * spatial values are tagged so TypeScript can narrow safely after a
+ * query runs.
+ *
+ * Canonical source: `crates/shared-ts/types.ts`. Each JS-facing package
+ * (`lora-node`, `lora-wasm`) copies this file into its own `ts/` dir
+ * via its `sync:types` npm script. The `verify:types` script fails CI if
+ * the copies drift — do not edit the per-package copies directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoraError = exports.wgs84_3d = exports.wgs84 = exports.cartesian3d = exports.cartesian = exports.duration = exports.localdatetime = exports.datetime = exports.localtime = exports.time = exports.date = void 0;
+exports.isNode = isNode;
+exports.isRelationship = isRelationship;
+exports.isPath = isPath;
+exports.isPoint = isPoint;
+exports.isTemporal = isTemporal;
+exports.wrapError = wrapError;
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+function isNode(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && v.kind === "node";
+}
+function isRelationship(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && v.kind === "relationship";
+}
+function isPath(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && v.kind === "path";
+}
+function isPoint(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && v.kind === "point";
+}
+function isTemporal(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const kind = v.kind;
+    return (kind === "date" ||
+        kind === "time" ||
+        kind === "localtime" ||
+        kind === "datetime" ||
+        kind === "localdatetime" ||
+        kind === "duration");
+}
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+const date = (iso) => ({ kind: "date", iso });
+exports.date = date;
+const time = (iso) => ({ kind: "time", iso });
+exports.time = time;
+const localtime = (iso) => ({ kind: "localtime", iso });
+exports.localtime = localtime;
+const datetime = (iso) => ({ kind: "datetime", iso });
+exports.datetime = datetime;
+const localdatetime = (iso) => ({ kind: "localdatetime", iso });
+exports.localdatetime = localdatetime;
+const duration = (iso) => ({ kind: "duration", iso });
+exports.duration = duration;
+const cartesian = (x, y) => ({
+    kind: "point",
+    srid: 7203,
+    crs: "cartesian",
+    x,
+    y,
+});
+exports.cartesian = cartesian;
+const cartesian3d = (x, y, z) => ({
+    kind: "point",
+    srid: 9157,
+    crs: "cartesian-3D",
+    x,
+    y,
+    z,
+});
+exports.cartesian3d = cartesian3d;
+const wgs84 = (longitude, latitude) => ({
+    kind: "point",
+    srid: 4326,
+    crs: "WGS-84-2D",
+    x: longitude,
+    y: latitude,
+    longitude,
+    latitude,
+});
+exports.wgs84 = wgs84;
+const wgs84_3d = (longitude, latitude, height) => ({
+    kind: "point",
+    srid: 4979,
+    crs: "WGS-84-3D",
+    x: longitude,
+    y: latitude,
+    z: height,
+    longitude,
+    latitude,
+    height,
+});
+exports.wgs84_3d = wgs84_3d;
+/**
+ * Error thrown by `Database.execute` when Lora parsing, analysis, or
+ * execution fails.
+ */
+class LoraError extends Error {
+    code;
+    constructor(message, code = "UNKNOWN") {
+        super(message);
+        this.name = "LoraError";
+        this.code = code;
+    }
+}
+exports.LoraError = LoraError;
+const ERROR_PREFIX_RE = /^(LORA_ERROR|INVALID_PARAMS|WORKER_ERROR):\s*(.*)$/s;
+/**
+ * Normalise a thrown value into a `LoraError` with a narrowed `code`
+ * when the message carries a recognised prefix; otherwise returns the
+ * original `Error` unchanged.
+ */
+function wrapError(err) {
+    if (!(err instanceof Error))
+        return new LoraError(String(err), "UNKNOWN");
+    const match = ERROR_PREFIX_RE.exec(err.message);
+    if (match) {
+        return new LoraError(match[2], match[1]);
+    }
+    return err;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../ts/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@loradb/lora-node",
+  "version": "0.1.0",
+  "description": "Node.js / TypeScript bindings for the Lora in-memory graph database",
+  "license": "BUSL-1.1",
+  "author": "LoraDB, Inc.",
+  "homepage": "https://github.com/lora-db/lora#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lora-db/lora.git",
+    "directory": "crates/lora-node"
+  },
+  "bugs": {
+    "url": "https://github.com/lora-db/lora/issues"
+  },
+  "keywords": [
+    "lora",
+    "loradb",
+    "graph",
+    "cypher",
+    "database",
+    "napi",
+    "n-api",
+    "neo4j"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "ts/native.js",
+    "ts/native.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "napi": {
+    "name": "lora-node",
+    "package": {
+      "name": "@loradb/lora-node"
+    },
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "sync:types": "node -e \"require('fs').copyFileSync('../shared-ts/types.ts','ts/types.ts')\"",
+    "verify:types": "node -e \"const fs=require('fs'); const a=fs.readFileSync('../shared-ts/types.ts','utf8'); const b=fs.readFileSync('ts/types.ts','utf8'); if (a!==b) { console.error('ts/types.ts is out of sync with shared-ts/types.ts — run npm run sync:types'); process.exit(1);} \"",
+    "prebuild": "npm run sync:types",
+    "pretypecheck": "npm run sync:types",
+    "pretest": "npm run sync:types",
+    "build:native": "napi build --platform --release --js false",
+    "build:native:debug": "napi build --platform --js false",
+    "build:ts": "tsc -p tsconfig.json",
+    "build": "npm run build:native && npm run build:ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "artifacts": "napi artifacts",
+    "create-npm-dirs": "napi create-npm-dir -t .",
+    "copy-license": "node -e \"const fs=require('fs'); try { fs.copyFileSync('../../LICENSE','LICENSE'); } catch (e) { if (e.code !== 'ENOENT') throw e; }\"",
+    "prepack": "npm run sync:types && npm run copy-license && npm run build",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "@types/node": "^22.7.4",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  },
+  "optionalDependencies": {
+    "@loradb/lora-node-linux-x64-gnu": "0.1.0",
+    "@loradb/lora-node-linux-arm64-gnu": "0.1.0",
+    "@loradb/lora-node-darwin-x64": "0.1.0",
+    "@loradb/lora-node-darwin-arm64": "0.1.0",
+    "@loradb/lora-node-win32-x64-msvc": "0.1.0"
+  }
+}

package/ts/native.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Low-level typings for the native Rust N-API module (`cypher.node`).
+ *
+ * These mirror what napi-derive would generate. The high-level TS wrapper
+ * in `index.ts` narrows the return / param types to the strongly-typed
+ * `QueryResult<T>` / `LoraParams` surface.
+ */
+
+export interface NativeQueryResult {
+  columns: string[];
+  rows: Array<Record<string, unknown>>;
+}
+
+export declare class Database {
+  constructor();
+  /** Non-blocking: runs on the libuv threadpool, returns a Promise. */
+  execute(
+    query: string,
+    params?: Record<string, unknown> | null,
+  ): Promise<NativeQueryResult>;
+  clear(): void;
+  nodeCount(): number;
+  relationshipCount(): number;
+}

package/ts/native.js

@@ -0,0 +1,90 @@
+// Native module loader. Picks the right platform-specific prebuilt binary if
+// present, otherwise falls back to the dev build produced by `napi build`.
+//
+// napi-rs appends an ABI suffix on some platforms:
+//   - Linux GNU:   lora-node.linux-x64-gnu.node
+//   - Linux musl:  lora-node.linux-x64-musl.node
+//   - Windows:     lora-node.win32-x64-msvc.node
+//   - macOS:       lora-node.darwin-arm64.node  (no ABI suffix)
+//   - FreeBSD:     lora-node.freebsd-x64.node
+//
+// Published installs resolve the binary through an optional platform
+// subpackage named `@loradb/lora-node-<triple>`; local dev builds drop the
+// `.node` at the crate root. We try both.
+
+"use strict";
+
+const { platform, arch } = process;
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+const { execSync } = require("node:child_process");
+
+function isMuslLibc() {
+  // glibc `ldd --version` mentions GNU; musl's mentions "musl".
+  try {
+    const out = execSync("ldd --version", { stdio: ["ignore", "pipe", "pipe"] })
+      .toString()
+      .toLowerCase();
+    return out.includes("musl");
+  } catch {
+    // When ldd can't be run, fall back to Node's process report which
+    // exposes `glibcVersionRuntime` only on glibc systems.
+    try {
+      const header = process.report?.getReport()?.header;
+      if (header && "glibcVersionRuntime" in header) return false;
+    } catch {
+      /* ignore */
+    }
+    // Default to glibc — the common case on CI Linux runners.
+    return false;
+  }
+}
+
+function candidateTriples() {
+  if (platform === "linux") {
+    const libc = isMuslLibc() ? "musl" : "gnu";
+    return [`${platform}-${arch}-${libc}`, `${platform}-${arch}`];
+  }
+  if (platform === "win32") {
+    return [`${platform}-${arch}-msvc`, `${platform}-${arch}`];
+  }
+  // darwin, freebsd, etc — napi doesn't add an ABI suffix.
+  return [`${platform}-${arch}`];
+}
+
+function loadNative() {
+  const triples = candidateTriples();
+
+  // 1. Local dev build at the crate root (produced by `napi build`).
+  const localCandidates = [
+    ...triples.map((t) => `lora-node.${t}.node`),
+    "lora.node",
+    "lora-node.node",
+  ];
+  for (const name of localCandidates) {
+    const candidate = join(__dirname, "..", name);
+    if (existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  // 2. Platform-specific npm subpackage (@loradb/lora-node-<triple>).
+  const subpackageNames = triples.map((t) => `@loradb/lora-node-${t}`);
+  for (const name of subpackageNames) {
+    try {
+      return require(name);
+    } catch (err) {
+      if (err && err.code !== "MODULE_NOT_FOUND") throw err;
+      // fall through to the next triple / final error.
+    }
+  }
+
+  throw new Error(
+    `lora-node: no native binary found for ${platform}-${arch}. ` +
+      `Tried local: ${localCandidates.join(", ")}. ` +
+      `Tried npm: ${subpackageNames.join(", ")}. ` +
+      "For local development, run `npm run build` in the crate directory.",
+  );
+}
+
+module.exports = loadNative();