@loradb/lora-wasm 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,197 @@
+# lora-wasm
+
+WebAssembly bindings for the [Lora](../../README.md) in-memory graph
+database. The package is designed for browsers and Node.js and exposes a
+**strongly typed, async-facing API** that keeps the main thread responsive:
+heavy query work can run inside a Web Worker while your UI code simply awaits
+the result.
+
+> **Status:** prototype / feasibility check. Not published to npm.
+
+## Build
+
+```bash
+cd crates/lora-wasm
+npm install
+npm run build              # wasm-pack (node + bundler) + tsc
+npm test                   # vitest
+```
+
+Build artefacts:
+
+| Directory         | Target              | Purpose                                                         |
+|-------------------|---------------------|-----------------------------------------------------------------|
+| `pkg-node/`       | `--target nodejs`   | In-process usage from Node (vitest, CLI, loader-node.ts)        |
+| `pkg-bundler/`    | `--target bundler`  | Consumption via Vite/webpack/esbuild                            |
+| `pkg-web/`        | `--target web`      | Browser Worker entry — self-fetches the `.wasm` binary          |
+| `dist/`           | TypeScript (`tsc`)  | Compiled wrapper (`Database`, worker, worker-client, types)     |
+
+To run the full validation suite (typecheck, vitest, Playwright browser
+test, npm pack dry-run), add:
+
+```bash
+npm run typecheck
+npm test
+npm run test:browser:install   # one-time chromium download
+npm run test:browser
+npm run pack:dry
+```
+
+## Two execution modes
+
+### 1. In-process (Node / scripts)
+
+`lora-wasm` is **async-only** — the sole initialization pattern is
+`createDatabase()`, which bootstraps the WASM module on first call.
+There is no synchronous constructor and no `Database.create()`
+static; `Database` is a type-only export.
+
+```ts
+import { createDatabase, isNode } from "lora-wasm";
+
+const db = await createDatabase();
+await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
+
+const r = await db.execute("MATCH (n:Person) RETURN n");
+for (const row of r.rows) {
+  if (isNode(row.n)) console.log(row.n.properties.name);
+}
+```
+
+### 2. Non-blocking Web Worker (browser)
+
+```ts
+import { createWorkerDatabase } from "lora-wasm/worker-client";
+
+const worker = new Worker(new URL("./worker.js", import.meta.url), {
+  type: "module",
+});
+const db = createWorkerDatabase(worker);
+
+await db.execute("CREATE (:N {n: 1})");     // runs off-main-thread
+const { rows } = await db.execute("MATCH (n) RETURN n.n AS n");
+```
+
+The worker entry (`ts/worker.ts`) hosts the WASM module. The main thread only
+posts messages, so long-running queries never block the event loop / UI.
+
+### 3. In-process but typed like the worker (advanced)
+
+The same `createWorkerDatabase` signature accepts any `WorkerLike` object —
+useful for tests and for swapping execution backends behind the same API.
+
+## Typed value model
+
+| TS type                              | Runtime shape                                                               |
+|--------------------------------------|-----------------------------------------------------------------------------|
+| `null`/`boolean`/`number`/`string`   | pass-through                                                                |
+| `LoraValue[]` / nested record      | arrays / objects                                                            |
+| `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 union of four CRS-specific shapes:
+
+| 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`, `time`, `datetime`, `localtime`, `localdatetime`,
+`duration`, `cartesian`, `cartesian3d`, `wgs84`, `wgs84_3d`. Guards:
+`isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`.
+
+> `distance()` on WGS-84-3D points ignores `height`. See
+> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the spatial
+> reference and out-of-scope operations.
+
+## Errors
+
+`db.execute(...)` and the worker client throw `LoraError` with a narrowed
+`code`:
+
+- `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 (worker client only)
+
+## Shared type contract
+
+The public TypeScript value model (`LoraValue`, `LoraNode`, …,
+`QueryResult`, `LoraError`) lives in a single canonical file at
+`crates/shared-ts/types.ts` and is copied into each consumer package by
+its `sync:types` npm script. CI runs `verify:types` to fail on drift.
+That keeps `lora-node` and `lora-wasm` locked to one identical
+public surface — consumers can swap backends without rewriting types.
+
+## Known limitations
+
+- The wasm module is single-threaded. Parallel queries inside one worker
+  serialise; spawn more workers for true parallelism.
+- I64 values are delivered as JS `number` and lose precision above 2^53.
+  Applications that need bigint precision should use the native
+  `lora-node` binding instead.
+- Wall-clock reads (`date()`, `datetime()`, `time()`, `localdatetime()`,
+  `localtime()`) are routed through `js_sys::Date::now()` on wasm32 via
+  the shim in `lora-store::temporal::unix_now`. The browser clock is
+  millisecond-granular, so the nanosecond field on returned values is
+  zero below the millisecond boundary.
+- Engine errors cross the worker boundary as `LoraError` with a
+  narrowed `code`; the engine does not currently stream query progress
+  or offer cancellation.
+
+## Feasibility assessment
+
+**What works today**
+
+- `cargo check --target wasm32-unknown-unknown` passes for the whole
+  database pipeline (`lora-ast`, `lora-parser`, `lora-analyzer`,
+  `lora-compiler`, `lora-executor`, `lora-store`,
+  `lora-database`, `lora-wasm`).
+- `wasm-pack build` succeeds for three targets (`nodejs`, `bundler`,
+  `web`) with a ~2.2 MB optimised `.wasm` each.
+- The non-blocking worker-backed path is end-to-end verified: a real
+  Chromium instance spawns a module Worker, loads the `pkg-web` bundle,
+  and runs a CREATE + MATCH round-trip — asserted by a Playwright test
+  behind `npm run test:browser`.
+- `vitest` runs 18 in-process tests against the `nodejs` bundle,
+  covering scalars, nested maps/lists, nodes, relationships, paths,
+  points, all temporal kinds including `date()`/`datetime()` no-arg
+  forms, parameter validation errors, and concurrent queries across the
+  worker message protocol.
+- The TypeScript public contract is shared verbatim with `lora-node`
+  via `crates/shared-ts/types.ts`, enforced by `verify:types` in CI.
+- `npm pack --dry-run` produces a 45-file, 6.6 MB tarball containing
+  all three wasm bundles plus the compiled TS wrapper. No `file:` deps,
+  no postinstall scripts.
+
+**What still blocks a real npm publish**
+
+- Package is marked `private: true` and the workspace is pre-1.0.
+  Publishing needs a final scope decision (e.g. `@lora/wasm`),
+  a LICENSE file, and a repository URL in `Cargo.toml`/`package.json`.
+- The three wasm bundles are each ~2.2 MB. A production publish should
+  either ship conditional exports that load only the bundle the
+  consumer imports, or switch to compressed `.wasm` + `fetch` with
+  `Content-Encoding: br`.
+- I64 precision is capped at `Number.MAX_SAFE_INTEGER`. For larger
+  integer properties we need a `bigint`-aware serializer on the wasm
+  boundary.
+- The engine is synchronous inside wasm — a single Worker serialises
+  queries. Multi-tenant workloads need either multiple Workers (already
+  possible), or an engine-level cooperative scheduler.
+- No query cancellation or progress streaming crosses the Worker
+  boundary; a slow query blocks that Worker until completion.
+
+**Bottom line**
+
+Yes — this database can be used from JavaScript and TypeScript in
+practice, in the browser and in Node, without native bindings. The
+worker-backed path keeps heavy query work off the main thread by
+default, and the strongly-typed wrapper makes query results ergonomic
+for TS consumers. The remaining gaps are packaging polish and two
+well-known wasm constraints (i64 precision, no cancellation); neither
+blocks feasibility.

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * lora-wasm — typed WebAssembly bindings for the Lora graph engine.
+ *
+ * This entry targets Node.js (ESM) and any bundler host whose resolver maps
+ * `node:module` through. Browser consumers should prefer the Worker-backed
+ * API exposed in `worker-client.ts` to keep the main thread responsive.
+ *
+ * **Initialization is async-only.** The one canonical entry point is
+ * `createDatabase()`; the WASM module is bootstrapped inside it before the
+ * first query runs. There is no synchronous constructor.
+ *
+ *   import { createDatabase } from "lora-wasm";
+ *
+ *   const db = await createDatabase();
+ *   const res = await db.execute("CREATE (:N {n: $v}) RETURN 1 AS one", { v: 1 });
+ */
+import type { LoraParams, LoraValue, QueryResult } from "./types.js";
+import { WasmDatabase } from "./loader-node.js";
+export * from "./types.js";
+export { createWorkerDatabase, type WorkerDatabase } from "./worker-client.js";
+/**
+ * In-memory Lora graph database running on the WASM engine.
+ *
+ * Obtained exclusively via `createDatabase()`. Queries still execute
+ * synchronously inside WASM, so for heavy queries in the browser prefer
+ * `createWorkerDatabase()`; every method returns a Promise for API symmetry
+ * with `lora-node` and the Worker variant.
+ */
+declare class DatabaseImpl {
+    #private;
+    constructor(inner: InstanceType<typeof WasmDatabase>);
+    execute<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): Promise<QueryResult<T>>;
+    clear(): Promise<void>;
+    nodeCount(): Promise<number>;
+    relationshipCount(): Promise<number>;
+    /** Release the underlying wasm handle. Subsequent calls will throw. */
+    dispose(): void;
+}
+/**
+ * Public type for a LoraDB instance backed by WASM.
+ *
+ * Exported as a type only — there is no runtime `Database` value. To obtain
+ * an instance, always use `createDatabase()`.
+ */
+export type Database = DatabaseImpl;
+/**
+ * Create and initialize a new in-memory LoraDB instance on the WASM engine.
+ *
+ * **This is the only supported initialization pattern** for `lora-wasm`.
+ * Synchronous construction is not available — the async factory bootstraps
+ * the WASM module on first call and guarantees the engine is ready before
+ * the first query.
+ *
+ * ```ts
+ * import { createDatabase } from "lora-wasm";
+ *
+ * const db = await createDatabase();
+ * const res = await db.execute("MATCH (n) RETURN count(n) AS n");
+ * ```
+ *
+ * For heavy browser workloads, use `createWorkerDatabase()` from
+ * `lora-wasm/worker-client` instead — it keeps the main thread responsive
+ * by running the engine in a Web Worker.
+ */
+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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAoB,MAAM,kBAAkB,CAAC;AAElE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAS/E;;;;;;;GAOG;AACH,cAAM,YAAY;;gBAGJ,KAAK,EAAE,YAAY,CAAC,OAAO,YAAY,CAAC;IAI9C,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;IASxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAGhB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAGxD"}

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * lora-wasm — typed WebAssembly bindings for the Lora graph engine.
+ *
+ * This entry targets Node.js (ESM) and any bundler host whose resolver maps
+ * `node:module` through. Browser consumers should prefer the Worker-backed
+ * API exposed in `worker-client.ts` to keep the main thread responsive.
+ *
+ * **Initialization is async-only.** The one canonical entry point is
+ * `createDatabase()`; the WASM module is bootstrapped inside it before the
+ * first query runs. There is no synchronous constructor.
+ *
+ *   import { createDatabase } from "lora-wasm";
+ *
+ *   const db = await createDatabase();
+ *   const res = await db.execute("CREATE (:N {n: $v}) RETURN 1 AS one", { v: 1 });
+ */
+import { wrapError } from "./types.js";
+import { WasmDatabase, init as wasmInit } from "./loader-node.js";
+export * from "./types.js";
+export { createWorkerDatabase } from "./worker-client.js";
+let bootstrapped = false;
+function ensureBootstrapped() {
+    if (bootstrapped)
+        return;
+    wasmInit();
+    bootstrapped = true;
+}
+/**
+ * In-memory Lora graph database running on the WASM engine.
+ *
+ * Obtained exclusively via `createDatabase()`. Queries still execute
+ * synchronously inside WASM, so for heavy queries in the browser prefer
+ * `createWorkerDatabase()`; every method returns a Promise for API symmetry
+ * with `lora-node` and the Worker variant.
+ */
+class DatabaseImpl {
+    #inner;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    async execute(query, params) {
+        try {
+            const raw = this.#inner.execute(query, (params ?? null));
+            return raw;
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async clear() {
+        this.#inner.clear();
+    }
+    async nodeCount() {
+        return this.#inner.nodeCount();
+    }
+    async relationshipCount() {
+        return this.#inner.relationshipCount();
+    }
+    /** Release the underlying wasm handle. Subsequent calls will throw. */
+    dispose() {
+        this.#inner.free();
+    }
+}
+/**
+ * Create and initialize a new in-memory LoraDB instance on the WASM engine.
+ *
+ * **This is the only supported initialization pattern** for `lora-wasm`.
+ * Synchronous construction is not available — the async factory bootstraps
+ * the WASM module on first call and guarantees the engine is ready before
+ * the first query.
+ *
+ * ```ts
+ * import { createDatabase } from "lora-wasm";
+ *
+ * const db = await createDatabase();
+ * const res = await db.execute("MATCH (n) RETURN count(n) AS n");
+ * ```
+ *
+ * For heavy browser workloads, use `createWorkerDatabase()` from
+ * `lora-wasm/worker-client` instead — it keeps the main thread responsive
+ * by running the engine in a Web Worker.
+ */
+export async function createDatabase() {
+    ensureBootstrapped();
+    return new DatabaseImpl(new WasmDatabase());
+}
+//# 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;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAElE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAuB,MAAM,oBAAoB,CAAC;AAE/E,IAAI,YAAY,GAAG,KAAK,CAAC;AACzB,SAAS,kBAAkB;IACzB,IAAI,YAAY;QAAE,OAAO;IACzB,QAAQ,EAAE,CAAC;IACX,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,YAAY;IACP,MAAM,CAAoC;IAEnD,YAAY,KAAwC;QAClD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO,CAEX,KAAa,EAAE,MAAmB;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,IAAI,IAAI,CAAY,CAAC,CAAC;YACpE,OAAO,GAAqB,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,iBAAiB;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACzC,CAAC;IAED,uEAAuE;IACvE,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;CACF;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,kBAAkB,EAAE,CAAC;IACrB,OAAO,IAAI,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;AAC9C,CAAC"}

package/dist/loader-node.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Node-specific loader. The wasm-pack `--target nodejs` output is CommonJS,
+ * so we wrap it with `createRequire` to stay ESM-compatible.
+ */
+import type { WasmDatabase as NativeWasmDatabase } from "../pkg-node/lora_wasm.js";
+export interface NativeModule {
+    WasmDatabase: new () => NativeWasmDatabase;
+    init: () => void;
+}
+export declare const WasmDatabase: new () => NativeWasmDatabase;
+export declare const init: () => void;
+//# sourceMappingURL=loader-node.d.ts.map

package/dist/loader-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-node.d.ts","sourceRoot":"","sources":["../ts/loader-node.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnF,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,UAAU,kBAAkB,CAAC;IAC3C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAOD,eAAO,MAAM,YAAY,YATC,kBASkB,CAAC;AAC7C,eAAO,MAAM,IAAI,QATH,IASc,CAAC"}

package/dist/loader-node.js

@@ -0,0 +1,12 @@
+/**
+ * Node-specific loader. The wasm-pack `--target nodejs` output is CommonJS,
+ * so we wrap it with `createRequire` to stay ESM-compatible.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+// The pkg-node path is stable because `wasm-pack build --out-dir pkg-node`
+// writes it next to this file's parent.
+const mod = require("../pkg-node/lora_wasm.js");
+export const WasmDatabase = mod.WasmDatabase;
+export const init = mod.init;
+//# sourceMappingURL=loader-node.js.map

package/dist/loader-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-node.js","sourceRoot":"","sources":["../ts/loader-node.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAQ5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,2EAA2E;AAC3E,wCAAwC;AACxC,MAAM,GAAG,GAAG,OAAO,CAAC,0BAA0B,CAAiB,CAAC;AAEhE,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;AAC7C,MAAM,CAAC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC"}

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