@loradb/lora-wasm 0.9.0 → 0.10.1

package/pkg-bundler/lora_wasm_bg.wasm.d.ts

@@ -1,29 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-export const memory: WebAssembly.Memory;
-export const __wbg_wasmdatabase_free: (a: number, b: number) => void;
-export const __wbg_wasmquerystream_free: (a: number, b: number) => void;
-export const wasmdatabase_clear: (a: number) => void;
-export const wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
-export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_new: () => number;
-export const wasmdatabase_nodeCount: (a: number) => number;
-export const wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_relationshipCount: (a: number) => number;
-export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
-export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
-export const wasmquerystream_close: (a: number) => void;
-export const wasmquerystream_columns: (a: number) => [number, number, number];
-export const wasmquerystream_next: (a: number) => [number, number, number];
-export const init: () => void;
-export const __wbindgen_malloc: (a: number, b: number) => number;
-export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-export const __wbindgen_exn_store: (a: number) => void;
-export const __externref_table_alloc: () => number;
-export const __wbindgen_export_4: WebAssembly.Table;
-export const __wbindgen_free: (a: number, b: number, c: number) => void;
-export const __externref_table_dealloc: (a: number) => void;
-export const __wbindgen_start: () => void;

package/pkg-bundler/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "lora-wasm",
-  "type": "module",
-  "collaborators": [
-    "LoraDB, Inc."
-  ],
-  "description": "WebAssembly bindings for the Lora in-memory graph database",
-  "version": "0.9.0",
-  "license": "BUSL-1.1",
-  "files": [
-    "lora_wasm_bg.wasm",
-    "lora_wasm.js",
-    "lora_wasm_bg.js",
-    "lora_wasm.d.ts"
-  ],
-  "main": "lora_wasm.js",
-  "types": "lora_wasm.d.ts",
-  "sideEffects": [
-    "./lora_wasm.js",
-    "./snippets/*"
-  ]
-}

package/pkg-node/LICENSE

@@ -1,87 +0,0 @@
-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/pkg-node/README.md

@@ -1,303 +0,0 @@
-# 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.
-
-> **Package:** `@loradb/lora-wasm`.
-
-## Build
-
-```bash
-cd crates/bindings/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
-```
-
-## Execution modes
-
-### 1. Default: Worker first, main-thread fallback
-
-`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.
-
-In browser-like hosts, `createDatabase()` tries to spawn the packaged module
-Worker first and pings it before returning. If the Worker cannot be created or
-fails during startup, the package emits one `console.warn` and falls back to
-the in-process WASM engine so the app can still run.
-
-```ts
-import { createDatabase, isNode } from "@loradb/lora-wasm";
-
-const db = await createDatabase(); // Worker-backed in browsers when possible
-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);
-}
-```
-
-### Explain & Profile
-
-`db.explain()` and `db.profile()` are first-class methods alongside
-`db.execute()`. They are intentionally *separate calls*, not a flag
-on `execute()`, so plan inspection and runtime metrics must be
-requested explicitly.
-
-```ts
-const plan = await db.explain(
-  "MATCH (p:Person) WHERE p.name = $name RETURN p",
-  { name: "Alice" },
-);
-console.log(plan.shape);          // "readOnly"
-console.log(plan.tree.operator);
-
-const profile = await db.profile(
-  "MATCH (p:Person) WHERE p.name = $name RETURN p",
-  { name: "Alice" },
-);
-console.log(profile.metrics.totalElapsedNs);
-console.log(profile.metrics.perOperator); // per-step inclusive timing
-```
-
-`explain()` never invokes the executor — calling it on a mutating
-query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
-untouched.
-
-> **`profile()` executes the query for real.** Mutating queries
-> produce the same side effects as `execute()`. Use `explain()` to
-> inspect a mutating plan without running it.
-
-To force the in-process engine:
-
-```ts
-const db = await createDatabase({ runtime: "main-thread" });
-```
-
-To require Worker startup instead of falling back:
-
-```ts
-const db = await createDatabase({ runtime: "worker" });
-```
-
-To disable the fallback warning:
-
-```ts
-const db = await createDatabase({ warnOnFallback: false });
-```
-
-### 2. Explicit main-thread WASM
-
-```ts
-import { createMainThreadDatabase } from "@loradb/lora-wasm";
-
-const db = await createMainThreadDatabase();
-```
-
-### 3. Custom Web Worker
-
-Use this when you need to control the Worker URL, lifecycle, bundler entry, or
-pooling strategy.
-
-```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.
-
-### 4. 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.
-
-## Snapshots
-
-WASM has no filesystem access, so snapshots never accept string paths.
-`saveSnapshot()` defaults to `Uint8Array`, and can also return `ArrayBuffer`,
-`Blob`, `Response`, `ReadableStream`, or an object `URL`. `loadSnapshot`
-accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, and web
-`ReadableStream<Uint8Array | ArrayBuffer>`. The bytes use the database
-snapshot codec (`LORACOL1`) and can be loaded by native LoraDB. Older store
-snapshots use the current `LORACOL1` columnar format.
-Snapshot bytes are uncompressed by default; pass `{ compression: "gzip" }` or
-`{ compression: { format: "gzip", level: 1 } }` to save smaller
-WASM-portable snapshots. Gzip levels `0..9` are supported; level `1` is the
-fast default.
-
-```ts
-import { createDatabase } from "@loradb/lora-wasm";
-
-const db = await createDatabase();
-await db.execute("CREATE (:Person {name: 'Alice'})");
-
-const bytes = await db.saveSnapshot();
-const compressed = await db.saveSnapshot({ compression: "gzip" });
-const blob = await db.saveSnapshot({ format: "blob", compression: "gzip" });
-const response = await db.saveSnapshot({ format: "response" });
-
-await db.loadSnapshot(bytes);
-await db.loadSnapshot(compressed);
-await db.loadSnapshot(blob);
-await db.loadSnapshot(response);
-await db.loadSnapshot(new URL("/graph.lorasnap", location.href));
-```
-
-## 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` from the `LoraErrorCode` union — these mirror
-`lora_database::LoraErrorCode` 1:1, plus `WORKER_ERROR` and `UNKNOWN`.
-
-Common ones:
-
-- `LORA_PARSE` — Cypher syntax could not be parsed
-- `LORA_SEMANTIC` — analysis failure (unknown variable, label, type mismatch, …)
-- `LORA_INVALID_PARAMS` — a parameter value could not be coerced to a `LoraValue`
-- `LORA_INVALID_VECTOR` — vector value failed dimension / coordinate-type validation
-- `LORA_TIMEOUT` — query exceeded its cooperative deadline
-- `LORA_IO`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO` — storage / snapshot failures
-- `LORA_INTERNAL` — last-resort fallback when the engine cannot classify the failure
-- `WORKER_ERROR` — worker transport / lifecycle failure (worker client only)
-
-See `ts/types.ts` (`LoraErrorCode`) for the full list.
-
-## Shared type contract
-
-The public TypeScript value model (`LoraValue`, `LoraNode`, …,
-`QueryResult`, `LoraError`) lives in a single canonical file at
-`crates/bindings/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 runs inside one JavaScript runtime. Auto-commit reads can
-  overlap on engine snapshots; write commits serialize. Use more Workers for
-  separate graphs or stronger UI isolation.
-- 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 offer query 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/bindings/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 once a call enters the module. A slow
-  query blocks that Worker until completion.
-- 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/pkg-node/lora_wasm.d.ts

@@ -1,85 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Call once at module start to install a panic hook that routes Rust
- * panics to `console.error`. No-op if compiled without the default feature.
- */
-export function init(): void;
-/**
- * In-memory Lora graph database handle.
- */
-export class WasmDatabase {
-  free(): void;
-  nodeCount(): number;
-  /**
-   * Open a true native row stream. Rows are pulled from the Rust executor
-   * one `next()` call at a time.
-   */
-  openStream(query: string, params: any): WasmQueryStream;
-  /**
-   * Execute an array of `{ query, params? }` statements inside one native
-   * transaction. Returns an array of query results in statement order.
-   */
-  transaction(statements: any, mode?: string | null): any;
-  /**
-   * Replace the graph state with a database snapshot decoded from `bytes`.
-   * Legacy store snapshot bytes are accepted for compatibility.
-   *
-   * Returns a plain object matching the shape of `SnapshotMeta`:
-   * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
-   */
-  loadSnapshot(bytes: Uint8Array, options: any): any;
-  /**
-   * Serialize the graph into database snapshot bytes. The caller is
-   * responsible for writing them to IndexedDB, localStorage, a server, or
-   * another host-provided store — WASM has no direct filesystem access.
-   * The returned bytes can later be passed to `loadSnapshot` on any
-   * `WasmDatabase` instance.
-   *
-   * Returns the serialized bytes as a `Uint8Array`.
-   */
-  saveSnapshot(options: any): Uint8Array;
-  /**
-   * Execute a Lora query and return the result as a binary buffer.
-   *
-   * Wire format is the shared `lora_binding_buffer` layout. The TS
-   * wrapper decodes it once into the same `{ columns, rows }` shape
-   * `execute()` returns, but in a tight V8 loop instead of going
-   * through `serde_wasm_bindgen` value-by-value. Materially faster
-   * on bulk reads.
-   */
-  executeBuffer(query: string, params: any): Uint8Array;
-  relationshipCount(): number;
-  constructor();
-  clear(): void;
-  /**
-   * Execute a Lora query. `params` may be `undefined`, `null`, or a
-   * plain object keyed by parameter name.
-   *
-   * Returns `{ columns: string[], rows: Array<Record<string, LoraValue>> }`
-   * as a plain JS object (structured-clonable).
-   */
-  execute(query: string, params: any): any;
-  /**
-   * Compile a query and return its plan without executing it.
-   *
-   * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
-   * the graph untouched — this method never runs the executor.
-   */
-  explain(query: string, params: any): any;
-  /**
-   * Execute a query and return the plan plus runtime metrics.
-   *
-   * **PROFILE executes the query for real.** Mutating queries are
-   * persisted exactly as in `execute()`. Use `explain()` to inspect
-   * a mutating plan without running it.
-   */
-  profile(query: string, params: any): any;
-}
-export class WasmQueryStream {
-  private constructor();
-  free(): void;
-  next(): any;
-  close(): void;
-  columns(): any;
-}