plateaudb 0.0.0-stage → 0.2.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 +230 -2
- package/dist/backend.d.ts +8 -0
- package/dist/events.d.ts +70 -0
- package/dist/facade.d.ts +334 -0
- package/dist/fallback.d.ts +3 -0
- package/dist/host.worker.js +2355 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +3188 -0
- package/dist/key.d.ts +67 -0
- package/dist/plateau_engine_bg.wasm +0 -0
- package/dist/protocol.d.ts +246 -0
- package/dist/runtime.d.ts +129 -0
- package/dist/scheduler.d.ts +15 -0
- package/dist/value.d.ts +7 -0
- package/package.json +55 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 jagadhis
|
|
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,231 @@
|
|
|
1
|
-
#
|
|
1
|
+
# plateaudb
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A browser database with an IndexedDB-compatible API, stored in the Origin Private File System
|
|
4
|
+
(OPFS). The engine is written in Rust and compiled to WebAssembly, and runs in a dedicated worker.
|
|
5
|
+
It keeps a compressed bitmap of row ids for each value of a field you declare, so a query that
|
|
6
|
+
filters on several fields (`team = 7 AND state IN (1, 2) ORDER BY updatedAt DESC LIMIT 50`) costs
|
|
7
|
+
roughly the size of its result, not the size of the table.
|
|
8
|
+
|
|
9
|
+
Status: 0.2.0, pre-1.0. Read [Known limits](#known-limits) before you put data in it that you
|
|
10
|
+
cannot rebuild.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm install plateaudb
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The package ships an ES module, its worker as a separate file, and the `.wasm` engine. The code
|
|
19
|
+
names the worker and the WASM with `new URL("./…", import.meta.url)`, which bundlers follow and
|
|
20
|
+
copy into your build. Tested with no bundler config: Vite 8 (dev server and `vite build`) and
|
|
21
|
+
Next.js 16 (`next build` with Turbopack, and with `--webpack`). It needs no COOP/COEP headers: it
|
|
22
|
+
does not use `SharedArrayBuffer`.
|
|
23
|
+
|
|
24
|
+
esbuild on its own does not copy files named by `new URL(…)`: copy `host.worker.js` and
|
|
25
|
+
`plateau_engine_bg.wasm` from `node_modules/plateaudb/dist/` next to your bundle (not tested).
|
|
26
|
+
|
|
27
|
+
Use it from browser code only. In Next.js, import it in a client component (`"use client"`) and
|
|
28
|
+
open databases in an effect, not during server rendering.
|
|
29
|
+
|
|
30
|
+
## Use it
|
|
31
|
+
|
|
32
|
+
`plateau` is an `IDBFactory`. Code written for `indexedDB` takes it unchanged:
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
import { plateau, PlateauKeyRange, promise } from "plateaudb";
|
|
36
|
+
|
|
37
|
+
const indexedDB = plateau; // where your code used window.indexedDB
|
|
38
|
+
const IDBKeyRange = PlateauKeyRange; // and window.IDBKeyRange
|
|
39
|
+
|
|
40
|
+
const open = indexedDB.open("shop", 1);
|
|
41
|
+
open.onupgradeneeded = () => {
|
|
42
|
+
const store = open.result.createObjectStore("orders", { keyPath: "id" });
|
|
43
|
+
store.createIndex("byStatus", "status");
|
|
44
|
+
};
|
|
45
|
+
const db = await promise(open); // or open.onsuccess = ...
|
|
46
|
+
|
|
47
|
+
const tx = db.transaction("orders", "readwrite");
|
|
48
|
+
const orders = tx.objectStore("orders");
|
|
49
|
+
orders.put({ id: 1, status: "open", total: 40 });
|
|
50
|
+
orders.put({ id: 2, status: "shipped", total: 15 });
|
|
51
|
+
orders.put({ id: 3, status: "open", total: 22 });
|
|
52
|
+
|
|
53
|
+
const one = await promise(orders.get(1));
|
|
54
|
+
const openOrders = await promise(orders.index("byStatus").getAll("open"));
|
|
55
|
+
const cursor = orders.openCursor(IDBKeyRange.lowerBound(2));
|
|
56
|
+
cursor.onsuccess = () => {
|
|
57
|
+
const c = cursor.result;
|
|
58
|
+
if (c) { console.log(c.key, c.value); c.continue(); }
|
|
59
|
+
};
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Databases, object stores, indexes (unique and multiEntry), key ranges, cursors, transactions with
|
|
63
|
+
auto-commit, and the `upgradeneeded`, `versionchange`, `blocked`, `complete`, `abort`, `success` and
|
|
64
|
+
`error` events behave as IndexedDB's do. `promise(request)` is a small helper that resolves with
|
|
65
|
+
`request.result` or rejects with `request.error`.
|
|
66
|
+
|
|
67
|
+
## Multi-key queries: `store.query`
|
|
68
|
+
|
|
69
|
+
Declare the fields you filter or sort on as typed columns when you create the store, and query
|
|
70
|
+
them with `store.query`. Fields you do not declare are stored with the row. A store without
|
|
71
|
+
`columns` is a generic store and takes any value IndexedDB stores (see the limits below).
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
open.onupgradeneeded = () => {
|
|
75
|
+
open.result.createObjectStore("issues", {
|
|
76
|
+
keyPath: "id",
|
|
77
|
+
columns: {
|
|
78
|
+
id: "f64", // the primary key column must be f64
|
|
79
|
+
teamId: { kind: "u32", index: "bitmap" },
|
|
80
|
+
stateId: { kind: "u32", index: "bitmap" },
|
|
81
|
+
labelIds: { kind: "u32_multi", index: "bitmap" }, // matches if any element matches
|
|
82
|
+
updatedAt: { kind: "f64", index: "ordered", group: "teamId" },
|
|
83
|
+
title: "str",
|
|
84
|
+
},
|
|
85
|
+
});
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
const store = db.transaction("issues").objectStore("issues");
|
|
89
|
+
|
|
90
|
+
// the 50 most recently updated open issues of team 7
|
|
91
|
+
const latest = await promise(store.query({
|
|
92
|
+
where: [
|
|
93
|
+
{ field: "teamId", op: "eq", value: 7 },
|
|
94
|
+
{ field: "stateId", op: "in", values: [1, 2] },
|
|
95
|
+
],
|
|
96
|
+
orderBy: { field: "updatedAt", desc: true },
|
|
97
|
+
limit: 50,
|
|
98
|
+
}));
|
|
99
|
+
|
|
100
|
+
// how many changed in team 7 since weekAgo
|
|
101
|
+
const n = await promise(store.query({
|
|
102
|
+
where: [
|
|
103
|
+
{ field: "teamId", op: "eq", value: 7 },
|
|
104
|
+
{ field: "updatedAt", op: "range", gt: weekAgo },
|
|
105
|
+
],
|
|
106
|
+
count: true,
|
|
107
|
+
}));
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Filters are ANDed: `eq`, `in`, and `range` with `gt`, `gte`, `lt`, `lte`. Column kinds: `u32`
|
|
111
|
+
(ids, enums), `u32_multi` (a list of u32, such as labels), `f64` (numbers, timestamps) and `str`
|
|
112
|
+
(stored, not indexed). `bitmap` indexes go on `u32` and `u32_multi`; `ordered` goes on `f64`,
|
|
113
|
+
optionally grouped by a bitmap column so an ordered walk inside one group stays short.
|
|
114
|
+
|
|
115
|
+
## Several tabs
|
|
116
|
+
|
|
117
|
+
One tab of the origin, the leader, runs the worker and holds the files; the other tabs forward
|
|
118
|
+
their calls and transactions to it over `BroadcastChannel`, and Web Locks pick the leader. Your
|
|
119
|
+
code does not change: every tab uses the same API. `versionchange` and `blocked` reach every tab
|
|
120
|
+
with a connection, as they do natively.
|
|
121
|
+
|
|
122
|
+
When the leader tab closes, the next tab takes over and reconnects the others. Transactions the
|
|
123
|
+
old leader was running for other tabs abort with `UnknownError`; whatever they committed is on
|
|
124
|
+
disk. In the bundled live-sync example the new leader was streaming again 10-16 ms after the old
|
|
125
|
+
one closed (Chromium and WebKit).
|
|
126
|
+
|
|
127
|
+
plateau adds two calls for multi-tab apps:
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
await plateau.whenLeader(); // resolves when this tab is the leader, e.g. to hold one server stream
|
|
131
|
+
const stop = db.observe("orders", ({ stores }) => render()); // after a commit in any tab
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Where plateau cannot run: the IndexedDB fallback
|
|
135
|
+
|
|
136
|
+
Where the engine cannot run, `plateau` hands every call to the browser's own `indexedDB`, so code
|
|
137
|
+
written against it keeps working. It falls back when the browser has no OPFS
|
|
138
|
+
(`navigator.storage.getDirectory`), no `Worker` or no WebAssembly, or when the worker cannot start
|
|
139
|
+
the engine or open an OPFS sync access handle: a WebKit ephemeral session (Playwright's default
|
|
140
|
+
context) fails there with `UnknownError`, as do browsers without module workers,
|
|
141
|
+
`FileSystemSyncAccessHandle` or WebAssembly SIMD.
|
|
142
|
+
|
|
143
|
+
The backend is chosen once per page, at the first call that needs storage (`open`,
|
|
144
|
+
`deleteDatabase`, `databases`, `setMemoryBudget`, `memoryStats`), and never changes after that.
|
|
145
|
+
`open` still returns its request at once; the request fires its events when the choice is made.
|
|
146
|
+
|
|
147
|
+
```js
|
|
148
|
+
plateau.backend; // "opfs" or "indexeddb"; undefined before the choice
|
|
149
|
+
const backend = await plateau.chooseBackend(); // chooses now if no call has yet
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
To skip the check, start the runtime before the first call with the backend you want:
|
|
153
|
+
`startRuntime({ backend: "indexeddb" })` (always the browser's IndexedDB) or
|
|
154
|
+
`startRuntime({ backend: "opfs" })` (never fall back; opening fails where OPFS does). Every tab of
|
|
155
|
+
the origin should ask for the same one.
|
|
156
|
+
|
|
157
|
+
On the fallback:
|
|
158
|
+
|
|
159
|
+
- **Data is separate.** What one backend wrote is not visible on the other. A browser that gains
|
|
160
|
+
OPFS support later starts on an empty plateau database; the old data stays in its IndexedDB.
|
|
161
|
+
- The objects are the browser's own (`IDBDatabase`, `IDBObjectStore`, ...), with plateau's calls
|
|
162
|
+
added to them. `PlateauKeyRange` returns the browser's `IDBKeyRange`; create key ranges after the
|
|
163
|
+
first `open`, since a range made before the backend is chosen is plateau's own and the browser
|
|
164
|
+
does not take it.
|
|
165
|
+
- `createObjectStore(name, { columns })` works; the browser ignores `columns`, so a field of the
|
|
166
|
+
wrong kind is stored instead of throwing `DataError`.
|
|
167
|
+
- `store.query` returns what plateau's engine returns for the same records, read from the store
|
|
168
|
+
(an `eq` filter on a field with a `multiEntry` index reads only that index's records), so it
|
|
169
|
+
costs the size of the store, not of the result. It also runs on stores without `columns`;
|
|
170
|
+
`request.plan` is `scan` or `index:<name>`.
|
|
171
|
+
- `db.observe` calls back in every tab after a readwrite transaction that opened one of the
|
|
172
|
+
observed stores commits, whether or not it wrote to it.
|
|
173
|
+
- `db.compact()` and `plateau.setMemoryBudget()` do nothing; `plateau.memoryStats()` reports zeros
|
|
174
|
+
and the budget last set. `plateau.whenLeader()` works as on OPFS.
|
|
175
|
+
- `plateau.databases()` returns the browser's list.
|
|
176
|
+
|
|
177
|
+
## Memory budget
|
|
178
|
+
|
|
179
|
+
The worker keeps the parts of each file it has read in memory up to a budget, and drops the least
|
|
180
|
+
recently used ones between operations. The default is 64 MiB, or 24 MiB where
|
|
181
|
+
`navigator.deviceMemory` is 4 or less.
|
|
182
|
+
|
|
183
|
+
```js
|
|
184
|
+
await plateau.setMemoryBudget(32 * 1024 * 1024); // or null for no limit
|
|
185
|
+
const stats = await plateau.memoryStats("shop"); // WASM memory (its peak), budget, cached and file bytes
|
|
186
|
+
await db.compact(); // merge segments and reclaim deleted rows
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Measured at 1M rows: peak WASM memory 58.9 MiB with the default budget and 29.3 MiB with a 24 MiB
|
|
190
|
+
budget on a store with declared columns; 97.1 MiB and 45.4 MiB on a generic store. Random gets
|
|
191
|
+
are about 1.6x slower once the working set is larger than the budget. WASM memory never shrinks,
|
|
192
|
+
so `memoryStats` reports the peak.
|
|
193
|
+
|
|
194
|
+
## Browser support
|
|
195
|
+
|
|
196
|
+
Measured with Playwright on macOS: Chromium 158 and WebKit 27.2. Firefox is not measured
|
|
197
|
+
(Playwright's Firefox did not launch on the test machine), so treat it as unknown.
|
|
198
|
+
|
|
199
|
+
plateau's engine needs OPFS with `FileSystemSyncAccessHandle` in a dedicated worker, module
|
|
200
|
+
workers, and WebAssembly SIMD (Chrome 91+, Safari 16.4+, Firefox 89+ ship SIMD). Elsewhere it runs
|
|
201
|
+
on the browser's IndexedDB (see [the fallback](#where-plateau-cannot-run-the-indexeddb-fallback)).
|
|
202
|
+
|
|
203
|
+
In a WebKit ephemeral session (Playwright's default, non-persistent context) OPFS is not available,
|
|
204
|
+
so plateau runs on the fallback; with a persistent profile it runs on OPFS. Measured with
|
|
205
|
+
Playwright: on the fallback, 85 of 85 conformance tests pass in Chromium and WebKit, with OPFS,
|
|
206
|
+
`Worker` or WebAssembly removed, the WASM failing to compile, the worker failing to load, and in a
|
|
207
|
+
WebKit ephemeral context. Private browsing modes are not measured.
|
|
208
|
+
|
|
209
|
+
## Known limits
|
|
210
|
+
|
|
211
|
+
- **Conformance: 84 of 85** WPT-style IndexedDB tests pass in Chromium and WebKit on OPFS, against
|
|
212
|
+
85 of 85 for native IndexedDB. The one difference: a key stored as `-0` comes back as `0`. On the
|
|
213
|
+
IndexedDB fallback all 85 pass.
|
|
214
|
+
- **The fallback's data is separate** from OPFS data, and its `store.query` scans the store (see
|
|
215
|
+
[the fallback](#where-plateau-cannot-run-the-indexeddb-fallback)).
|
|
216
|
+
- **First open:** the page's first call waits for the worker to check that it can open an OPFS
|
|
217
|
+
file before the database opens: about 1 ms more to the first open on a fresh page (medians of
|
|
218
|
+
10 page loads: Chromium 10.2 ms against 9.6 ms without the check, WebKit 15.0 ms against 14.0 ms).
|
|
219
|
+
- **Values:** `Blob`, `File`, `ImageData` and `Error` values throw `DataCloneError`.
|
|
220
|
+
- `plateau.databases()` returns an empty list on OPFS.
|
|
221
|
+
- **Start-up:** the first query on a fresh page load costs more than native IndexedDB, because the
|
|
222
|
+
worker starts and the WASM compiles (measured through the API at 1M rows in Chromium: 8-13 ms
|
|
223
|
+
against native 4-5 ms). Reopening and warm queries are faster than native.
|
|
224
|
+
- **No RxDB adapter yet.**
|
|
225
|
+
- **Pre-1.0:** the API, the `columns` declaration and plateau's own calls may change between
|
|
226
|
+
minor versions. The file format may change too; plan to be able to rebuild local data from
|
|
227
|
+
your server.
|
|
228
|
+
|
|
229
|
+
## Licence
|
|
230
|
+
|
|
231
|
+
MIT. Source: https://github.com/jagadhis/plateaudb
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export type Backend = "opfs" | "indexeddb";
|
|
2
|
+
/** The browser's IndexedDB as it was when plateau loaded, before an app could replace it. */
|
|
3
|
+
export declare const nativeIndexedDB: IDBFactory | undefined;
|
|
4
|
+
/** The backend, once chosen. */
|
|
5
|
+
export declare function chosenBackend(): Backend | undefined;
|
|
6
|
+
/** Chooses the backend if no call has yet, and resolves with it. Synchronous when nothing needs a
|
|
7
|
+
* probe (a requested backend, or something missing on the main thread). */
|
|
8
|
+
export declare function chooseBackend(): Promise<Backend>;
|
package/dist/events.d.ts
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
export declare class PlateauEvent {
|
|
2
|
+
readonly type: string;
|
|
3
|
+
readonly bubbles: boolean;
|
|
4
|
+
readonly cancelable: boolean;
|
|
5
|
+
readonly isTrusted = true;
|
|
6
|
+
target: PlateauTarget | null;
|
|
7
|
+
currentTarget: PlateauTarget | null;
|
|
8
|
+
eventPhase: number;
|
|
9
|
+
defaultPrevented: boolean;
|
|
10
|
+
/** @internal */ stopped: boolean;
|
|
11
|
+
/** @internal */ stoppedNow: boolean;
|
|
12
|
+
constructor(type: string, init?: {
|
|
13
|
+
bubbles?: boolean;
|
|
14
|
+
cancelable?: boolean;
|
|
15
|
+
});
|
|
16
|
+
preventDefault(): void;
|
|
17
|
+
stopPropagation(): void;
|
|
18
|
+
stopImmediatePropagation(): void;
|
|
19
|
+
get timeStamp(): number;
|
|
20
|
+
get cancelBubble(): boolean;
|
|
21
|
+
get returnValue(): boolean;
|
|
22
|
+
}
|
|
23
|
+
export declare class PlateauVersionChangeEvent extends PlateauEvent {
|
|
24
|
+
readonly oldVersion: number;
|
|
25
|
+
readonly newVersion: number | null;
|
|
26
|
+
constructor(type: string, init?: {
|
|
27
|
+
oldVersion?: number;
|
|
28
|
+
newVersion?: number | null;
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
type Listener = ((e: any) => unknown) | {
|
|
32
|
+
handleEvent(e: any): unknown;
|
|
33
|
+
};
|
|
34
|
+
/** Outcome of a dispatch: whether a listener threw. */
|
|
35
|
+
export interface Dispatched {
|
|
36
|
+
threw: boolean;
|
|
37
|
+
}
|
|
38
|
+
export declare class PlateauTarget {
|
|
39
|
+
/** @internal */ private entries;
|
|
40
|
+
/** @internal */ private slots;
|
|
41
|
+
/** @internal The next target on the bubble path. */
|
|
42
|
+
parentTarget(): PlateauTarget | null;
|
|
43
|
+
addEventListener(type: string, fn: Listener | null, opts?: boolean | {
|
|
44
|
+
capture?: boolean;
|
|
45
|
+
once?: boolean;
|
|
46
|
+
}): void;
|
|
47
|
+
removeEventListener(type: string, fn: Listener | null, opts?: boolean | {
|
|
48
|
+
capture?: boolean;
|
|
49
|
+
}): void;
|
|
50
|
+
/** @internal Reads an `on<type>` handler. */
|
|
51
|
+
protected getHandler(type: string): ((e: any) => unknown) | null;
|
|
52
|
+
/** @internal Sets an `on<type>` handler; the first non-null value takes a place in the listener
|
|
53
|
+
* order, as the DOM's event handler attributes do. */
|
|
54
|
+
protected setHandler(type: string, fn: unknown): void;
|
|
55
|
+
/** @internal Whether anything listens here (for any event type). */
|
|
56
|
+
hasListeners(): boolean;
|
|
57
|
+
/** @internal Whether a listener for `type` would run here when an event passes on its way to a
|
|
58
|
+
* descendant: a capture listener, or any listener if the event bubbles. */
|
|
59
|
+
listensOnPath(type: string, bubbles: boolean): boolean;
|
|
60
|
+
dispatchEvent(e: PlateauEvent): boolean;
|
|
61
|
+
/** @internal */
|
|
62
|
+
invoke(e: PlateauEvent, phase: "capture" | "target" | "bubble", out: Dispatched): void;
|
|
63
|
+
}
|
|
64
|
+
/** Dispatches `e` at `target` along its parent path. */
|
|
65
|
+
export declare function dispatch(target: PlateauTarget, e: PlateauEvent): Dispatched;
|
|
66
|
+
/** Defines `on<type>` accessors on a target class. */
|
|
67
|
+
export declare function handlers(cls: {
|
|
68
|
+
prototype: PlateauTarget;
|
|
69
|
+
}, types: string[]): void;
|
|
70
|
+
export {};
|
package/dist/facade.d.ts
ADDED
|
@@ -0,0 +1,334 @@
|
|
|
1
|
+
import { type Backend } from "./backend";
|
|
2
|
+
import { PlateauEvent, PlateauTarget, PlateauVersionChangeEvent } from "./events";
|
|
3
|
+
import { PlateauKeyRange, type Key, type KeyPath, type WireRange } from "./key";
|
|
4
|
+
import type { CursorHit, Direction, IndexDef, MemoryStats, Op, PutRow, StoreDef, TxReply } from "./protocol";
|
|
5
|
+
export type StringList = string[] & {
|
|
6
|
+
contains(s: string): boolean;
|
|
7
|
+
item(i: number): string | null;
|
|
8
|
+
};
|
|
9
|
+
type ResultKind = "value" | "key" | "keys" | "values" | "count" | "none" | "cursor" | "query" | "records";
|
|
10
|
+
export declare class PlateauRequest extends PlateauTarget {
|
|
11
|
+
/** @internal */ _result: unknown;
|
|
12
|
+
/** @internal */ _error: DOMException | null;
|
|
13
|
+
/** @internal */ _done: boolean;
|
|
14
|
+
/** @internal */ kind: ResultKind;
|
|
15
|
+
/** @internal */ cursor: PlateauCursor | null;
|
|
16
|
+
source: unknown;
|
|
17
|
+
transaction: PlateauTransaction | null;
|
|
18
|
+
/** For `query`: the plan the engine chose. */
|
|
19
|
+
plan: string | undefined;
|
|
20
|
+
/** @internal A put's key when the caller gave it (the worker then answers nothing). */
|
|
21
|
+
known: unknown;
|
|
22
|
+
constructor(source: unknown, transaction: PlateauTransaction | null, kind: ResultKind);
|
|
23
|
+
get readyState(): "pending" | "done";
|
|
24
|
+
get result(): any;
|
|
25
|
+
get error(): DOMException | null;
|
|
26
|
+
/** @internal */
|
|
27
|
+
parentTarget(): PlateauTarget | null;
|
|
28
|
+
}
|
|
29
|
+
export interface PlateauRequest {
|
|
30
|
+
onsuccess: ((e: PlateauEvent) => unknown) | null;
|
|
31
|
+
onerror: ((e: PlateauEvent) => unknown) | null;
|
|
32
|
+
}
|
|
33
|
+
export declare class PlateauOpenDBRequest extends PlateauRequest {
|
|
34
|
+
constructor();
|
|
35
|
+
}
|
|
36
|
+
export interface PlateauOpenDBRequest {
|
|
37
|
+
onblocked: ((e: PlateauVersionChangeEvent) => unknown) | null;
|
|
38
|
+
onupgradeneeded: ((e: PlateauVersionChangeEvent) => unknown) | null;
|
|
39
|
+
}
|
|
40
|
+
/** A promise for a request's result. */
|
|
41
|
+
export declare function promise<T = any>(r: PlateauRequest): Promise<T>;
|
|
42
|
+
/** What `PlateauDatabase.observe` calls back with: the observed stores the transaction wrote. */
|
|
43
|
+
export interface PlateauChange {
|
|
44
|
+
stores: string[];
|
|
45
|
+
}
|
|
46
|
+
interface Observer {
|
|
47
|
+
stores: Set<string>;
|
|
48
|
+
callback: (change: PlateauChange) => void;
|
|
49
|
+
}
|
|
50
|
+
export declare class PlateauFactory {
|
|
51
|
+
/** Which backend runs this page's databases: `"opfs"` (plateau's engine) or `"indexeddb"` (the
|
|
52
|
+
* browser's own, where the engine cannot run); undefined until the first call that needs storage
|
|
53
|
+
* chooses it. It never changes after that. */
|
|
54
|
+
get backend(): Backend | undefined;
|
|
55
|
+
/** Chooses the backend now if no call has yet, and resolves with it. */
|
|
56
|
+
chooseBackend(): Promise<Backend>;
|
|
57
|
+
open(name: string, version?: number): PlateauOpenDBRequest;
|
|
58
|
+
deleteDatabase(name: string): PlateauOpenDBRequest;
|
|
59
|
+
/** @internal */
|
|
60
|
+
private deleteHere;
|
|
61
|
+
cmp(a: unknown, b: unknown): number;
|
|
62
|
+
/** On the IndexedDB fallback, the browser's list; plateau's engine does not list its databases yet
|
|
63
|
+
* and resolves with an empty list. */
|
|
64
|
+
databases(): Promise<{
|
|
65
|
+
name: string;
|
|
66
|
+
version: number;
|
|
67
|
+
}[]>;
|
|
68
|
+
/** plateau's own: resolves when this tab is the leader, the one tab of the origin that runs the
|
|
69
|
+
* worker (at once in a single tab, or when the leader closes and this tab takes over). Work that
|
|
70
|
+
* must run in one tab at a time, such as holding a server stream, waits on it. */
|
|
71
|
+
whenLeader(): Promise<void>;
|
|
72
|
+
/** plateau's own: sets the memory budget for the sections the runtime keeps loaded, in bytes
|
|
73
|
+
* (null for no limit). Past it, the least recently used are dropped between operations and read
|
|
74
|
+
* again when touched. The default is 64 MiB, or 24 MiB where `navigator.deviceMemory` is 4 or
|
|
75
|
+
* less. */
|
|
76
|
+
setMemoryBudget(bytes: number | null): Promise<void>;
|
|
77
|
+
/** plateau's own: the runtime's WASM memory (its peak: WASM memory never shrinks), the budget,
|
|
78
|
+
* the bytes loaded sections hold, and the file sizes of database `name` if it is open. On the
|
|
79
|
+
* IndexedDB fallback there is no engine: zeros, and the budget last set. */
|
|
80
|
+
memoryStats(name?: string): Promise<MemoryStats>;
|
|
81
|
+
}
|
|
82
|
+
export declare class PlateauDatabase extends PlateauTarget {
|
|
83
|
+
readonly name: string;
|
|
84
|
+
/** @internal */ _version: number;
|
|
85
|
+
/** @internal */ _stores: Map<string, StoreDef>;
|
|
86
|
+
/** @internal */ _nextId: number;
|
|
87
|
+
/** @internal */ _upgrade: PlateauTransaction | null;
|
|
88
|
+
/** @internal */ _txs: Set<PlateauTransaction>;
|
|
89
|
+
/** @internal */ _closePending: boolean;
|
|
90
|
+
/** @internal */ _observers: Set<Observer>;
|
|
91
|
+
/** @internal */ _closed: boolean;
|
|
92
|
+
/** @internal */ _closedPromise: Promise<void>;
|
|
93
|
+
/** @internal */ private markClosed;
|
|
94
|
+
constructor(name: string, version: number, nextId: number, stores: StoreDef[]);
|
|
95
|
+
get version(): number;
|
|
96
|
+
get objectStoreNames(): StringList;
|
|
97
|
+
/** @internal */
|
|
98
|
+
upgradeTx(): PlateauTransaction;
|
|
99
|
+
createObjectStore(name: string, options?: {
|
|
100
|
+
keyPath?: KeyPath | null;
|
|
101
|
+
autoIncrement?: boolean;
|
|
102
|
+
columns?: unknown;
|
|
103
|
+
}): PlateauObjectStore;
|
|
104
|
+
deleteObjectStore(name: string): void;
|
|
105
|
+
transaction(names: string | Iterable<string>, mode?: IDBTransactionMode, options?: {
|
|
106
|
+
durability?: string;
|
|
107
|
+
}): PlateauTransaction;
|
|
108
|
+
close(): void;
|
|
109
|
+
/** plateau's own: calls `callback` after each readwrite transaction that wrote one of `stores`
|
|
110
|
+
* commits, in this tab or any other tab of the origin, with the observed stores it wrote. Reads
|
|
111
|
+
* started in the callback see that commit. Returns a function that stops the calls; closing the
|
|
112
|
+
* connection stops them too. */
|
|
113
|
+
observe(stores: string | Iterable<string>, callback: (change: PlateauChange) => void): () => void;
|
|
114
|
+
/** plateau's own: rewrites every object store's file without its deleted and replaced rows,
|
|
115
|
+
* into free space where it fits, and cuts the file's free tail. Waits for this connection's
|
|
116
|
+
* running transactions to finish first; rejects with InvalidStateError if the connection is
|
|
117
|
+
* closing or another connection's readwrite transaction is running. */
|
|
118
|
+
compact(): Promise<void>;
|
|
119
|
+
/** @internal */
|
|
120
|
+
_closeNow(): void;
|
|
121
|
+
/** @internal */
|
|
122
|
+
_maybeClosed(): void;
|
|
123
|
+
}
|
|
124
|
+
export interface PlateauDatabase {
|
|
125
|
+
onabort: ((e: PlateauEvent) => unknown) | null;
|
|
126
|
+
onclose: ((e: PlateauEvent) => unknown) | null;
|
|
127
|
+
onerror: ((e: PlateauEvent) => unknown) | null;
|
|
128
|
+
onversionchange: ((e: PlateauVersionChangeEvent) => unknown) | null;
|
|
129
|
+
}
|
|
130
|
+
type Pending = PlateauRequest | null;
|
|
131
|
+
export declare class PlateauTransaction extends PlateauTarget {
|
|
132
|
+
readonly db: PlateauDatabase;
|
|
133
|
+
readonly mode: IDBTransactionMode;
|
|
134
|
+
durability: string;
|
|
135
|
+
/** @internal */ _scope: string[];
|
|
136
|
+
/** @internal */ _state: "active" | "inactive" | "committing" | "finished";
|
|
137
|
+
/** @internal */ _started: boolean;
|
|
138
|
+
/** @internal */ _aborted: boolean;
|
|
139
|
+
/** @internal */ _error: DOMException | null;
|
|
140
|
+
/** @internal */ _handles: Map<string, PlateauObjectStore>;
|
|
141
|
+
/** @internal Made on first ask: most transactions are never awaited this way. */ private finished;
|
|
142
|
+
/** @internal */ private markFinished;
|
|
143
|
+
/** @internal */ private isFinished;
|
|
144
|
+
/** @internal */ private id;
|
|
145
|
+
/** @internal */ private version;
|
|
146
|
+
/** @internal */ private began;
|
|
147
|
+
/** @internal */ private unsent;
|
|
148
|
+
/** @internal */ private unsentReqs;
|
|
149
|
+
/** @internal Requests sent and not answered, from `head` on. */ private inflight;
|
|
150
|
+
/** @internal */ private head;
|
|
151
|
+
/** @internal */ private flushQueued;
|
|
152
|
+
/** @internal */ private settleQueued;
|
|
153
|
+
/** @internal */ private commitSent;
|
|
154
|
+
/** @internal */ private beforeUpgrade;
|
|
155
|
+
/** @internal */ private nextIdBefore;
|
|
156
|
+
/** @internal Stores a readwrite transaction wrote, for observers. */ private written;
|
|
157
|
+
constructor(db: PlateauDatabase, scope: string[], mode: IDBTransactionMode, version?: number);
|
|
158
|
+
get objectStoreNames(): StringList;
|
|
159
|
+
get error(): DOMException | null;
|
|
160
|
+
/** Resolves on complete, rejects on abort. */
|
|
161
|
+
get done(): Promise<void>;
|
|
162
|
+
/** @internal */
|
|
163
|
+
parentTarget(): PlateauTarget | null;
|
|
164
|
+
/** @internal Resolves once the transaction has finished (complete or abort). */
|
|
165
|
+
_finishedPromise(): Promise<void>;
|
|
166
|
+
objectStore(name: string): PlateauObjectStore;
|
|
167
|
+
abort(): void;
|
|
168
|
+
commit(): void;
|
|
169
|
+
/** @internal Checks a request can be made now. */
|
|
170
|
+
_check(write: boolean): void;
|
|
171
|
+
/** @internal Queues an operation and the requests its results go to. */
|
|
172
|
+
_issue(op: Op, req: Pending): void;
|
|
173
|
+
/** @internal Queues a point get, joining the previous point gets of the same store. */
|
|
174
|
+
_issueGet(s: string, key: string, req: PlateauRequest): void;
|
|
175
|
+
/** @internal Queues a put, joining the previous puts of the same store. */
|
|
176
|
+
_issuePut(s: string, row: PutRow, req: PlateauRequest): void;
|
|
177
|
+
/** @internal Queues a put into a typed store, joining the previous ones of the same store as
|
|
178
|
+
* columns. */
|
|
179
|
+
_issueTyped(def: StoreDef, t: unknown[], rest: string, add: boolean, gen: boolean, req: PlateauRequest): void;
|
|
180
|
+
/** @internal Queues a delete of one number key of a typed store, joining the previous ones. */
|
|
181
|
+
_issueDeleteNumber(s: string, key: number, req: PlateauRequest): void;
|
|
182
|
+
/** @internal Queues a delete of one key, joining the previous ones of the same store. */
|
|
183
|
+
_issueDelete(s: string, key: string, req: PlateauRequest): void;
|
|
184
|
+
private queued;
|
|
185
|
+
/** @internal Cursor steps answered from prefetched entries, waiting for their microtask. */
|
|
186
|
+
private local;
|
|
187
|
+
/** @internal Answers a cursor step from what the cursor prefetched, as a worker reply would. */
|
|
188
|
+
_local(req: PlateauRequest, hit: CursorHit | null): void;
|
|
189
|
+
/** @internal A schema operation of an upgrade: no request, but its failure aborts. */
|
|
190
|
+
_internal(op: Op): void;
|
|
191
|
+
/** @internal Called by the scheduler. */
|
|
192
|
+
_start(): void;
|
|
193
|
+
/** @internal Ends the active period at the end of the current task. */
|
|
194
|
+
_settleSoon(): void;
|
|
195
|
+
private message;
|
|
196
|
+
private flush;
|
|
197
|
+
/** Commits when nothing more can be asked. */
|
|
198
|
+
private settle;
|
|
199
|
+
/** Whether no pending request has a listener. */
|
|
200
|
+
private quiet;
|
|
201
|
+
/** @internal */
|
|
202
|
+
_onReply(r: TxReply): void;
|
|
203
|
+
private deliver;
|
|
204
|
+
private deliverError;
|
|
205
|
+
private complete;
|
|
206
|
+
private finish;
|
|
207
|
+
/** @internal */
|
|
208
|
+
_abort(error: DOMException | null): void;
|
|
209
|
+
}
|
|
210
|
+
export interface PlateauTransaction {
|
|
211
|
+
onabort: ((e: PlateauEvent) => unknown) | null;
|
|
212
|
+
oncomplete: ((e: PlateauEvent) => unknown) | null;
|
|
213
|
+
onerror: ((e: PlateauEvent) => unknown) | null;
|
|
214
|
+
}
|
|
215
|
+
export declare class PlateauObjectStore {
|
|
216
|
+
/** @internal */ readonly _tx: PlateauTransaction;
|
|
217
|
+
/** @internal */ readonly _def: StoreDef;
|
|
218
|
+
/** @internal */ private indexHandles;
|
|
219
|
+
/** @internal */ private keyPathValue;
|
|
220
|
+
constructor(tx: PlateauTransaction, def: StoreDef);
|
|
221
|
+
get name(): string;
|
|
222
|
+
get keyPath(): KeyPath | null;
|
|
223
|
+
get autoIncrement(): boolean;
|
|
224
|
+
get indexNames(): StringList;
|
|
225
|
+
get transaction(): PlateauTransaction;
|
|
226
|
+
/** @internal */
|
|
227
|
+
_live(): void;
|
|
228
|
+
/** @internal Checks for a request: store alive, transaction active, writable if asked. */
|
|
229
|
+
_ready(write: boolean): void;
|
|
230
|
+
put(value: unknown, key?: unknown): PlateauRequest;
|
|
231
|
+
add(value: unknown, key?: unknown): PlateauRequest;
|
|
232
|
+
/** @internal */
|
|
233
|
+
store(value: unknown, key: unknown, add: boolean, keyGiven: boolean, source?: unknown): PlateauRequest;
|
|
234
|
+
delete(query: unknown): PlateauRequest;
|
|
235
|
+
clear(): PlateauRequest;
|
|
236
|
+
get(query: unknown): PlateauRequest;
|
|
237
|
+
getKey(query: unknown): PlateauRequest;
|
|
238
|
+
getAll(query?: unknown, n?: unknown): PlateauRequest;
|
|
239
|
+
getAllKeys(query?: unknown, n?: unknown): PlateauRequest;
|
|
240
|
+
count(query?: unknown): PlateauRequest;
|
|
241
|
+
/** IndexedDB's getAllRecords: up to `count` records ({key, primaryKey, value}) in `direction`. */
|
|
242
|
+
getAllRecords(o?: {
|
|
243
|
+
query?: unknown;
|
|
244
|
+
count?: number;
|
|
245
|
+
direction?: IDBCursorDirection;
|
|
246
|
+
}): PlateauRequest;
|
|
247
|
+
openCursor(query?: unknown, dir?: IDBCursorDirection): PlateauRequest;
|
|
248
|
+
openKeyCursor(query?: unknown, dir?: IDBCursorDirection): PlateauRequest;
|
|
249
|
+
/** plateau's multi-key query on declared columns: `{where, orderBy, limit, count}`. The result is
|
|
250
|
+
* the matching values, or a number with `count: true`; `request.plan` names the plan. */
|
|
251
|
+
query(q: {
|
|
252
|
+
where?: unknown[];
|
|
253
|
+
orderBy?: {
|
|
254
|
+
field: string;
|
|
255
|
+
desc?: boolean;
|
|
256
|
+
};
|
|
257
|
+
limit?: number;
|
|
258
|
+
count?: boolean;
|
|
259
|
+
}): PlateauRequest;
|
|
260
|
+
/** @internal */
|
|
261
|
+
private cursor;
|
|
262
|
+
/** @internal */
|
|
263
|
+
request(op: Op, kind: ResultKind): PlateauRequest;
|
|
264
|
+
index(name: string): PlateauIndex;
|
|
265
|
+
createIndex(name: string, keyPath: KeyPath, options?: {
|
|
266
|
+
unique?: boolean;
|
|
267
|
+
multiEntry?: boolean;
|
|
268
|
+
}): PlateauIndex;
|
|
269
|
+
deleteIndex(name: string): void;
|
|
270
|
+
}
|
|
271
|
+
export declare class PlateauIndex {
|
|
272
|
+
readonly objectStore: PlateauObjectStore;
|
|
273
|
+
/** @internal */ readonly _def: IndexDef;
|
|
274
|
+
/** @internal */ private keyPathValue;
|
|
275
|
+
constructor(store: PlateauObjectStore, def: IndexDef);
|
|
276
|
+
get name(): string;
|
|
277
|
+
get keyPath(): KeyPath;
|
|
278
|
+
get unique(): boolean;
|
|
279
|
+
get multiEntry(): boolean;
|
|
280
|
+
/** @internal */
|
|
281
|
+
_live(): void;
|
|
282
|
+
/** @internal */
|
|
283
|
+
_ready(): void;
|
|
284
|
+
private request;
|
|
285
|
+
private get s();
|
|
286
|
+
get(query: unknown): PlateauRequest;
|
|
287
|
+
getKey(query: unknown): PlateauRequest;
|
|
288
|
+
getAll(query?: unknown, n?: unknown): PlateauRequest;
|
|
289
|
+
getAllKeys(query?: unknown, n?: unknown): PlateauRequest;
|
|
290
|
+
count(query?: unknown): PlateauRequest;
|
|
291
|
+
/** IndexedDB's getAllRecords: up to `count` records ({key, primaryKey, value}) in `direction`. */
|
|
292
|
+
getAllRecords(o?: {
|
|
293
|
+
query?: unknown;
|
|
294
|
+
count?: number;
|
|
295
|
+
direction?: IDBCursorDirection;
|
|
296
|
+
}): PlateauRequest;
|
|
297
|
+
openCursor(query?: unknown, dir?: IDBCursorDirection): PlateauRequest;
|
|
298
|
+
openKeyCursor(query?: unknown, dir?: IDBCursorDirection): PlateauRequest;
|
|
299
|
+
private cursor;
|
|
300
|
+
}
|
|
301
|
+
export declare class PlateauCursor {
|
|
302
|
+
readonly request: PlateauRequest;
|
|
303
|
+
readonly source: PlateauObjectStore | PlateauIndex;
|
|
304
|
+
readonly direction: Direction;
|
|
305
|
+
/** @internal */ private store;
|
|
306
|
+
/** @internal */ private index;
|
|
307
|
+
/** @internal */ private range;
|
|
308
|
+
/** @internal */ private withValues;
|
|
309
|
+
/** @internal */ private at;
|
|
310
|
+
/** @internal */ private gotValue;
|
|
311
|
+
/** @internal */ private keyValue;
|
|
312
|
+
/** @internal */ private pkValue;
|
|
313
|
+
/** @internal */ _value: unknown;
|
|
314
|
+
/** @internal Prefetched next steps, and whether the range ends after them. */ private ahead;
|
|
315
|
+
/** @internal */ private aheadEnd;
|
|
316
|
+
constructor(req: PlateauRequest, source: PlateauObjectStore | PlateauIndex, store: PlateauObjectStore, index: string | undefined, range: WireRange | null, dir: Direction, values: boolean);
|
|
317
|
+
get key(): Key | undefined;
|
|
318
|
+
get primaryKey(): Key | undefined;
|
|
319
|
+
/** @internal Requests the next step. */
|
|
320
|
+
_step(to: [string, string?] | undefined, n: number): void;
|
|
321
|
+
/** @internal A step's answer arrived; the request's result. */
|
|
322
|
+
_land(hit: CursorHit | null): PlateauCursor | null;
|
|
323
|
+
/** @internal */
|
|
324
|
+
private ready;
|
|
325
|
+
advance(count: number): void;
|
|
326
|
+
continue(key?: unknown): void;
|
|
327
|
+
continuePrimaryKey(key: unknown, primaryKey: unknown): void;
|
|
328
|
+
update(value: unknown): PlateauRequest;
|
|
329
|
+
delete(): PlateauRequest;
|
|
330
|
+
}
|
|
331
|
+
export declare class PlateauCursorWithValue extends PlateauCursor {
|
|
332
|
+
}
|
|
333
|
+
export declare const plateau: PlateauFactory;
|
|
334
|
+
export { PlateauKeyRange };
|