inillucent-wasm 0.0.0-stage → 2.10.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jason McAffee
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,71 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # inillucent-wasm
2
+
3
+ The [inillucent](https://github.com/Black-Rainbow-Labs/Inillucent) embedded SQL database compiled to
4
+ WebAssembly, with the WASI host it needs to run in a browser or in Node. SQL, FTS5 full text search,
5
+ `VECTOR(N)` columns with HNSW indexes, and encryption, in one 6.6 MiB module (2.4 MiB compressed).
6
+
7
+ Most pages want [`inillucent-web`](https://www.npmjs.com/package/inillucent-web), the client built
8
+ on this package. It has `connect`, `query`, transactions, and `openPersistent` for a database the
9
+ browser keeps. This package is the layer under it, for a page that wants the engine's calls
10
+ directly.
11
+
12
+ ```sh
13
+ npm install inillucent-wasm
14
+ ```
15
+
16
+ ## Use
17
+
18
+ ```js
19
+ import { Engine } from 'inillucent-wasm';
20
+
21
+ const engine = await Engine.load(); // compiles dist/inillucent.wasm
22
+ const db = engine.open('/notes.rdb');
23
+ const conn = engine.connect(db);
24
+ engine.execute(conn, 'CREATE TABLE note (id INTEGER PRIMARY KEY, body TEXT)');
25
+ engine.execute(conn, 'INSERT INTO note (body) VALUES (?1)', ['hello']);
26
+ const result = engine.execute(conn, 'SELECT id, body FROM note');
27
+ // { columns: ['id', 'body'], rows: [[1, 'hello']], total: 1, more: false, affected: null, ... }
28
+ ```
29
+
30
+ `Engine.load({ wasm })` takes the module as a URL, bytes, a fetch `Response` or a compiled
31
+ `WebAssembly.Module`. A bundler that moves `dist/inillucent.wasm` needs to be told where it went:
32
+ `import wasm from 'inillucent-wasm/inillucent.wasm?url'` in Vite, for example.
33
+
34
+ Values come back as `null`, a number, a `BigInt` for an integer past 2^53, a string, or a
35
+ `Uint8Array`. A failure is an `InillucentError` with the driver's `statusName`, and a construct the
36
+ engine has not built is an `UnsupportedError` naming it.
37
+
38
+ ## Files
39
+
40
+ Every path the engine opens is resolved by the file system the engine was given:
41
+
42
+ | File system | Where the files are | Where it works |
43
+ |---|---|---|
44
+ | `MemoryFileSystem` (the default) | JavaScript memory; `exportFile(path)` and `importFile(path, bytes)` move a file in and out | anywhere |
45
+ | `OpfsFileSystem.open(name)` | the browser's origin private file system, one folder per name | a dedicated worker only |
46
+
47
+ `OpfsFileSystem` keeps a pool of OPFS files with their sync access handles open, because a handle
48
+ cannot be made while the engine is waiting for a file. Call `await fileSystem.refill()` between
49
+ requests to keep the pool full, and `fileSystem.close()` to let another worker open the database. A
50
+ second worker opening the same name while the first holds it gets a `DatabaseBusyError`.
51
+
52
+ ## When the instance stops
53
+
54
+ A statement that nests deeper than the JavaScript engine's call stack allows stops the instance, and
55
+ every later call throws `EngineStoppedError` with `reason: 'stack'`. The files are outside the
56
+ instance, so `Engine.load({ wasm: engine.module, fileSystem: engine.fs })` makes a new engine that
57
+ opens the database and recovers it. `inillucent-web` does this itself.
58
+
59
+ ## Build and test
60
+
61
+ From a checkout of the repository:
62
+
63
+ ```sh
64
+ rustup target add wasm32-wasip1
65
+ node packages/web/build.mjs
66
+ node --test packages/web/test/conformance.test.mjs packages/web/test/engine.test.mjs
67
+ npm --prefix packages/web install
68
+ node --test packages/web/test/browser/opfs.test.mjs
69
+ ```
70
+
71
+ [docs/web.md](../../docs/web.md) explains the design and what differs from the native library.
Binary file
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
- {
2
- "name": "inillucent-wasm",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "inillucent-wasm",
3
+ "version": "2.10.0",
4
+ "description": "The inillucent embedded SQL database compiled to WebAssembly, with the WASI host it needs in a browser or Node. Full text and vector search, in memory or kept in the browser's origin private file system.",
5
+ "keywords": [
6
+ "database",
7
+ "sql",
8
+ "sqlite",
9
+ "wasm",
10
+ "webassembly",
11
+ "browser",
12
+ "opfs",
13
+ "vector",
14
+ "search"
15
+ ],
16
+ "homepage": "https://github.com/Black-Rainbow-Labs/Inillucent/tree/main/packages/web#readme",
17
+ "bugs": "https://github.com/Black-Rainbow-Labs/Inillucent/issues",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/Black-Rainbow-Labs/Inillucent.git",
21
+ "directory": "packages/web"
22
+ },
23
+ "license": "MIT",
24
+ "author": "Black Rainbow Labs",
25
+ "type": "module",
26
+ "main": "./src/index.mjs",
27
+ "exports": {
28
+ ".": "./src/index.mjs",
29
+ "./inillucent.wasm": "./dist/inillucent.wasm"
30
+ },
31
+ "files": [
32
+ "src",
33
+ "dist/inillucent.wasm",
34
+ "README.md",
35
+ "LICENSE"
36
+ ],
37
+ "sideEffects": false,
38
+ "engines": {
39
+ "node": ">=20"
40
+ },
41
+ "scripts": {
42
+ "build": "node build.mjs",
43
+ "test": "node --test test/conformance.test.mjs test/engine.test.mjs",
44
+ "test:browser": "node --test test/browser/opfs.test.mjs"
45
+ },
46
+ "devDependencies": {
47
+ "playwright": "1.58.0"
48
+ }
49
+ }