@loradb/lora-wasm 0.9.0 → 0.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +11 -8
- package/pkg-bundler/LICENSE +0 -87
- package/pkg-bundler/README.md +0 -303
- package/pkg-bundler/lora_wasm.d.ts +0 -85
- package/pkg-bundler/lora_wasm.js +0 -5
- package/pkg-bundler/lora_wasm_bg.js +0 -835
- package/pkg-bundler/lora_wasm_bg.wasm +0 -0
- package/pkg-bundler/lora_wasm_bg.wasm.d.ts +0 -29
- package/pkg-bundler/package.json +0 -22
- package/pkg-node/LICENSE +0 -87
- package/pkg-node/README.md +0 -303
- package/pkg-node/lora_wasm.d.ts +0 -85
- package/pkg-node/lora_wasm.js +0 -843
- package/pkg-node/lora_wasm_bg.wasm +0 -0
- package/pkg-node/lora_wasm_bg.wasm.d.ts +0 -29
- package/pkg-node/package.json +0 -16
- package/pkg-web/LICENSE +0 -87
- package/pkg-web/README.md +0 -303
- package/pkg-web/lora_wasm.d.ts +0 -138
- package/pkg-web/lora_wasm.js +0 -866
- package/pkg-web/lora_wasm_bg.wasm +0 -0
- package/pkg-web/lora_wasm_bg.wasm.d.ts +0 -29
- package/pkg-web/package.json +0 -20
|
Binary file
|
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
/* tslint:disable */
|
|
2
|
-
/* eslint-disable */
|
|
3
|
-
export const memory: WebAssembly.Memory;
|
|
4
|
-
export const __wbg_wasmdatabase_free: (a: number, b: number) => void;
|
|
5
|
-
export const __wbg_wasmquerystream_free: (a: number, b: number) => void;
|
|
6
|
-
export const wasmdatabase_clear: (a: number) => void;
|
|
7
|
-
export const wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
8
|
-
export const wasmdatabase_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
|
|
9
|
-
export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
10
|
-
export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
11
|
-
export const wasmdatabase_new: () => number;
|
|
12
|
-
export const wasmdatabase_nodeCount: (a: number) => number;
|
|
13
|
-
export const wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
14
|
-
export const wasmdatabase_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
15
|
-
export const wasmdatabase_relationshipCount: (a: number) => number;
|
|
16
|
-
export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
|
|
17
|
-
export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
|
|
18
|
-
export const wasmquerystream_close: (a: number) => void;
|
|
19
|
-
export const wasmquerystream_columns: (a: number) => [number, number, number];
|
|
20
|
-
export const wasmquerystream_next: (a: number) => [number, number, number];
|
|
21
|
-
export const init: () => void;
|
|
22
|
-
export const __wbindgen_malloc: (a: number, b: number) => number;
|
|
23
|
-
export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
|
|
24
|
-
export const __wbindgen_exn_store: (a: number) => void;
|
|
25
|
-
export const __externref_table_alloc: () => number;
|
|
26
|
-
export const __wbindgen_export_4: WebAssembly.Table;
|
|
27
|
-
export const __wbindgen_free: (a: number, b: number, c: number) => void;
|
|
28
|
-
export const __externref_table_dealloc: (a: number) => void;
|
|
29
|
-
export const __wbindgen_start: () => void;
|
package/pkg-node/package.json
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "lora-wasm",
|
|
3
|
-
"collaborators": [
|
|
4
|
-
"LoraDB, Inc."
|
|
5
|
-
],
|
|
6
|
-
"description": "WebAssembly bindings for the Lora in-memory graph database",
|
|
7
|
-
"version": "0.9.0",
|
|
8
|
-
"license": "BUSL-1.1",
|
|
9
|
-
"files": [
|
|
10
|
-
"lora_wasm_bg.wasm",
|
|
11
|
-
"lora_wasm.js",
|
|
12
|
-
"lora_wasm.d.ts"
|
|
13
|
-
],
|
|
14
|
-
"main": "lora_wasm.js",
|
|
15
|
-
"types": "lora_wasm.d.ts"
|
|
16
|
-
}
|
package/pkg-web/LICENSE
DELETED
|
@@ -1,87 +0,0 @@
|
|
|
1
|
-
Business Source License 1.1
|
|
2
|
-
|
|
3
|
-
Parameters
|
|
4
|
-
|
|
5
|
-
Licensor: LoraDB, Inc.
|
|
6
|
-
Licensed Work: LoraDB
|
|
7
|
-
Change Date: 2029-04-19
|
|
8
|
-
Change License: Apache License, Version 2.0
|
|
9
|
-
|
|
10
|
-
Additional Use Grant: You may use, copy, modify, create derivative works of,
|
|
11
|
-
distribute, and make production use of the Licensed Work
|
|
12
|
-
for internal business purposes and non-production
|
|
13
|
-
purposes, provided that you do not use the Licensed Work
|
|
14
|
-
to offer, operate, or make available a database-as-a-
|
|
15
|
-
service, hosted API, managed database platform, or any
|
|
16
|
-
substantially similar hosted service for third parties.
|
|
17
|
-
|
|
18
|
-
The Additional Use Grant does not permit using the
|
|
19
|
-
Licensed Work to provide a commercial or non-commercial
|
|
20
|
-
hosted service that allows third parties to access LoraDB
|
|
21
|
-
functionality, including as part of a competing managed
|
|
22
|
-
database platform, backend-as-a-service, application
|
|
23
|
-
platform, developer platform, or resale offering.
|
|
24
|
-
|
|
25
|
-
Business Source License
|
|
26
|
-
|
|
27
|
-
Terms
|
|
28
|
-
|
|
29
|
-
The Licensor hereby grants you the right to copy, modify, create derivative
|
|
30
|
-
works, redistribute, and make non-production use of the Licensed Work. The
|
|
31
|
-
Licensor may make an Additional Use Grant, above, permitting limited production
|
|
32
|
-
use.
|
|
33
|
-
|
|
34
|
-
Effective on the Change Date, or the fourth anniversary of the first publicly
|
|
35
|
-
available distribution of a specific version of the Licensed Work under this
|
|
36
|
-
License, whichever comes first, the Licensor hereby grants you rights under
|
|
37
|
-
the terms of the Change License, and the rights granted in the paragraph
|
|
38
|
-
above terminate.
|
|
39
|
-
|
|
40
|
-
If your use of the Licensed Work does not comply with the requirements
|
|
41
|
-
currently in effect as described in this License, you must purchase a
|
|
42
|
-
commercial license from the Licensor, its affiliated entities, or authorized
|
|
43
|
-
resellers, or you must refrain from using the Licensed Work.
|
|
44
|
-
|
|
45
|
-
All copies of the original and modified Licensed Work, and derivative works
|
|
46
|
-
of the Licensed Work, are subject to this License. This License applies
|
|
47
|
-
separately for each version of the Licensed Work and the Change Date may vary
|
|
48
|
-
for each version of the Licensed Work released by Licensor.
|
|
49
|
-
|
|
50
|
-
You must conspicuously display this License on each original or modified copy
|
|
51
|
-
of the Licensed Work. If you receive the Licensed Work in original or modified
|
|
52
|
-
form from a third party, the terms and conditions set forth in this License
|
|
53
|
-
apply to your use of that work.
|
|
54
|
-
|
|
55
|
-
Any use of the Licensed Work in violation of this License will automatically
|
|
56
|
-
terminate your rights under this License for the current and all other
|
|
57
|
-
versions of the Licensed Work.
|
|
58
|
-
|
|
59
|
-
This License does not grant you any right in any trademark or logo of Licensor
|
|
60
|
-
or its affiliates.
|
|
61
|
-
|
|
62
|
-
TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
|
|
63
|
-
AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
|
|
64
|
-
EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY,
|
|
65
|
-
FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
|
|
66
|
-
|
|
67
|
-
MariaDB hereby grants you permission to use this License's text to license
|
|
68
|
-
your works, and to refer to it using the trademark "Business Source License",
|
|
69
|
-
as long as you comply with the Covenants of Licensor below.
|
|
70
|
-
|
|
71
|
-
Covenants of Licensor
|
|
72
|
-
|
|
73
|
-
In consideration of the right to use this License's text and the "Business
|
|
74
|
-
Source License" name and trademark, Licensor covenants to MariaDB, and to all
|
|
75
|
-
other recipients of the licensed work to be provided by Licensor:
|
|
76
|
-
|
|
77
|
-
1. To specify as the Change License the GPL Version 2.0 or any later version,
|
|
78
|
-
or a license that is compatible with GPL Version 2.0 or a later version,
|
|
79
|
-
where "compatible" means that software provided under the Change License can
|
|
80
|
-
be included in a program with software provided under GPL Version 2.0 or a
|
|
81
|
-
later version. Licensor may specify additional Change Licenses without
|
|
82
|
-
limitation.
|
|
83
|
-
2. To either: (a) specify an additional grant of rights to use that does not
|
|
84
|
-
impose any additional restriction on the right granted in this License, as
|
|
85
|
-
the Additional Use Grant; or (b) insert the text "None".
|
|
86
|
-
3. To specify a Change Date.
|
|
87
|
-
4. Not to modify this License in any other way.
|
package/pkg-web/README.md
DELETED
|
@@ -1,303 +0,0 @@
|
|
|
1
|
-
# lora-wasm
|
|
2
|
-
|
|
3
|
-
WebAssembly bindings for the [Lora](../../../README.md) in-memory graph
|
|
4
|
-
database. The package is designed for browsers and Node.js and exposes a
|
|
5
|
-
**strongly typed, async-facing API** that keeps the main thread responsive:
|
|
6
|
-
heavy query work can run inside a Web Worker while your UI code simply awaits
|
|
7
|
-
the result.
|
|
8
|
-
|
|
9
|
-
> **Package:** `@loradb/lora-wasm`.
|
|
10
|
-
|
|
11
|
-
## Build
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
cd crates/bindings/lora-wasm
|
|
15
|
-
npm install
|
|
16
|
-
npm run build # wasm-pack (node + bundler) + tsc
|
|
17
|
-
npm test # vitest
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Build artefacts:
|
|
21
|
-
|
|
22
|
-
| Directory | Target | Purpose |
|
|
23
|
-
|-------------------|---------------------|-----------------------------------------------------------------|
|
|
24
|
-
| `pkg-node/` | `--target nodejs` | In-process usage from Node (vitest, CLI, loader-node.ts) |
|
|
25
|
-
| `pkg-bundler/` | `--target bundler` | Consumption via Vite/webpack/esbuild |
|
|
26
|
-
| `pkg-web/` | `--target web` | Browser Worker entry — self-fetches the `.wasm` binary |
|
|
27
|
-
| `dist/` | TypeScript (`tsc`) | Compiled wrapper (`Database`, worker, worker-client, types) |
|
|
28
|
-
|
|
29
|
-
To run the full validation suite (typecheck, vitest, Playwright browser
|
|
30
|
-
test, npm pack dry-run), add:
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
npm run typecheck
|
|
34
|
-
npm test
|
|
35
|
-
npm run test:browser:install # one-time chromium download
|
|
36
|
-
npm run test:browser
|
|
37
|
-
npm run pack:dry
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Execution modes
|
|
41
|
-
|
|
42
|
-
### 1. Default: Worker first, main-thread fallback
|
|
43
|
-
|
|
44
|
-
`lora-wasm` is **async-only** — the sole initialization pattern is
|
|
45
|
-
`createDatabase()`, which bootstraps the WASM module on first call.
|
|
46
|
-
There is no synchronous constructor and no `Database.create()`
|
|
47
|
-
static; `Database` is a type-only export.
|
|
48
|
-
|
|
49
|
-
In browser-like hosts, `createDatabase()` tries to spawn the packaged module
|
|
50
|
-
Worker first and pings it before returning. If the Worker cannot be created or
|
|
51
|
-
fails during startup, the package emits one `console.warn` and falls back to
|
|
52
|
-
the in-process WASM engine so the app can still run.
|
|
53
|
-
|
|
54
|
-
```ts
|
|
55
|
-
import { createDatabase, isNode } from "@loradb/lora-wasm";
|
|
56
|
-
|
|
57
|
-
const db = await createDatabase(); // Worker-backed in browsers when possible
|
|
58
|
-
await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
|
|
59
|
-
|
|
60
|
-
const r = await db.execute("MATCH (n:Person) RETURN n");
|
|
61
|
-
for (const row of r.rows) {
|
|
62
|
-
if (isNode(row.n)) console.log(row.n.properties.name);
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### Explain & Profile
|
|
67
|
-
|
|
68
|
-
`db.explain()` and `db.profile()` are first-class methods alongside
|
|
69
|
-
`db.execute()`. They are intentionally *separate calls*, not a flag
|
|
70
|
-
on `execute()`, so plan inspection and runtime metrics must be
|
|
71
|
-
requested explicitly.
|
|
72
|
-
|
|
73
|
-
```ts
|
|
74
|
-
const plan = await db.explain(
|
|
75
|
-
"MATCH (p:Person) WHERE p.name = $name RETURN p",
|
|
76
|
-
{ name: "Alice" },
|
|
77
|
-
);
|
|
78
|
-
console.log(plan.shape); // "readOnly"
|
|
79
|
-
console.log(plan.tree.operator);
|
|
80
|
-
|
|
81
|
-
const profile = await db.profile(
|
|
82
|
-
"MATCH (p:Person) WHERE p.name = $name RETURN p",
|
|
83
|
-
{ name: "Alice" },
|
|
84
|
-
);
|
|
85
|
-
console.log(profile.metrics.totalElapsedNs);
|
|
86
|
-
console.log(profile.metrics.perOperator); // per-step inclusive timing
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
`explain()` never invokes the executor — calling it on a mutating
|
|
90
|
-
query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
|
|
91
|
-
untouched.
|
|
92
|
-
|
|
93
|
-
> **`profile()` executes the query for real.** Mutating queries
|
|
94
|
-
> produce the same side effects as `execute()`. Use `explain()` to
|
|
95
|
-
> inspect a mutating plan without running it.
|
|
96
|
-
|
|
97
|
-
To force the in-process engine:
|
|
98
|
-
|
|
99
|
-
```ts
|
|
100
|
-
const db = await createDatabase({ runtime: "main-thread" });
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
To require Worker startup instead of falling back:
|
|
104
|
-
|
|
105
|
-
```ts
|
|
106
|
-
const db = await createDatabase({ runtime: "worker" });
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
To disable the fallback warning:
|
|
110
|
-
|
|
111
|
-
```ts
|
|
112
|
-
const db = await createDatabase({ warnOnFallback: false });
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
### 2. Explicit main-thread WASM
|
|
116
|
-
|
|
117
|
-
```ts
|
|
118
|
-
import { createMainThreadDatabase } from "@loradb/lora-wasm";
|
|
119
|
-
|
|
120
|
-
const db = await createMainThreadDatabase();
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
### 3. Custom Web Worker
|
|
124
|
-
|
|
125
|
-
Use this when you need to control the Worker URL, lifecycle, bundler entry, or
|
|
126
|
-
pooling strategy.
|
|
127
|
-
|
|
128
|
-
```ts
|
|
129
|
-
import { createWorkerDatabase } from "lora-wasm/worker-client";
|
|
130
|
-
|
|
131
|
-
const worker = new Worker(new URL("./worker.js", import.meta.url), {
|
|
132
|
-
type: "module",
|
|
133
|
-
});
|
|
134
|
-
const db = createWorkerDatabase(worker);
|
|
135
|
-
|
|
136
|
-
await db.execute("CREATE (:N {n: 1})"); // runs off-main-thread
|
|
137
|
-
const { rows } = await db.execute("MATCH (n) RETURN n.n AS n");
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
The worker entry (`ts/worker.ts`) hosts the WASM module. The main thread only
|
|
141
|
-
posts messages, so long-running queries never block the event loop / UI.
|
|
142
|
-
|
|
143
|
-
### 4. In-process but typed like the worker (advanced)
|
|
144
|
-
|
|
145
|
-
The same `createWorkerDatabase` signature accepts any `WorkerLike` object —
|
|
146
|
-
useful for tests and for swapping execution backends behind the same API.
|
|
147
|
-
|
|
148
|
-
## Snapshots
|
|
149
|
-
|
|
150
|
-
WASM has no filesystem access, so snapshots never accept string paths.
|
|
151
|
-
`saveSnapshot()` defaults to `Uint8Array`, and can also return `ArrayBuffer`,
|
|
152
|
-
`Blob`, `Response`, `ReadableStream`, or an object `URL`. `loadSnapshot`
|
|
153
|
-
accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, and web
|
|
154
|
-
`ReadableStream<Uint8Array | ArrayBuffer>`. The bytes use the database
|
|
155
|
-
snapshot codec (`LORACOL1`) and can be loaded by native LoraDB. Older store
|
|
156
|
-
snapshots use the current `LORACOL1` columnar format.
|
|
157
|
-
Snapshot bytes are uncompressed by default; pass `{ compression: "gzip" }` or
|
|
158
|
-
`{ compression: { format: "gzip", level: 1 } }` to save smaller
|
|
159
|
-
WASM-portable snapshots. Gzip levels `0..9` are supported; level `1` is the
|
|
160
|
-
fast default.
|
|
161
|
-
|
|
162
|
-
```ts
|
|
163
|
-
import { createDatabase } from "@loradb/lora-wasm";
|
|
164
|
-
|
|
165
|
-
const db = await createDatabase();
|
|
166
|
-
await db.execute("CREATE (:Person {name: 'Alice'})");
|
|
167
|
-
|
|
168
|
-
const bytes = await db.saveSnapshot();
|
|
169
|
-
const compressed = await db.saveSnapshot({ compression: "gzip" });
|
|
170
|
-
const blob = await db.saveSnapshot({ format: "blob", compression: "gzip" });
|
|
171
|
-
const response = await db.saveSnapshot({ format: "response" });
|
|
172
|
-
|
|
173
|
-
await db.loadSnapshot(bytes);
|
|
174
|
-
await db.loadSnapshot(compressed);
|
|
175
|
-
await db.loadSnapshot(blob);
|
|
176
|
-
await db.loadSnapshot(response);
|
|
177
|
-
await db.loadSnapshot(new URL("/graph.lorasnap", location.href));
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
## Typed value model
|
|
181
|
-
|
|
182
|
-
| TS type | Runtime shape |
|
|
183
|
-
|--------------------------------------|-----------------------------------------------------------------------------|
|
|
184
|
-
| `null`/`boolean`/`number`/`string` | pass-through |
|
|
185
|
-
| `LoraValue[]` / nested record | arrays / objects |
|
|
186
|
-
| `LoraNode` | `{ kind: "node", id, labels, properties }` |
|
|
187
|
-
| `LoraRelationship` | `{ kind: "relationship", id, startId, endId, type, properties }` |
|
|
188
|
-
| `LoraPath` | `{ kind: "path", nodes: number[], rels: number[] }` |
|
|
189
|
-
| `LoraDate`…`LoraDuration` | `{ kind: "date", iso: "YYYY-MM-DD" }` etc. |
|
|
190
|
-
| `LoraPoint` | Discriminated union on `srid` — see below |
|
|
191
|
-
|
|
192
|
-
`LoraPoint` is a union of four CRS-specific shapes:
|
|
193
|
-
|
|
194
|
-
| Shape | Meaning |
|
|
195
|
-
|---------------------------------------------------------------------------------------------------------|---------------|
|
|
196
|
-
| `{ kind: "point", srid: 7203, crs: "cartesian", x, y }` | Cartesian 2D |
|
|
197
|
-
| `{ kind: "point", srid: 9157, crs: "cartesian-3D", x, y, z }` | Cartesian 3D |
|
|
198
|
-
| `{ kind: "point", srid: 4326, crs: "WGS-84-2D", x, y, longitude, latitude }` | WGS-84 2D |
|
|
199
|
-
| `{ kind: "point", srid: 4979, crs: "WGS-84-3D", x, y, z, longitude, latitude, height }` | WGS-84 3D |
|
|
200
|
-
|
|
201
|
-
Helper constructors: `date`, `time`, `datetime`, `localtime`, `localdatetime`,
|
|
202
|
-
`duration`, `cartesian`, `cartesian3d`, `wgs84`, `wgs84_3d`. Guards:
|
|
203
|
-
`isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`.
|
|
204
|
-
|
|
205
|
-
> `distance()` on WGS-84-3D points ignores `height`. See
|
|
206
|
-
> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the spatial
|
|
207
|
-
> reference and out-of-scope operations.
|
|
208
|
-
|
|
209
|
-
## Errors
|
|
210
|
-
|
|
211
|
-
`db.execute(...)` and the worker client throw `LoraError` with a
|
|
212
|
-
narrowed `code` from the `LoraErrorCode` union — these mirror
|
|
213
|
-
`lora_database::LoraErrorCode` 1:1, plus `WORKER_ERROR` and `UNKNOWN`.
|
|
214
|
-
|
|
215
|
-
Common ones:
|
|
216
|
-
|
|
217
|
-
- `LORA_PARSE` — Cypher syntax could not be parsed
|
|
218
|
-
- `LORA_SEMANTIC` — analysis failure (unknown variable, label, type mismatch, …)
|
|
219
|
-
- `LORA_INVALID_PARAMS` — a parameter value could not be coerced to a `LoraValue`
|
|
220
|
-
- `LORA_INVALID_VECTOR` — vector value failed dimension / coordinate-type validation
|
|
221
|
-
- `LORA_TIMEOUT` — query exceeded its cooperative deadline
|
|
222
|
-
- `LORA_IO`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO` — storage / snapshot failures
|
|
223
|
-
- `LORA_INTERNAL` — last-resort fallback when the engine cannot classify the failure
|
|
224
|
-
- `WORKER_ERROR` — worker transport / lifecycle failure (worker client only)
|
|
225
|
-
|
|
226
|
-
See `ts/types.ts` (`LoraErrorCode`) for the full list.
|
|
227
|
-
|
|
228
|
-
## Shared type contract
|
|
229
|
-
|
|
230
|
-
The public TypeScript value model (`LoraValue`, `LoraNode`, …,
|
|
231
|
-
`QueryResult`, `LoraError`) lives in a single canonical file at
|
|
232
|
-
`crates/bindings/shared-ts/types.ts` and is copied into each consumer package by
|
|
233
|
-
its `sync:types` npm script. CI runs `verify:types` to fail on drift.
|
|
234
|
-
That keeps `lora-node` and `lora-wasm` locked to one identical
|
|
235
|
-
public surface — consumers can swap backends without rewriting types.
|
|
236
|
-
|
|
237
|
-
## Known limitations
|
|
238
|
-
|
|
239
|
-
- The wasm module runs inside one JavaScript runtime. Auto-commit reads can
|
|
240
|
-
overlap on engine snapshots; write commits serialize. Use more Workers for
|
|
241
|
-
separate graphs or stronger UI isolation.
|
|
242
|
-
- I64 values are delivered as JS `number` and lose precision above 2^53.
|
|
243
|
-
Applications that need bigint precision should use the native
|
|
244
|
-
`lora-node` binding instead.
|
|
245
|
-
- Wall-clock reads (`date()`, `datetime()`, `time()`, `localdatetime()`,
|
|
246
|
-
`localtime()`) are routed through `js_sys::Date::now()` on wasm32 via
|
|
247
|
-
the shim in `lora-store::temporal::unix_now`. The browser clock is
|
|
248
|
-
millisecond-granular, so the nanosecond field on returned values is
|
|
249
|
-
zero below the millisecond boundary.
|
|
250
|
-
- Engine errors cross the worker boundary as `LoraError` with a
|
|
251
|
-
narrowed `code`; the engine does not currently offer query cancellation.
|
|
252
|
-
|
|
253
|
-
## Feasibility assessment
|
|
254
|
-
|
|
255
|
-
**What works today**
|
|
256
|
-
|
|
257
|
-
- `cargo check --target wasm32-unknown-unknown` passes for the whole
|
|
258
|
-
database pipeline (`lora-ast`, `lora-parser`, `lora-analyzer`,
|
|
259
|
-
`lora-compiler`, `lora-executor`, `lora-store`,
|
|
260
|
-
`lora-database`, `lora-wasm`).
|
|
261
|
-
- `wasm-pack build` succeeds for three targets (`nodejs`, `bundler`,
|
|
262
|
-
`web`) with a ~2.2 MB optimised `.wasm` each.
|
|
263
|
-
- The non-blocking worker-backed path is end-to-end verified: a real
|
|
264
|
-
Chromium instance spawns a module Worker, loads the `pkg-web` bundle,
|
|
265
|
-
and runs a CREATE + MATCH round-trip — asserted by a Playwright test
|
|
266
|
-
behind `npm run test:browser`.
|
|
267
|
-
- `vitest` runs 18 in-process tests against the `nodejs` bundle,
|
|
268
|
-
covering scalars, nested maps/lists, nodes, relationships, paths,
|
|
269
|
-
points, all temporal kinds including `date()`/`datetime()` no-arg
|
|
270
|
-
forms, parameter validation errors, and concurrent queries across the
|
|
271
|
-
worker message protocol.
|
|
272
|
-
- The TypeScript public contract is shared verbatim with `lora-node`
|
|
273
|
-
via `crates/bindings/shared-ts/types.ts`, enforced by `verify:types` in CI.
|
|
274
|
-
- `npm pack --dry-run` produces a 45-file, 6.6 MB tarball containing
|
|
275
|
-
all three wasm bundles plus the compiled TS wrapper. No `file:` deps,
|
|
276
|
-
no postinstall scripts.
|
|
277
|
-
|
|
278
|
-
**What still blocks a real npm publish**
|
|
279
|
-
|
|
280
|
-
- Package is marked `private: true` and the workspace is pre-1.0.
|
|
281
|
-
Publishing needs a final scope decision (e.g. `@lora/wasm`),
|
|
282
|
-
a LICENSE file, and a repository URL in `Cargo.toml`/`package.json`.
|
|
283
|
-
- The three wasm bundles are each ~2.2 MB. A production publish should
|
|
284
|
-
either ship conditional exports that load only the bundle the
|
|
285
|
-
consumer imports, or switch to compressed `.wasm` + `fetch` with
|
|
286
|
-
`Content-Encoding: br`.
|
|
287
|
-
- I64 precision is capped at `Number.MAX_SAFE_INTEGER`. For larger
|
|
288
|
-
integer properties we need a `bigint`-aware serializer on the wasm
|
|
289
|
-
boundary.
|
|
290
|
-
- The engine is synchronous inside wasm once a call enters the module. A slow
|
|
291
|
-
query blocks that Worker until completion.
|
|
292
|
-
- No query cancellation or progress streaming crosses the Worker
|
|
293
|
-
boundary; a slow query blocks that Worker until completion.
|
|
294
|
-
|
|
295
|
-
**Bottom line**
|
|
296
|
-
|
|
297
|
-
Yes — this database can be used from JavaScript and TypeScript in
|
|
298
|
-
practice, in the browser and in Node, without native bindings. The
|
|
299
|
-
worker-backed path keeps heavy query work off the main thread by
|
|
300
|
-
default, and the strongly-typed wrapper makes query results ergonomic
|
|
301
|
-
for TS consumers. The remaining gaps are packaging polish and two
|
|
302
|
-
well-known wasm constraints (i64 precision, no cancellation); neither
|
|
303
|
-
blocks feasibility.
|
package/pkg-web/lora_wasm.d.ts
DELETED
|
@@ -1,138 +0,0 @@
|
|
|
1
|
-
/* tslint:disable */
|
|
2
|
-
/* eslint-disable */
|
|
3
|
-
/**
|
|
4
|
-
* Call once at module start to install a panic hook that routes Rust
|
|
5
|
-
* panics to `console.error`. No-op if compiled without the default feature.
|
|
6
|
-
*/
|
|
7
|
-
export function init(): void;
|
|
8
|
-
/**
|
|
9
|
-
* In-memory Lora graph database handle.
|
|
10
|
-
*/
|
|
11
|
-
export class WasmDatabase {
|
|
12
|
-
free(): void;
|
|
13
|
-
nodeCount(): number;
|
|
14
|
-
/**
|
|
15
|
-
* Open a true native row stream. Rows are pulled from the Rust executor
|
|
16
|
-
* one `next()` call at a time.
|
|
17
|
-
*/
|
|
18
|
-
openStream(query: string, params: any): WasmQueryStream;
|
|
19
|
-
/**
|
|
20
|
-
* Execute an array of `{ query, params? }` statements inside one native
|
|
21
|
-
* transaction. Returns an array of query results in statement order.
|
|
22
|
-
*/
|
|
23
|
-
transaction(statements: any, mode?: string | null): any;
|
|
24
|
-
/**
|
|
25
|
-
* Replace the graph state with a database snapshot decoded from `bytes`.
|
|
26
|
-
* Legacy store snapshot bytes are accepted for compatibility.
|
|
27
|
-
*
|
|
28
|
-
* Returns a plain object matching the shape of `SnapshotMeta`:
|
|
29
|
-
* `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
|
|
30
|
-
*/
|
|
31
|
-
loadSnapshot(bytes: Uint8Array, options: any): any;
|
|
32
|
-
/**
|
|
33
|
-
* Serialize the graph into database snapshot bytes. The caller is
|
|
34
|
-
* responsible for writing them to IndexedDB, localStorage, a server, or
|
|
35
|
-
* another host-provided store — WASM has no direct filesystem access.
|
|
36
|
-
* The returned bytes can later be passed to `loadSnapshot` on any
|
|
37
|
-
* `WasmDatabase` instance.
|
|
38
|
-
*
|
|
39
|
-
* Returns the serialized bytes as a `Uint8Array`.
|
|
40
|
-
*/
|
|
41
|
-
saveSnapshot(options: any): Uint8Array;
|
|
42
|
-
/**
|
|
43
|
-
* Execute a Lora query and return the result as a binary buffer.
|
|
44
|
-
*
|
|
45
|
-
* Wire format is the shared `lora_binding_buffer` layout. The TS
|
|
46
|
-
* wrapper decodes it once into the same `{ columns, rows }` shape
|
|
47
|
-
* `execute()` returns, but in a tight V8 loop instead of going
|
|
48
|
-
* through `serde_wasm_bindgen` value-by-value. Materially faster
|
|
49
|
-
* on bulk reads.
|
|
50
|
-
*/
|
|
51
|
-
executeBuffer(query: string, params: any): Uint8Array;
|
|
52
|
-
relationshipCount(): number;
|
|
53
|
-
constructor();
|
|
54
|
-
clear(): void;
|
|
55
|
-
/**
|
|
56
|
-
* Execute a Lora query. `params` may be `undefined`, `null`, or a
|
|
57
|
-
* plain object keyed by parameter name.
|
|
58
|
-
*
|
|
59
|
-
* Returns `{ columns: string[], rows: Array<Record<string, LoraValue>> }`
|
|
60
|
-
* as a plain JS object (structured-clonable).
|
|
61
|
-
*/
|
|
62
|
-
execute(query: string, params: any): any;
|
|
63
|
-
/**
|
|
64
|
-
* Compile a query and return its plan without executing it.
|
|
65
|
-
*
|
|
66
|
-
* Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
|
|
67
|
-
* the graph untouched — this method never runs the executor.
|
|
68
|
-
*/
|
|
69
|
-
explain(query: string, params: any): any;
|
|
70
|
-
/**
|
|
71
|
-
* Execute a query and return the plan plus runtime metrics.
|
|
72
|
-
*
|
|
73
|
-
* **PROFILE executes the query for real.** Mutating queries are
|
|
74
|
-
* persisted exactly as in `execute()`. Use `explain()` to inspect
|
|
75
|
-
* a mutating plan without running it.
|
|
76
|
-
*/
|
|
77
|
-
profile(query: string, params: any): any;
|
|
78
|
-
}
|
|
79
|
-
export class WasmQueryStream {
|
|
80
|
-
private constructor();
|
|
81
|
-
free(): void;
|
|
82
|
-
next(): any;
|
|
83
|
-
close(): void;
|
|
84
|
-
columns(): any;
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
|
|
88
|
-
|
|
89
|
-
export interface InitOutput {
|
|
90
|
-
readonly memory: WebAssembly.Memory;
|
|
91
|
-
readonly __wbg_wasmdatabase_free: (a: number, b: number) => void;
|
|
92
|
-
readonly __wbg_wasmquerystream_free: (a: number, b: number) => void;
|
|
93
|
-
readonly wasmdatabase_clear: (a: number) => void;
|
|
94
|
-
readonly wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
95
|
-
readonly wasmdatabase_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
|
|
96
|
-
readonly wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
97
|
-
readonly wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
98
|
-
readonly wasmdatabase_new: () => number;
|
|
99
|
-
readonly wasmdatabase_nodeCount: (a: number) => number;
|
|
100
|
-
readonly wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
101
|
-
readonly wasmdatabase_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
|
|
102
|
-
readonly wasmdatabase_relationshipCount: (a: number) => number;
|
|
103
|
-
readonly wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
|
|
104
|
-
readonly wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
|
|
105
|
-
readonly wasmquerystream_close: (a: number) => void;
|
|
106
|
-
readonly wasmquerystream_columns: (a: number) => [number, number, number];
|
|
107
|
-
readonly wasmquerystream_next: (a: number) => [number, number, number];
|
|
108
|
-
readonly init: () => void;
|
|
109
|
-
readonly __wbindgen_malloc: (a: number, b: number) => number;
|
|
110
|
-
readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
|
|
111
|
-
readonly __wbindgen_exn_store: (a: number) => void;
|
|
112
|
-
readonly __externref_table_alloc: () => number;
|
|
113
|
-
readonly __wbindgen_export_4: WebAssembly.Table;
|
|
114
|
-
readonly __wbindgen_free: (a: number, b: number, c: number) => void;
|
|
115
|
-
readonly __externref_table_dealloc: (a: number) => void;
|
|
116
|
-
readonly __wbindgen_start: () => void;
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
export type SyncInitInput = BufferSource | WebAssembly.Module;
|
|
120
|
-
/**
|
|
121
|
-
* Instantiates the given `module`, which can either be bytes or
|
|
122
|
-
* a precompiled `WebAssembly.Module`.
|
|
123
|
-
*
|
|
124
|
-
* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
|
|
125
|
-
*
|
|
126
|
-
* @returns {InitOutput}
|
|
127
|
-
*/
|
|
128
|
-
export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
|
|
129
|
-
|
|
130
|
-
/**
|
|
131
|
-
* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
|
|
132
|
-
* for everything else, calls `WebAssembly.instantiate` directly.
|
|
133
|
-
*
|
|
134
|
-
* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
|
|
135
|
-
*
|
|
136
|
-
* @returns {Promise<InitOutput>}
|
|
137
|
-
*/
|
|
138
|
-
export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
|