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/dist/key.d.ts ADDED
@@ -0,0 +1,67 @@
1
+ export type Key = number | string | Date | ArrayBuffer | Key[];
2
+ /** The sortable encoding of `v` if it is a valid key, else `undefined`. */
3
+ export declare function encodeKey(v: unknown): string | undefined;
4
+ /** Where the key encoded at `at` ends. */
5
+ export declare function skipKey(s: string, at: number): number;
6
+ /** The key (as IndexedDB hands keys out: numbers, Dates, strings, ArrayBuffers, arrays) encoded
7
+ * at `at`, and where its encoding ends. */
8
+ export declare function decodeKeyAt(s: string, at: number): [Key, number];
9
+ export declare function decodeKey(s: string): Key;
10
+ /** The number an encoded number key holds, or `undefined` for another key type. */
11
+ export declare function encodedNumber(s: string): number | undefined;
12
+ export declare function encodeNumberKey(n: number): string;
13
+ export declare function dataError(message: string): DOMException;
14
+ /** The encoding of `v`, or a DataError. */
15
+ export declare function requireKey(v: unknown, what?: string): string;
16
+ /** `indexedDB.cmp`: -1, 0 or 1. */
17
+ export declare function cmp(a: unknown, b: unknown): number;
18
+ export type KeyPath = string | string[];
19
+ export declare function validKeyPath(p: unknown): p is KeyPath;
20
+ /** A key path given as any sequence (an array or a DOMStringList-like) or any value converted to a
21
+ * string, as WebIDL does for `(DOMString or sequence<DOMString>)`. */
22
+ export declare function normalizeKeyPath(p: unknown): unknown;
23
+ /** What evaluating a key path on a value gives: `{ key }` (the encoding of a valid key), `"invalid"`
24
+ * (a value that is not a key) or `"missing"` (no value at the path). An array key path gives an
25
+ * array key, or `"invalid"` if any part is missing or invalid. */
26
+ export declare function extractKey(value: unknown, path: KeyPath): {
27
+ key: string;
28
+ } | "invalid" | "missing";
29
+ /** The keys an index with this key path holds for a record: none, one, or (multiEntry over an
30
+ * array value) each distinct valid element. */
31
+ export declare function indexKeys(value: unknown, path: KeyPath, multiEntry: boolean): string[];
32
+ /** Whether a generated key could be put at `path` in `value` (every step before the last is an
33
+ * object or absent). */
34
+ export declare function canInjectKey(value: unknown, path: string): boolean;
35
+ /** Puts `key` at `path` in `value`, creating the objects on the way. */
36
+ export declare function injectKey(value: unknown, path: string, key: Key): void;
37
+ /** A key range as the worker takes it: encoded bounds, `undefined` for unbounded. */
38
+ export interface WireRange {
39
+ lo?: string;
40
+ hi?: string;
41
+ loOpen: boolean;
42
+ hiOpen: boolean;
43
+ }
44
+ /** @internal From now on `PlateauKeyRange`'s factories return the browser's `IDBKeyRange`: the page
45
+ * runs on the browser's IndexedDB, which takes no other range. */
46
+ export declare function useNativeKeyRanges(): void;
47
+ /** On the IndexedDB fallback, the factories return the browser's own `IDBKeyRange`. */
48
+ export declare class PlateauKeyRange {
49
+ /** @internal */ readonly lo: string | undefined;
50
+ /** @internal */ readonly hi: string | undefined;
51
+ readonly lowerOpen: boolean;
52
+ readonly upperOpen: boolean;
53
+ private constructor();
54
+ get lower(): Key | undefined;
55
+ get upper(): Key | undefined;
56
+ static only(value: unknown): PlateauKeyRange;
57
+ static lowerBound(lower: unknown, open?: boolean): PlateauKeyRange;
58
+ static upperBound(upper: unknown, open?: boolean): PlateauKeyRange;
59
+ static bound(lower: unknown, upper: unknown, lowerOpen?: boolean, upperOpen?: boolean): PlateauKeyRange;
60
+ includes(key: unknown): boolean;
61
+ /** @internal */
62
+ wire(): WireRange;
63
+ }
64
+ export declare function inRange(r: WireRange, k: string): boolean;
65
+ /** Converts a query argument (a key, a key range or, where allowed, nothing) to a wire range.
66
+ * Accepts native `IDBKeyRange` objects too. */
67
+ export declare function toRange(q: unknown, nullOk: boolean): WireRange | null;
Binary file
@@ -0,0 +1,246 @@
1
+ import type { KeyPath, WireRange } from "./key";
2
+ export type ColumnKind = "u32" | "u32_multi" | "f64" | "str";
3
+ /** A field the app declares on a store (plateau's `columns` option): stored as a typed engine
4
+ * column, with the engine's bitmap or ordered index if asked. */
5
+ export interface ColumnDecl {
6
+ name: string;
7
+ kind: ColumnKind;
8
+ index?: "bitmap" | "ordered";
9
+ group?: string;
10
+ }
11
+ export interface IndexDef {
12
+ /** Unique within the database; names the index's engine column (`_i<id>`). */
13
+ id: number;
14
+ name: string;
15
+ keyPath: KeyPath;
16
+ unique: boolean;
17
+ multiEntry: boolean;
18
+ }
19
+ export interface StoreDef {
20
+ /** Unique within the database for its life; names the store's file. */
21
+ id: number;
22
+ /** The store's engine file; a new one when an index is created or deleted on a store. */
23
+ file: string;
24
+ name: string;
25
+ keyPath: KeyPath | null;
26
+ autoIncrement: boolean;
27
+ indexes: IndexDef[];
28
+ /** Declared typed fields; when present the store's key path is one of them, an f64 column, and
29
+ * the engine's primary key. */
30
+ columns?: ColumnDecl[];
31
+ }
32
+ export interface Catalog {
33
+ version: number;
34
+ nextId: number;
35
+ stores: StoreDef[];
36
+ }
37
+ export type Direction = "next" | "nextunique" | "prev" | "prevunique";
38
+ /** One operation of a transaction. Each yields one result per request it carries. */
39
+ export type Op =
40
+ /** Point gets of a store by encoded key; one result per key. */
41
+ {
42
+ o: "get";
43
+ s: string;
44
+ ks: string[];
45
+ }
46
+ /** First record (or key) in a range, of a store or an index. */
47
+ | {
48
+ o: "first";
49
+ s: string;
50
+ i?: string;
51
+ r: WireRange;
52
+ key: boolean;
53
+ } | {
54
+ o: "all";
55
+ s: string;
56
+ i?: string;
57
+ r: WireRange | null;
58
+ n: number;
59
+ key: boolean;
60
+ } | {
61
+ o: "count";
62
+ s: string;
63
+ i?: string;
64
+ r: WireRange | null;
65
+ }
66
+ /** Puts; one result per row (its encoded key). `t` holds a typed store's declared fields in
67
+ * column order; `v` the stored form of the rest of the value (or of the whole value). */
68
+ | {
69
+ o: "put";
70
+ s: string;
71
+ rows: PutRow[];
72
+ }
73
+ /** Puts into a typed store, as columns: per declared column a Float64Array (f64), Uint32Array
74
+ * (u32), string array (str) or [offsets, values] Uint32Arrays (u32_multi); `v` the stored rests
75
+ * (null when all are empty); `add` the rows that must not overwrite, `gen` the rows whose key the
76
+ * store generates. One result per row: the generated key, else nothing. */
77
+ | {
78
+ o: "tput";
79
+ s: string;
80
+ n: number;
81
+ cols: unknown[];
82
+ v: string[] | null;
83
+ add: number[];
84
+ gen: number[];
85
+ } | {
86
+ o: "del";
87
+ s: string;
88
+ r: WireRange;
89
+ }
90
+ /** Deletes of single keys; one result per key. */
91
+ | {
92
+ o: "delk";
93
+ s: string;
94
+ ks: string[];
95
+ nums?: number[];
96
+ } | {
97
+ o: "clear";
98
+ s: string;
99
+ }
100
+ /** A cursor step; with `pre`, up to that many following entries come along (`more`). */
101
+ | {
102
+ o: "cur";
103
+ s: string;
104
+ i?: string;
105
+ r: WireRange | null;
106
+ d: Direction;
107
+ at?: [string, string];
108
+ to?: [string, string?];
109
+ n: number;
110
+ v: boolean;
111
+ pre?: number;
112
+ }
113
+ /** getAllRecords: up to `n` records (key, primary key, value) in direction `d`. */
114
+ | {
115
+ o: "recs";
116
+ s: string;
117
+ i?: string;
118
+ r: WireRange | null;
119
+ n: number;
120
+ d: Direction;
121
+ } | {
122
+ o: "query";
123
+ s: string;
124
+ q: string;
125
+ } | {
126
+ o: "mkStore";
127
+ def: StoreDef;
128
+ } | {
129
+ o: "rmStore";
130
+ s: string;
131
+ } | {
132
+ o: "mkIndex";
133
+ s: string;
134
+ def: IndexDef;
135
+ } | {
136
+ o: "rmIndex";
137
+ s: string;
138
+ i: string;
139
+ };
140
+ export interface PutRow {
141
+ k?: string;
142
+ v: string;
143
+ t?: unknown[];
144
+ add: boolean;
145
+ }
146
+ /** A cursor step's answer: encoded key, encoded primary key, value if asked. */
147
+ export interface CursorHit {
148
+ k: string;
149
+ p: string;
150
+ v?: unknown;
151
+ /** Prefetched next steps, in order. */
152
+ more?: CursorHit[];
153
+ }
154
+ export interface TxMessage {
155
+ t: "tx";
156
+ tx: number;
157
+ db: string;
158
+ begin?: {
159
+ mode: "readonly" | "readwrite" | "versionchange";
160
+ stores: string[];
161
+ version?: number;
162
+ };
163
+ ops: Op[];
164
+ /** `commitIfClean`: commit unless a request of the transaction failed (then reply `Deferred`). */
165
+ end?: "commit" | "abort" | "commitIfClean";
166
+ }
167
+ export interface TxReply {
168
+ t: "tx";
169
+ tx: number;
170
+ /** One per request, in order. */
171
+ res: unknown[];
172
+ /** Requests that failed: [index into res, DOMException name, message]. */
173
+ errs: [number, string, string][];
174
+ /** Set when the message ended the transaction. */
175
+ end?: {
176
+ ok: true;
177
+ } | {
178
+ ok: false;
179
+ name: string;
180
+ message: string;
181
+ };
182
+ }
183
+ export type CallMessage = {
184
+ t: "open";
185
+ id: number;
186
+ db: string;
187
+ } | {
188
+ t: "close";
189
+ id: number;
190
+ db: string;
191
+ } | {
192
+ t: "delete";
193
+ id: number;
194
+ db: string;
195
+ }
196
+ /** Sets the runtime's memory budget in bytes; null for no limit. */
197
+ | {
198
+ t: "budget";
199
+ id: number;
200
+ bytes: number | null;
201
+ }
202
+ /** Memory facts, and the file sizes of `db` if it is open. */
203
+ | {
204
+ t: "stats";
205
+ id: number;
206
+ db?: string;
207
+ }
208
+ /** Compacts every store file of an open database. */
209
+ | {
210
+ t: "compact";
211
+ id: number;
212
+ db: string;
213
+ }
214
+ /** Checks that the worker runs the engine on OPFS; fails where it cannot. */
215
+ | {
216
+ t: "probe";
217
+ id: number;
218
+ };
219
+ /** A call message without its id, per variant. */
220
+ export type CallRequest = CallMessage extends infer M ? (M extends CallMessage ? Omit<M, "id"> : never) : never;
221
+ /** What `memoryStats` reports. */
222
+ export interface MemoryStats {
223
+ /** The worker's WASM memory: its peak, since WASM memory never shrinks. */
224
+ wasmMemoryBytes: number;
225
+ /** The memory budget for loaded sections; Infinity when there is none. */
226
+ budgetBytes: number;
227
+ /** Bytes the loaded sections of every open database hold. */
228
+ cachedBytes: number;
229
+ /** The database's files (catalog and one per store), when it is open. */
230
+ fileBytes?: number;
231
+ files?: Record<string, number>;
232
+ /** Of `fileBytes`, the bytes the committed states use; the rest is free space. */
233
+ usedBytes?: number;
234
+ }
235
+ export type CallReply = {
236
+ t: "call";
237
+ id: number;
238
+ ok: true;
239
+ value: any;
240
+ } | {
241
+ t: "call";
242
+ id: number;
243
+ ok: false;
244
+ name: string;
245
+ message: string;
246
+ };
@@ -0,0 +1,129 @@
1
+ import type { CallRequest, TxMessage, TxReply } from "./protocol";
2
+ export interface RuntimeOptions {
3
+ /** A worker running plateau's worker script, already started (say by a head bootstrap). */
4
+ worker?: Worker;
5
+ /** Resolves when that worker has its WASM (it replied to `init`). */
6
+ initialized?: Promise<unknown>;
7
+ /** Which backend this page uses: `auto` (the default) picks OPFS where the engine runs there and
8
+ * the browser's own IndexedDB elsewhere; `opfs` and `indexeddb` skip the check. */
9
+ backend?: "auto" | "opfs" | "indexeddb";
10
+ }
11
+ /** Once versionchange has fired at a tab's connections: whether one is still open without a close
12
+ * pending, and their version (0 when none is open). */
13
+ export interface VersionChangeAck {
14
+ blocking: boolean;
15
+ version: number;
16
+ }
17
+ /** A tab's answer to a version change, and when its connections have all closed. */
18
+ export interface VersionChangeWait {
19
+ ack: VersionChangeAck | Promise<VersionChangeAck>;
20
+ closed: Promise<void>;
21
+ }
22
+ /** Fires versionchange at this tab's open connections to `db`; null when it has none open.
23
+ * `oldVersion` is null for a deleteDatabase, whose events carry the connections' version. */
24
+ export type VersionChangeHook = (db: string, oldVersion: number | null, newVersion: number | null) => VersionChangeWait | null;
25
+ /** The facade's handler for version changes other tabs ask for. */
26
+ export declare function onVersionChange(hook: VersionChangeHook): void;
27
+ /** The facade's handler for commits made in other tabs. */
28
+ export declare function onChange(hook: (db: string, stores: string[]) => void): void;
29
+ export declare class Runtime {
30
+ /** The worker, in the leader tab (and in a tab that has not yet found a live leader). */
31
+ worker: Worker | null;
32
+ /** `pending` while the tab knows no live leader: what it sends waits. */
33
+ role: "pending" | "leader" | "follower";
34
+ /** Transactions waiting for replies, by id. */
35
+ readonly txs: Map<number, {
36
+ _onReply(r: TxReply): void;
37
+ }>;
38
+ nextTx: number;
39
+ readonly tab: string;
40
+ /** Resolves when this tab becomes the leader (at once for a single tab); never rejects. */
41
+ readonly leading: Promise<void>;
42
+ /** The backend the page asked for (`startRuntime({ backend })`). */
43
+ readonly requested: "auto" | "opfs" | "indexeddb";
44
+ /** Set when this tab cannot run the engine (its worker failed to start, or the page uses the
45
+ * browser's IndexedDB): calls fail with it, here and from the tabs this one leads. */
46
+ dead: DOMException | null;
47
+ private becameLeader;
48
+ /** Whether the worker answered `init` (or was handed over started). */
49
+ private started;
50
+ private calls;
51
+ private nextCall;
52
+ /** Messages sent while no leader is known, in order. */
53
+ private held;
54
+ /** Transactions with messages at the current leader (follower only). */
55
+ private begun;
56
+ /** Transactions aborted because the leader closed; their later messages are dropped. */
57
+ private lost;
58
+ /** This tab's open connections per database. */
59
+ private opened;
60
+ private leaderTab;
61
+ private hub;
62
+ private port;
63
+ /** This tab's open-queue requests. */
64
+ private slots;
65
+ private nextSlot;
66
+ /** This tab's version changes waiting on other tabs. */
67
+ private vcs;
68
+ private nextVc;
69
+ /** Version changes this tab answered, by asking tab and id: a repeat sent to a new leader does
70
+ * not fire versionchange again. */
71
+ private seen;
72
+ private followers;
73
+ private relayed;
74
+ private queues;
75
+ private slotHolds;
76
+ private fanouts;
77
+ constructor(o?: RuntimeOptions);
78
+ /** This tab does not run the engine: stops its worker; calls fail from now on, and a tab this one
79
+ * leads gets the same failure, so it picks the same backend. */
80
+ stop(message: string): void;
81
+ call<T>(m: CallRequest): Promise<T>;
82
+ post(m: TxMessage, transfer?: Transferable[]): void;
83
+ /** A transaction of this tab finished. */
84
+ finished(tx: number): void;
85
+ /** Runs `job` when every earlier open or deleteDatabase of `db`, in any tab, has finished. */
86
+ queue(db: string, job: () => Promise<void>): void;
87
+ /** Tells the other tabs that a transaction of this tab that wrote `stores` committed. */
88
+ changed(db: string, stores: string[]): void;
89
+ /** Fires versionchange at other tabs' connections to `db`; null when no other tab has one. */
90
+ versionChange(db: string, oldVersion: number | null, newVersion: number | null): {
91
+ ack: Promise<VersionChangeAck>;
92
+ closed: Promise<void>;
93
+ } | null;
94
+ private startWorker;
95
+ private send;
96
+ /** Sends a control message to the leader. While there is none it is dropped: `flush` sends
97
+ * again whatever is still wanted once one answers. */
98
+ private toLeader;
99
+ private settle;
100
+ private watch;
101
+ private onHub;
102
+ /** A follower of `leader`: stops its own worker and asks the leader to serve it. */
103
+ private join;
104
+ private lead;
105
+ /** The leader closed: abort what it was running for this tab, and hold what follows. */
106
+ private leaderLost;
107
+ /** A leader serves this tab now: reopen its connections there, then send what waited. */
108
+ private flush;
109
+ private receive;
110
+ /** This tab's connections answer the version change `key` (asking tab and its id). */
111
+ private answer;
112
+ private reply;
113
+ private serve;
114
+ private onLeader;
115
+ private relayCall;
116
+ private relayTx;
117
+ private openQueue;
118
+ private grantSlot;
119
+ private fanOut;
120
+ /** A follower closed: roll back its transactions, close its connections, free what it held. */
121
+ private followerGone;
122
+ }
123
+ /** The page's runtime if it has started. */
124
+ export declare function currentRuntime(): Runtime | null;
125
+ /** The page's runtime, started on first call. */
126
+ export declare function runtime(o?: RuntimeOptions): Runtime;
127
+ /** Starts the runtime now, as an app does by importing the library at start-up; `o` attaches it
128
+ * to a worker a bootstrap started. */
129
+ export declare function startRuntime(o?: RuntimeOptions): Runtime;
@@ -0,0 +1,15 @@
1
+ export interface Schedulable {
2
+ readonly mode: IDBTransactionMode;
3
+ _scope: string[];
4
+ _started: boolean;
5
+ _state: string;
6
+ _start(): void;
7
+ }
8
+ declare class Scheduler {
9
+ live: Schedulable[];
10
+ add(tx: Schedulable): void;
11
+ done(tx: Schedulable): void;
12
+ pump(): void;
13
+ }
14
+ export declare function scheduler(name: string): Scheduler;
15
+ export {};
@@ -0,0 +1,7 @@
1
+ export declare function cloneError(what: string): DOMException;
2
+ /** The stored form of `v`. Throws DataCloneError for a type plateau does not store. */
3
+ export declare function encodeValue(v: unknown): string;
4
+ /** A fresh copy of the value `encodeValue` stored. */
5
+ export declare function decodeValue(s: string): unknown;
6
+ /** `structuredClone` restricted to the types plateau stores. */
7
+ export declare function cloneValue(v: unknown): unknown;
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "plateaudb",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "type": "module",
5
+ "description": "A browser database on OPFS with an IndexedDB-compatible API, written in Rust and compiled to WebAssembly; multi-key query time stays near-flat as rows grow",
6
+ "license": "MIT",
7
+ "author": "jagadhis",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/jagadhis/plateaudb.git"
11
+ },
12
+ "homepage": "https://github.com/jagadhis/plateaudb",
13
+ "bugs": {
14
+ "url": "https://github.com/jagadhis/plateaudb/issues"
15
+ },
16
+ "keywords": [
17
+ "indexeddb",
18
+ "opfs",
19
+ "database",
20
+ "browser",
21
+ "wasm",
22
+ "webassembly",
23
+ "rust",
24
+ "offline",
25
+ "local-first",
26
+ "bitmap-index"
27
+ ],
28
+ "exports": {
29
+ ".": {
30
+ "types": "./dist/index.d.ts",
31
+ "default": "./dist/index.js"
32
+ },
33
+ "./package.json": "./package.json"
34
+ },
35
+ "module": "./dist/index.js",
36
+ "types": "./dist/index.d.ts",
37
+ "files": [
38
+ "dist",
39
+ "README.md",
40
+ "LICENSE"
41
+ ],
42
+ "sideEffects": false,
43
+ "scripts": {
44
+ "build": "bun build.ts",
45
+ "prepack": "bun build.ts",
46
+ "test": "bun test test/",
47
+ "typecheck": "tsc --noEmit",
48
+ "conformance": "bun conformance/run.ts",
49
+ "multitab": "bun conformance/multitab.ts"
50
+ },
51
+ "devDependencies": {
52
+ "@types/bun": "^1.3.0",
53
+ "playwright": "1.65.0",
54
+ "typescript": "^5.9.0",
55
+ "vite": "^8.0.0"
56
+ }
57
+ }