@baukit/data-contracts-expo-sqlite 0.7.2 → 0.7.4
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/package.json +3 -2
- package/src/connection.test.ts +654 -0
- package/src/connection.ts +253 -0
- package/src/index.test.ts +673 -0
- package/src/index.ts +164 -0
- package/src/migration-conformance.test.ts +171 -0
- package/src/migration-conformance.ts +281 -0
- package/src/node-sqlite.test.ts +195 -0
- package/src/node-sqlite.ts +205 -0
- package/src/operation-queue.test.ts +68 -0
- package/src/operation-queue.ts +42 -0
- package/src/queued-database.ts +86 -0
- package/src/statements.ts +328 -0
- package/src/testing.ts +7 -0
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
import { StorageError } from '@baukit/data-contracts';
|
|
2
|
+
import type { SQLiteBindParams, SQLiteRunResult, SQLiteVariadicBindParams } from 'expo-sqlite';
|
|
3
|
+
|
|
4
|
+
import { type ExpoSqliteDatabase, QueuedDatabase } from './queued-database.js';
|
|
5
|
+
import type { SQLiteConnection, StatementScope } from './statements.js';
|
|
6
|
+
|
|
7
|
+
type BindArguments = [SQLiteBindParams] | SQLiteVariadicBindParams;
|
|
8
|
+
|
|
9
|
+
const ENFORCE_FOREIGN_KEYS = 'PRAGMA foreign_keys = ON';
|
|
10
|
+
const ROOT_DEPTH = 0;
|
|
11
|
+
const SAVEPOINT_PREFIX = 'baukit_nested_';
|
|
12
|
+
|
|
13
|
+
/** The statements that open, commit, and roll back one transaction level. */
|
|
14
|
+
interface Boundary {
|
|
15
|
+
readonly begin: string;
|
|
16
|
+
readonly commit: string;
|
|
17
|
+
readonly rollback: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
const ROOT_BOUNDARY: Boundary = {
|
|
21
|
+
begin: 'BEGIN IMMEDIATE',
|
|
22
|
+
commit: 'COMMIT',
|
|
23
|
+
rollback: 'ROLLBACK',
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
type TransactionWork<TResult> = (transaction: SqliteTransaction) => Promise<TResult> | TResult;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Raw SQL statements. Parameters bind as `expo-sqlite` binds them: variadic values, one array, or
|
|
30
|
+
* one object whose keys keep their `$`, `:`, or `@` prefix.
|
|
31
|
+
*/
|
|
32
|
+
export interface SqliteStatements {
|
|
33
|
+
/** Runs a script of one or more statements without parameters. */
|
|
34
|
+
exec(source: string): Promise<void>;
|
|
35
|
+
run(source: string, params: SQLiteBindParams): Promise<SQLiteRunResult>;
|
|
36
|
+
run(source: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
|
|
37
|
+
/** Resolves to the first row, or `undefined` when there is none. */
|
|
38
|
+
get<TRow>(source: string, params: SQLiteBindParams): Promise<TRow | undefined>;
|
|
39
|
+
get<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow | undefined>;
|
|
40
|
+
all<TRow>(source: string, params: SQLiteBindParams): Promise<TRow[]>;
|
|
41
|
+
all<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow[]>;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Statements inside one open transaction. They reject with `storage_closed` once the transaction
|
|
46
|
+
* has settled, and with a `TypeError` while a nested transaction started from it is open.
|
|
47
|
+
*/
|
|
48
|
+
export interface SqliteTransaction extends SqliteStatements {
|
|
49
|
+
/**
|
|
50
|
+
* Runs `work` in a savepoint inside this transaction, without waiting on the file queue. The
|
|
51
|
+
* savepoint is released when `work` resolves and rolled back when it rejects; the rejection
|
|
52
|
+
* then reaches the caller, and the enclosing transaction commits only if the caller catches it.
|
|
53
|
+
*/
|
|
54
|
+
transaction<TResult>(work: TransactionWork<TResult>): Promise<TResult>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface ExpoSqliteConnectionOptions {
|
|
58
|
+
/** Close the supplied database when this connection closes. Defaults to false. */
|
|
59
|
+
readonly closeDatabase?: boolean;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
class ScopedStatements implements SqliteStatements {
|
|
63
|
+
public constructor(protected readonly scope: StatementScope) {}
|
|
64
|
+
|
|
65
|
+
public async exec(source: string): Promise<void> {
|
|
66
|
+
this.scope.assertAvailable();
|
|
67
|
+
await this.scope.run((connection) => connection.execAsync(source));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
public run(source: string, params: SQLiteBindParams): Promise<SQLiteRunResult>;
|
|
71
|
+
public run(source: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
|
|
72
|
+
public async run(source: string, ...params: BindArguments): Promise<SQLiteRunResult> {
|
|
73
|
+
this.scope.assertAvailable();
|
|
74
|
+
return this.scope.run((connection) => connection.runAsync(source, ...variadic(params)));
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
public get<TRow>(source: string, params: SQLiteBindParams): Promise<TRow | undefined>;
|
|
78
|
+
public get<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow | undefined>;
|
|
79
|
+
public async get<TRow>(source: string, ...params: BindArguments): Promise<TRow | undefined> {
|
|
80
|
+
this.scope.assertAvailable();
|
|
81
|
+
const row = await this.scope.run((connection) =>
|
|
82
|
+
connection.getFirstAsync<TRow>(source, ...variadic(params)),
|
|
83
|
+
);
|
|
84
|
+
return row ?? undefined;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
public all<TRow>(source: string, params: SQLiteBindParams): Promise<TRow[]>;
|
|
88
|
+
public all<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow[]>;
|
|
89
|
+
public async all<TRow>(source: string, ...params: BindArguments): Promise<TRow[]> {
|
|
90
|
+
this.scope.assertAvailable();
|
|
91
|
+
return this.scope.run((connection) =>
|
|
92
|
+
connection.getAllAsync<TRow>(source, ...variadic(params)),
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** One open transaction or savepoint. Only the innermost open level accepts work. */
|
|
98
|
+
class TransactionLevel implements StatementScope {
|
|
99
|
+
private active = true;
|
|
100
|
+
private nestedOpen = false;
|
|
101
|
+
|
|
102
|
+
public constructor(
|
|
103
|
+
private readonly connection: SQLiteConnection,
|
|
104
|
+
private readonly depth: number,
|
|
105
|
+
) {}
|
|
106
|
+
|
|
107
|
+
public assertAvailable(): void {
|
|
108
|
+
if (!this.active) {
|
|
109
|
+
throw new StorageError('storage_closed', 'The transaction context is no longer active.');
|
|
110
|
+
}
|
|
111
|
+
if (this.nestedOpen) {
|
|
112
|
+
throw new TypeError(
|
|
113
|
+
'A nested SQLite transaction is open. Use the nested transaction until it settles.',
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
public run<TResult>(
|
|
119
|
+
statement: (connection: SQLiteConnection) => Promise<TResult>,
|
|
120
|
+
): Promise<TResult> {
|
|
121
|
+
return statement(this.connection);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
public async nest<TResult>(work: TransactionWork<TResult>): Promise<TResult> {
|
|
125
|
+
this.assertAvailable();
|
|
126
|
+
this.nestedOpen = true;
|
|
127
|
+
try {
|
|
128
|
+
return await runLevel(this.connection, this.depth + 1, work);
|
|
129
|
+
} finally {
|
|
130
|
+
this.nestedOpen = false;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
public finish(): void {
|
|
135
|
+
this.active = false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
class ConnectionTransaction extends ScopedStatements implements SqliteTransaction {
|
|
140
|
+
public constructor(private readonly level: TransactionLevel) {
|
|
141
|
+
super(level);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
public transaction<TResult>(work: TransactionWork<TResult>): Promise<TResult> {
|
|
145
|
+
return this.level.nest(work);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** The root scope: queued on the database file, with foreign keys enabled before any work. */
|
|
150
|
+
class ConnectionScope implements StatementScope {
|
|
151
|
+
private foreignKeysEnforced = false;
|
|
152
|
+
|
|
153
|
+
public constructor(public readonly queued: QueuedDatabase) {}
|
|
154
|
+
|
|
155
|
+
public assertAvailable(): void {
|
|
156
|
+
this.queued.assertOpen();
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
public run<TResult>(
|
|
160
|
+
statement: (connection: SQLiteConnection) => Promise<TResult>,
|
|
161
|
+
): Promise<TResult> {
|
|
162
|
+
return this.queued.enqueue(async () => {
|
|
163
|
+
await this.enforceForeignKeys();
|
|
164
|
+
return statement(this.queued.database);
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
private async enforceForeignKeys(): Promise<void> {
|
|
169
|
+
if (this.foreignKeysEnforced) {
|
|
170
|
+
return;
|
|
171
|
+
}
|
|
172
|
+
await this.queued.database.execAsync(ENFORCE_FOREIGN_KEYS);
|
|
173
|
+
this.foreignKeysEnforced = true;
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* A raw SQL connection over an Expo SQLite database. Statements, transactions, and `close()` run
|
|
179
|
+
* one at a time in call order on the queue that every adapter store on the same database file
|
|
180
|
+
* shares, so a root statement never runs inside another caller's transaction. Transactions run
|
|
181
|
+
* `BEGIN IMMEDIATE` on the supplied handle, and the connection enables foreign keys before its
|
|
182
|
+
* first statement, so they stay enforced inside transactions.
|
|
183
|
+
*/
|
|
184
|
+
export class ExpoSqliteConnection extends ScopedStatements {
|
|
185
|
+
private readonly root: ConnectionScope;
|
|
186
|
+
|
|
187
|
+
public constructor(database: ExpoSqliteDatabase, options: ExpoSqliteConnectionOptions = {}) {
|
|
188
|
+
const root = new ConnectionScope(new QueuedDatabase(database, options.closeDatabase === true));
|
|
189
|
+
super(root);
|
|
190
|
+
this.root = root;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Runs `work` in one transaction that commits when it resolves and rolls back when it rejects.
|
|
195
|
+
* Use only the transaction it receives, and nest through its `transaction()`: a root call on
|
|
196
|
+
* this file from inside `work` waits for the transaction, which waits for `work`, and neither
|
|
197
|
+
* finishes.
|
|
198
|
+
*/
|
|
199
|
+
public async transaction<TResult>(work: TransactionWork<TResult>): Promise<TResult> {
|
|
200
|
+
this.root.assertAvailable();
|
|
201
|
+
return this.root.run((connection) => runLevel(connection, ROOT_DEPTH, work));
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Rejects new work, waits for accepted work, and settles every caller with one result. */
|
|
205
|
+
public close(): Promise<void> {
|
|
206
|
+
return this.root.queued.close();
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function boundaryAt(depth: number): Boundary {
|
|
211
|
+
if (depth === ROOT_DEPTH) {
|
|
212
|
+
return ROOT_BOUNDARY;
|
|
213
|
+
}
|
|
214
|
+
const name = `${SAVEPOINT_PREFIX}${String(depth)}`;
|
|
215
|
+
return {
|
|
216
|
+
begin: `SAVEPOINT ${name}`,
|
|
217
|
+
commit: `RELEASE ${name}`,
|
|
218
|
+
rollback: `ROLLBACK TO ${name}; RELEASE ${name}`,
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
async function runLevel<TResult>(
|
|
223
|
+
connection: SQLiteConnection,
|
|
224
|
+
depth: number,
|
|
225
|
+
work: TransactionWork<TResult>,
|
|
226
|
+
): Promise<TResult> {
|
|
227
|
+
const boundary = boundaryAt(depth);
|
|
228
|
+
await connection.execAsync(boundary.begin);
|
|
229
|
+
const level = new TransactionLevel(connection, depth);
|
|
230
|
+
try {
|
|
231
|
+
const result = await work(new ConnectionTransaction(level));
|
|
232
|
+
await connection.execAsync(boundary.commit);
|
|
233
|
+
return result;
|
|
234
|
+
} catch (cause) {
|
|
235
|
+
await rollback(connection, boundary);
|
|
236
|
+
throw cause;
|
|
237
|
+
} finally {
|
|
238
|
+
level.finish();
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Keeps the original failure when SQLite has already rolled the transaction back. */
|
|
243
|
+
async function rollback(connection: SQLiteConnection, boundary: Boundary): Promise<void> {
|
|
244
|
+
try {
|
|
245
|
+
await connection.execAsync(boundary.rollback);
|
|
246
|
+
} catch {
|
|
247
|
+
return;
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
function variadic(params: BindArguments): SQLiteVariadicBindParams {
|
|
252
|
+
return params as SQLiteVariadicBindParams;
|
|
253
|
+
}
|