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 +21 -0
- package/README.md +71 -3
- package/dist/inillucent.wasm +0 -0
- package/package.json +49 -6
- package/src/engine.mjs +695 -0
- package/src/index.mjs +26 -0
- package/src/memory-fs.mjs +234 -0
- package/src/opfs-fs.mjs +399 -0
- package/src/wasi.mjs +547 -0
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
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|