@tallyui/storage-sqlite 0.2.0 → 3.0.0-next.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.
@@ -0,0 +1,75 @@
1
+ import type { SQLiteBasics, SQLResultRow } from 'rxdb/plugins/storage-sqlite';
2
+ import { sqliteBoolParams } from '../params';
3
+
4
+ /**
5
+ * The minimal surface of `@sqlite.org/sqlite-wasm`'s synchronous OO1 API
6
+ * (https://sqlite.org/wasm/doc/trunk/api-oo1.md) that this adapter needs,
7
+ * whether the handle comes from `sqlite3.oo1.DB` or from an opfs-sahpool
8
+ * `OpfsSAHPoolDb`.
9
+ */
10
+ export interface Oo1Db {
11
+ exec(opts: { sql: string; bind?: unknown[]; rowMode?: 'object'; returnValue?: 'resultRows' }): unknown;
12
+ close(): void;
13
+ }
14
+
15
+ /**
16
+ * A port of WCPOS's `getSQLiteBasicsOo1` spike onto the synchronous OO1 API,
17
+ * for RxDB Premium's SQLite storage (ADR-061). Unlike the expo-sqlite
18
+ * `SQLiteBasics` in `rx-storage-sqlite.ts`, one worker here can serve several
19
+ * RxDB databases: `openDb(name)` opens a separate opfs-sahpool file per name,
20
+ * for example one per store scope after a store switch. What must not happen
21
+ * is opening the *same* name twice, which would give two handles on one pool
22
+ * file — so handles are cached by name. `open(name)` returns the cached
23
+ * handle if there is one, otherwise opens a new one (running
24
+ * `PRAGMA locking_mode = exclusive` before anything else touches it), caches
25
+ * it, and returns it; concurrent opens of the same name share a single
26
+ * in-flight promise. `close` removes the handle from the cache, so a later
27
+ * `open` of that name reopens it.
28
+ */
29
+ export function getSQLiteBasicsOpfsSahPool({ openDb }: { openDb: (name: string) => Promise<Oo1Db> }): SQLiteBasics<Oo1Db> {
30
+ const handles = new Map<string, Promise<Oo1Db>>();
31
+ const namesByHandle = new Map<Oo1Db, string>();
32
+ return {
33
+ debugId: 'tallyui-sqlite-sahpool',
34
+ journalMode: 'WAL',
35
+ open: async (name) => {
36
+ const cached = handles.get(name);
37
+ if (cached !== undefined) {
38
+ return cached;
39
+ }
40
+ const opening = (async () => {
41
+ const db = await openDb(name);
42
+ // Exclusive locking must be set before anything else touches the
43
+ // handle: it drops SQLite's per-transaction lock/unlock cycle, which
44
+ // is the point of opfs-sahpool owning the origin's storage alone.
45
+ db.exec({ sql: 'PRAGMA locking_mode = exclusive' });
46
+ namesByHandle.set(db, name);
47
+ return db;
48
+ })();
49
+ handles.set(name, opening);
50
+ return opening;
51
+ },
52
+ all: async (db, q) => {
53
+ return db.exec({
54
+ sql: q.query,
55
+ bind: sqliteBoolParams(q.params),
56
+ rowMode: 'object',
57
+ returnValue: 'resultRows',
58
+ }) as SQLResultRow[];
59
+ },
60
+ run: async (db, q) => {
61
+ db.exec({ sql: q.query, bind: sqliteBoolParams(q.params) });
62
+ },
63
+ setPragma: async (db, key, value) => {
64
+ db.exec({ sql: `pragma ${key} = ${value};` });
65
+ },
66
+ close: async (db) => {
67
+ const name = namesByHandle.get(db);
68
+ if (name !== undefined) {
69
+ handles.delete(name);
70
+ namesByHandle.delete(db);
71
+ }
72
+ db.close();
73
+ },
74
+ };
75
+ }
@@ -0,0 +1,84 @@
1
+ import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
2
+ import type { RxStorage } from 'rxdb';
3
+ import { setPremiumFlag } from 'rxdb-premium/plugins/shared';
4
+ import { getRxStorageSQLite } from 'rxdb-premium/plugins/storage-sqlite';
5
+ import { exposeWorkerRxStorage } from 'rxdb-premium/plugins/storage-worker';
6
+ import { getSQLiteBasicsOpfsSahPool, type Oo1Db } from './sqlite-basics-sahpool';
7
+ import { STORAGE_HELD_MARKER, StorageUnavailableError, StorageWorkerStartError } from './errors';
8
+
9
+ // What a pool install rejects with while another tab holds the pool (#293): WebKit's, then Chromium's.
10
+ const HELD_ERROR_NAMES = ['InvalidStateError', 'NoModificationAllowedError'];
11
+
12
+ // Only the message crosses RxDB's worker channel, so each start error carries its cause's name and message.
13
+ const describeCause = (cause: unknown) => (cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause));
14
+
15
+ // A private window (WebKit's ephemeral storage, #293) rejects getDirectory(), and a browser without sync access
16
+ // handles can't host the pool: the storage is unavailable, whatever other tabs do.
17
+ async function requireOpfs(): Promise<void> {
18
+ try {
19
+ const handle = globalThis.FileSystemFileHandle?.prototype ?? {};
20
+ if (!('createSyncAccessHandle' in handle)) throw new TypeError('FileSystemFileHandle.createSyncAccessHandle is missing');
21
+ await navigator.storage.getDirectory();
22
+ } catch (cause) {
23
+ const why = `this browser gives the page no OPFS storage (a private window?): ${describeCause(cause)}`;
24
+ throw new StorageUnavailableError(`StorageUnavailableError: ${why}`, { cause });
25
+ }
26
+ }
27
+
28
+ // The worker is its own JS context with its own RxDB globals, so it sets
29
+ // RxDB 17's premium flag itself (13-collection cap otherwise).
30
+ setPremiumFlag();
31
+
32
+ // This must run inside a dedicated worker (ADR-061): `createSyncAccessHandle`,
33
+ // which opfs-sahpool needs, exists only there, not on the main thread or in
34
+ // a shared worker. opfs-sahpool also holds exclusive access handles for the
35
+ // whole origin, so once this worker has the pool open, a second tab cannot
36
+ // open it at all; ADR-061 makes one live tab, one dedicated worker, the
37
+ // supported topology and a reload the recovery from a dead or hung worker.
38
+ //
39
+ // `exposeWorkerRxStorage` below must run synchronously, at module start,
40
+ // before the pool install is even awaited: in real Chromium, RxDB's first
41
+ // message (creating the storage instance) arrives well before start-up
42
+ // finishes, and a worker that isn't listening yet drops it, hanging every
43
+ // cold start.
44
+
45
+ // A throwaway instance gives `name`/`rxdbVersion` without awaiting anything;
46
+ // its `openDb` is never called, since only `ready` below opens a real pool.
47
+ const { name, rxdbVersion } = getRxStorageSQLite({
48
+ sqliteBasics: getSQLiteBasicsOpfsSahPool({ openDb: () => Promise.reject(new Error('unused: throwaway instance')) }),
49
+ });
50
+
51
+ const ready: Promise<RxStorage<any, any>> = Promise.all([sqlite3InitModule(), requireOpfs()])
52
+ .then(([sqlite3]) => sqlite3.installOpfsSAHPoolVfs({ name: 'tallyui', initialCapacity: 64 }))
53
+ .then((pool) =>
54
+ getRxStorageSQLite({
55
+ sqliteBasics: getSQLiteBasicsOpfsSahPool({
56
+ // The OO1 `exec()` here is the real, overloaded sqlite-wasm signature;
57
+ // `Oo1Db` is the minimal shape this package's adapters need from it.
58
+ openDb: async (dbName) => new pool.OpfsSAHPoolDb('/' + dbName) as unknown as Oo1Db,
59
+ }),
60
+ })
61
+ );
62
+ // A pool install failure before any createStorageInstance call would otherwise be an unhandled rejection; createStorageInstance below still surfaces it as a start error.
63
+ ready.catch(() => {});
64
+
65
+ const storage: RxStorage<any, any> = {
66
+ name,
67
+ rxdbVersion,
68
+ createStorageInstance: async (params) => {
69
+ let realStorage: RxStorage<any, any>;
70
+ try {
71
+ realStorage = await ready;
72
+ } catch (cause) {
73
+ // Start-up failed: fail every call instead of hanging it forever. With OPFS reachable, a refused
74
+ // pool install means another tab holds it; any other failure keeps its cause for diagnosis.
75
+ if (cause instanceof StorageUnavailableError) throw cause;
76
+ const held = HELD_ERROR_NAMES.includes((cause as Error | undefined)?.name ?? '');
77
+ const what = held ? `${STORAGE_HELD_MARKER} (opfs-sahpool)` : 'SQLite worker start failed';
78
+ throw new StorageWorkerStartError(`StorageWorkerStartError: ${what}: ${describeCause(cause)}`, { cause });
79
+ }
80
+ return realStorage.createStorageInstance(params);
81
+ },
82
+ };
83
+
84
+ exposeWorkerRxStorage({ storage });
@@ -1,169 +0,0 @@
1
- /**
2
- * Integration test: RxDB -> SQLite storage round-trip.
3
- *
4
- * Creates a real RxDB database backed by the SQLite storage adapter
5
- * (using the mock in-memory SQLite) and proves that documents can
6
- * be inserted, queried, and updated through the full RxDB pipeline.
7
- */
8
- import { describe, it, expect, beforeEach, afterEach } from 'vitest';
9
- import { createRxDatabase, addRxPlugin, type RxDatabase, type RxCollection } from 'rxdb';
10
- import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';
11
- import { wrappedValidateAjvStorage } from 'rxdb/plugins/validate-ajv';
12
- import { createMockSQLiteDatabase } from './mock-sqlite';
13
- import { getRxStorageSQLite } from './rx-storage-sqlite';
14
-
15
- // Enable dev mode for better error messages in tests
16
- addRxPlugin(RxDBDevModePlugin);
17
-
18
- interface HeroDocType {
19
- id: string;
20
- name: string;
21
- power: number;
22
- }
23
-
24
- type HeroCollection = RxCollection<HeroDocType>;
25
- type HeroDatabase = RxDatabase<{ heroes: HeroCollection }>;
26
-
27
- const heroSchema = {
28
- version: 0,
29
- primaryKey: 'id',
30
- type: 'object' as const,
31
- properties: {
32
- id: { type: 'string' as const, maxLength: 100 },
33
- name: { type: 'string' as const },
34
- power: { type: 'number' as const },
35
- },
36
- required: ['id', 'name', 'power'] as const,
37
- };
38
-
39
- describe('RxDB + SQLite storage integration', () => {
40
- let db: HeroDatabase;
41
-
42
- beforeEach(async () => {
43
- const mockDb = createMockSQLiteDatabase();
44
- const baseStorage = getRxStorageSQLite(mockDb);
45
- // Wrap with ajv validator to satisfy dev-mode requirements
46
- const storage = wrappedValidateAjvStorage({ storage: baseStorage });
47
-
48
- db = await createRxDatabase<{ heroes: HeroCollection }>({
49
- name: 'integration_test_' + Date.now(),
50
- storage,
51
- multiInstance: false,
52
- ignoreDuplicate: true,
53
- });
54
-
55
- await db.addCollections({
56
- heroes: { schema: heroSchema },
57
- });
58
- });
59
-
60
- afterEach(async () => {
61
- if (db) {
62
- await db.close();
63
- }
64
- });
65
-
66
- it('should insert a document and query it back', async () => {
67
- // Insert
68
- const doc = await db.heroes.insert({
69
- id: 'hero1',
70
- name: 'Superman',
71
- power: 100,
72
- });
73
- expect(doc.id).toBe('hero1');
74
- expect(doc.name).toBe('Superman');
75
-
76
- // Query back
77
- const found = await db.heroes.findOne('hero1').exec();
78
- expect(found).not.toBeNull();
79
- expect(found!.name).toBe('Superman');
80
- expect(found!.power).toBe(100);
81
- });
82
-
83
- it('should insert multiple documents and find them all', async () => {
84
- await db.heroes.bulkInsert([
85
- { id: 'h1', name: 'Batman', power: 80 },
86
- { id: 'h2', name: 'Wonder Woman', power: 95 },
87
- { id: 'h3', name: 'Flash', power: 90 },
88
- ]);
89
-
90
- const all = await db.heroes.find().exec();
91
- expect(all).toHaveLength(3);
92
-
93
- const names = all.map((d) => d.name).sort();
94
- expect(names).toEqual(['Batman', 'Flash', 'Wonder Woman']);
95
- });
96
-
97
- it('should update a document', async () => {
98
- const doc = await db.heroes.insert({
99
- id: 'hero1',
100
- name: 'Superman',
101
- power: 100,
102
- });
103
-
104
- // Update using RxDB's patch method
105
- await doc.patch({ power: 150 });
106
-
107
- // Query back the updated version
108
- const updated = await db.heroes.findOne('hero1').exec();
109
- expect(updated).not.toBeNull();
110
- expect(updated!.power).toBe(150);
111
- });
112
-
113
- it('should delete a document', async () => {
114
- const doc = await db.heroes.insert({
115
- id: 'hero1',
116
- name: 'Superman',
117
- power: 100,
118
- });
119
-
120
- await doc.remove();
121
-
122
- const found = await db.heroes.findOne('hero1').exec();
123
- expect(found).toBeNull();
124
- });
125
-
126
- it('should support querying by selector', async () => {
127
- await db.heroes.bulkInsert([
128
- { id: 'h1', name: 'Batman', power: 80 },
129
- { id: 'h2', name: 'Superman', power: 100 },
130
- { id: 'h3', name: 'Flash', power: 90 },
131
- ]);
132
-
133
- // Query for heroes with power > 85
134
- // Use in-memory fallback since mock doesn't support json_extract
135
- const powerful = await db.heroes.find({
136
- selector: { power: { $gt: 85 } },
137
- }).exec();
138
-
139
- expect(powerful).toHaveLength(2);
140
- const names = powerful.map((d) => d.name).sort();
141
- expect(names).toEqual(['Flash', 'Superman']);
142
- });
143
-
144
- it('should handle the full create-read-update-delete cycle', async () => {
145
- // Create
146
- const doc = await db.heroes.insert({
147
- id: 'lifecycle',
148
- name: 'Temp Hero',
149
- power: 50,
150
- });
151
- expect(doc.id).toBe('lifecycle');
152
-
153
- // Read
154
- let found = await db.heroes.findOne('lifecycle').exec();
155
- expect(found).not.toBeNull();
156
- expect(found!.name).toBe('Temp Hero');
157
-
158
- // Update
159
- await found!.patch({ name: 'Updated Hero', power: 75 });
160
- found = await db.heroes.findOne('lifecycle').exec();
161
- expect(found!.name).toBe('Updated Hero');
162
- expect(found!.power).toBe(75);
163
-
164
- // Delete
165
- await found!.remove();
166
- found = await db.heroes.findOne('lifecycle').exec();
167
- expect(found).toBeNull();
168
- });
169
- });
@@ -1,239 +0,0 @@
1
- import { describe, it, expect } from 'vitest';
2
- import { mangoQueryToSQL, buildQuerySQL, buildCountSQL } from './mango-to-sql';
3
- import type { FilledMangoQuery } from 'rxdb';
4
-
5
- function makeQuery(overrides: Partial<FilledMangoQuery<any>> = {}): FilledMangoQuery<any> {
6
- return {
7
- selector: {},
8
- sort: [],
9
- skip: 0,
10
- ...overrides,
11
- };
12
- }
13
-
14
- describe('mangoQueryToSQL', () => {
15
- describe('basic selectors', () => {
16
- it('should produce WHERE with only _deleted filter for empty selector', () => {
17
- const result = mangoQueryToSQL(makeQuery());
18
- expect(result.where).toBe(`WHERE json_extract(data, '$._deleted') = 0`);
19
- expect(result.params).toEqual([]);
20
- });
21
-
22
- it('should handle equality ($eq) for a field', () => {
23
- const result = mangoQueryToSQL(makeQuery({
24
- selector: { name: 'Alice' } as any,
25
- }));
26
- expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
27
- expect(result.params).toContain('Alice');
28
- });
29
-
30
- it('should handle explicit $eq operator', () => {
31
- const result = mangoQueryToSQL(makeQuery({
32
- selector: { name: { $eq: 'Alice' } } as any,
33
- }));
34
- expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
35
- expect(result.params).toEqual(['Alice']);
36
- });
37
- });
38
-
39
- describe('comparison operators', () => {
40
- it('should handle $gt', () => {
41
- const result = mangoQueryToSQL(makeQuery({
42
- selector: { age: { $gt: 25 } } as any,
43
- }));
44
- expect(result.where).toContain(`json_extract(data, '$.age') > ?`);
45
- expect(result.params).toContain(25);
46
- });
47
-
48
- it('should handle $gte', () => {
49
- const result = mangoQueryToSQL(makeQuery({
50
- selector: { age: { $gte: 25 } } as any,
51
- }));
52
- expect(result.where).toContain(`json_extract(data, '$.age') >= ?`);
53
- expect(result.params).toContain(25);
54
- });
55
-
56
- it('should handle $lt', () => {
57
- const result = mangoQueryToSQL(makeQuery({
58
- selector: { age: { $lt: 30 } } as any,
59
- }));
60
- expect(result.where).toContain(`json_extract(data, '$.age') < ?`);
61
- expect(result.params).toContain(30);
62
- });
63
-
64
- it('should handle $lte', () => {
65
- const result = mangoQueryToSQL(makeQuery({
66
- selector: { age: { $lte: 30 } } as any,
67
- }));
68
- expect(result.where).toContain(`json_extract(data, '$.age') <= ?`);
69
- expect(result.params).toContain(30);
70
- });
71
-
72
- it('should handle $ne', () => {
73
- const result = mangoQueryToSQL(makeQuery({
74
- selector: { status: { $ne: 'inactive' } } as any,
75
- }));
76
- expect(result.where).toContain(`json_extract(data, '$.status') != ?`);
77
- expect(result.params).toContain('inactive');
78
- });
79
- });
80
-
81
- describe('array operators', () => {
82
- it('should handle $in', () => {
83
- const result = mangoQueryToSQL(makeQuery({
84
- selector: { status: { $in: ['active', 'pending'] } } as any,
85
- }));
86
- expect(result.where).toContain(`json_extract(data, '$.status') IN (?, ?)`);
87
- expect(result.params).toEqual(['active', 'pending']);
88
- });
89
-
90
- it('should handle empty $in as always-false', () => {
91
- const result = mangoQueryToSQL(makeQuery({
92
- selector: { status: { $in: [] } } as any,
93
- }));
94
- expect(result.where).toContain('0');
95
- });
96
-
97
- it('should handle $nin', () => {
98
- const result = mangoQueryToSQL(makeQuery({
99
- selector: { status: { $nin: ['deleted', 'archived'] } } as any,
100
- }));
101
- expect(result.where).toContain(`json_extract(data, '$.status') NOT IN (?, ?)`);
102
- expect(result.params).toEqual(['deleted', 'archived']);
103
- });
104
- });
105
-
106
- describe('regex', () => {
107
- it('should convert $regex to LIKE with wildcards', () => {
108
- const result = mangoQueryToSQL(makeQuery({
109
- selector: { name: { $regex: '^Al' } } as any,
110
- }));
111
- expect(result.where).toContain(`json_extract(data, '$.name') LIKE ?`);
112
- expect(result.params).toContain('Al%');
113
- });
114
-
115
- it('should handle unanchored regex with wrapping wildcards', () => {
116
- const result = mangoQueryToSQL(makeQuery({
117
- selector: { name: { $regex: 'lic' } } as any,
118
- }));
119
- expect(result.params).toContain('%lic%');
120
- });
121
-
122
- it('should handle end-anchored regex', () => {
123
- const result = mangoQueryToSQL(makeQuery({
124
- selector: { name: { $regex: 'ice$' } } as any,
125
- }));
126
- expect(result.params).toContain('%ice');
127
- });
128
- });
129
-
130
- describe('logical operators', () => {
131
- it('should handle $and', () => {
132
- const result = mangoQueryToSQL(makeQuery({
133
- selector: {
134
- $and: [
135
- { age: { $gte: 18 } },
136
- { age: { $lte: 65 } },
137
- ],
138
- } as any,
139
- }));
140
- expect(result.where).toContain(`json_extract(data, '$.age') >= ?`);
141
- expect(result.where).toContain(`json_extract(data, '$.age') <= ?`);
142
- expect(result.where).toContain(' AND ');
143
- expect(result.params).toEqual([18, 65]);
144
- });
145
-
146
- it('should handle $or', () => {
147
- const result = mangoQueryToSQL(makeQuery({
148
- selector: {
149
- $or: [
150
- { name: 'Alice' },
151
- { name: 'Bob' },
152
- ],
153
- } as any,
154
- }));
155
- expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
156
- expect(result.where).toContain(' OR ');
157
- expect(result.params).toEqual(['Alice', 'Bob']);
158
- });
159
- });
160
-
161
- describe('sort', () => {
162
- it('should generate ORDER BY clause for ascending', () => {
163
- const result = mangoQueryToSQL(makeQuery({
164
- sort: [{ name: 'asc' }] as any,
165
- }));
166
- expect(result.orderBy).toBe(`ORDER BY json_extract(data, '$.name') ASC`);
167
- });
168
-
169
- it('should generate ORDER BY clause for descending', () => {
170
- const result = mangoQueryToSQL(makeQuery({
171
- sort: [{ age: 'desc' }] as any,
172
- }));
173
- expect(result.orderBy).toBe(`ORDER BY json_extract(data, '$.age') DESC`);
174
- });
175
-
176
- it('should handle multiple sort fields', () => {
177
- const result = mangoQueryToSQL(makeQuery({
178
- sort: [{ name: 'asc' }, { age: 'desc' }] as any,
179
- }));
180
- expect(result.orderBy).toBe(
181
- `ORDER BY json_extract(data, '$.name') ASC, json_extract(data, '$.age') DESC`
182
- );
183
- });
184
- });
185
-
186
- describe('limit and skip', () => {
187
- it('should generate LIMIT clause', () => {
188
- const result = mangoQueryToSQL(makeQuery({ limit: 10 }));
189
- expect(result.limit).toBe('LIMIT ?');
190
- expect(result.limitParams).toEqual([10]);
191
- });
192
-
193
- it('should generate LIMIT + OFFSET for skip', () => {
194
- const result = mangoQueryToSQL(makeQuery({ limit: 10, skip: 5 }));
195
- expect(result.limit).toBe('LIMIT ? OFFSET ?');
196
- expect(result.limitParams).toEqual([10, 5]);
197
- });
198
-
199
- it('should generate LIMIT -1 OFFSET for skip without limit', () => {
200
- const result = mangoQueryToSQL(makeQuery({ skip: 5 }));
201
- expect(result.limit).toBe('LIMIT -1 OFFSET ?');
202
- expect(result.limitParams).toEqual([5]);
203
- });
204
- });
205
- });
206
-
207
- describe('buildQuerySQL', () => {
208
- it('should build a complete SELECT statement', () => {
209
- const query = makeQuery({
210
- selector: { name: 'Alice' } as any,
211
- sort: [{ name: 'asc' }] as any,
212
- limit: 10,
213
- skip: 0,
214
- });
215
- const { sql, params } = buildQuerySQL('my_table', query);
216
- expect(sql).toContain('SELECT data FROM "my_table"');
217
- expect(sql).toContain('WHERE');
218
- expect(sql).toContain('ORDER BY');
219
- expect(sql).toContain('LIMIT');
220
- expect(params).toContain('Alice');
221
- });
222
- });
223
-
224
- describe('buildCountSQL', () => {
225
- it('should build a COUNT statement without sort/limit/skip', () => {
226
- const query = makeQuery({
227
- selector: { age: { $gt: 20 } } as any,
228
- sort: [{ name: 'asc' }] as any,
229
- limit: 10,
230
- skip: 5,
231
- });
232
- const { sql, params } = buildCountSQL('my_table', query);
233
- expect(sql).toContain('SELECT COUNT(*) as count FROM "my_table"');
234
- expect(sql).toContain('WHERE');
235
- expect(sql).not.toContain('ORDER BY');
236
- expect(sql).not.toContain('LIMIT');
237
- expect(params).toContain(20);
238
- });
239
- });