@baukit/data-contracts-expo-sqlite 0.4.0 → 0.5.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/README.md CHANGED
@@ -33,20 +33,183 @@ await storage.withTransaction((transaction) =>
33
33
  ```
34
34
 
35
35
  Nested calls made on the transaction-scoped context join the ambient exclusive
36
- transaction. Independent root calls are serialized. `close()` closes the
37
- logical adapter; pass `{ closeDatabase: true }` when it should also own the
38
- supplied database handle.
36
+ transaction. `close()` closes the logical adapter; pass
37
+ `{ closeDatabase: true }` when it should also own the supplied database handle.
39
38
 
40
39
  Namespaces share one fixed `baukit_records` table without colliding. Call `initialize()` before using a store. Records are serialized as JSON, pagination is bounded and keyset-based, and malformed persisted payloads produce a content-free error.
41
40
 
42
- The package's fast Vitest suite uses a deterministic database fake. The
41
+ ## Operation ordering
42
+
43
+ Expo SQLite runs `withExclusiveTransactionAsync` on a second connection to the
44
+ same file. A statement on the base handle that runs while that transaction is
45
+ open fails with `database is locked`. The adapter therefore runs root reads,
46
+ root writes, `initialize()`, `withTransaction()`, and `close()` one at a time,
47
+ in call order, on one queue per database file (`SQLiteDatabase.databasePath`).
48
+ Every `ExpoSqliteStore`, `SqliteRecordStore`, `SqliteKeyValueStore`, and
49
+ `SqliteSchemaMetadataStore` on that file shares the queue, whichever handle and
50
+ namespace it uses. Stores on different files do not wait for each other.
51
+
52
+ - Work on the transaction context runs on the transaction connection and never
53
+ enters the queue.
54
+ - A rejected operation releases the queue for the next caller.
55
+ - `close()` rejects new calls with `storage_closed`, waits for work it already
56
+ accepted, closes an owned handle once, and returns the same promise to every
57
+ caller, including a rejected one.
58
+ - Lock errors from SQLite reach the caller unchanged. The adapter never retries.
59
+
60
+ Inside a `withTransaction` callback, use the context it passes in. A root call
61
+ on any store for the same file queues behind the transaction, the transaction
62
+ waits for that call, and neither finishes. Keep network and file work outside the
63
+ callback, because it holds the queue for every store on that file. Raw
64
+ statements a product runs on the handle itself bypass the queue. Run them
65
+ through `ExpoSqliteConnection` instead.
66
+
67
+ The package's fast Vitest suite runs the shared contracts against a deterministic
68
+ database fake and against `NodeSqliteDatabase` (see below). The
43
69
  [Expo SQLite device-conformance app](../../../examples/expo-sqlite-conformance/README.md)
44
70
  mirrors the shared contract cases against real `expo-sqlite` on Android,
45
71
  including creation/reopening, namespace isolation, malformed data, rollback,
46
- schema-metadata upgrades, and authenticated E→F→E database isolation. Products
72
+ schema-metadata upgrades, root-versus-transaction overlap in both arrival
73
+ orders, `ExpoSqliteConnection` ordering, foreign keys, and rollback next to
74
+ `ExpoSqliteStore`, and authenticated E→F→E database isolation. Products
47
75
  derive the database name and resolve its registry with `@baukit/data-contracts`
48
76
  before opening the Expo database. iOS is a scheduled/manual macOS gate.
49
77
 
78
+ ## Raw SQL connection
79
+
80
+ `ExpoSqliteConnection` runs a product's own SQL, such as a relational schema
81
+ and its migration runner, on the same per-file queue as the stores above.
82
+
83
+ ```ts
84
+ import { ExpoSqliteConnection } from '@baukit/data-contracts-expo-sqlite';
85
+
86
+ const connection = new ExpoSqliteConnection(database);
87
+ await connection.exec('CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT)');
88
+ await connection.transaction(async (transaction) => {
89
+ await transaction.run('INSERT INTO notes (id, body) VALUES (?, ?)', 'one', 'first');
90
+ return transaction.get<{ readonly body: string }>('SELECT body FROM notes WHERE id = ?', 'one');
91
+ });
92
+ ```
93
+
94
+ - `exec(source)` runs a script without parameters. `run`, `get`, and `all`
95
+ bind parameters as `expo-sqlite` does: variadic values, one array, or one
96
+ object whose keys keep their `$`, `:`, or `@` prefix. `run` resolves to
97
+ `{ changes, lastInsertRowId }`, `get` to the first row or `undefined`, and
98
+ `all` to every row.
99
+ - Every root statement, `transaction()`, and `close()` waits its turn on the
100
+ queue that every store on the same database file shares. A root statement
101
+ that another caller issues while a transaction is open runs after that
102
+ transaction commits or rolls back, never inside it.
103
+ - `transaction(work)` runs `BEGIN IMMEDIATE` on the supplied handle, commits
104
+ when `work` resolves, and rolls back when `work` or the commit rejects. The
105
+ original error reaches the caller unchanged, and the result of `work` is
106
+ returned.
107
+ - The transaction context has the same statement methods. Its
108
+ `transaction()` always rejects with a `TypeError`: nested transactions are
109
+ refused, never joined. After the transaction settles, its statements reject
110
+ with `storage_closed`.
111
+ - The connection runs `PRAGMA foreign_keys = ON` on the handle before its
112
+ first statement. Because transactions run on that handle, foreign keys and
113
+ `ON DELETE` actions stay enforced inside them. A step that must rebuild a
114
+ table can still run `PRAGMA foreign_keys = OFF` as a root statement before
115
+ its transaction and turn it back on afterwards.
116
+ - `close()` rejects new calls with `storage_closed`, waits for accepted work,
117
+ and closes the handle only with `{ closeDatabase: true }`.
118
+ - SQLite errors, including `database is locked`, pass through unchanged, and
119
+ nothing retries.
120
+
121
+ The connection does not use `withExclusiveTransactionAsync`. Expo runs `BEGIN`
122
+ on the new connection before calling the task, and SQLite ignores
123
+ `PRAGMA foreign_keys` inside a transaction, so a second connection would leave
124
+ foreign keys off with no way to turn them on.
125
+
126
+ The same deadlock rule as `withTransaction` applies: inside `work`, use the
127
+ transaction context. A root call on the connection or on any store for the
128
+ same file queues behind the transaction and never finishes.
129
+
130
+ ## Node tests
131
+
132
+ `@baukit/data-contracts-expo-sqlite/testing` runs Expo SQLite code in Node unit
133
+ tests (Vitest or Jest) on Node's built-in `node:sqlite`. It needs Node 24 or
134
+ later and adds no dependency.
135
+
136
+ ```ts
137
+ import { ExpoSqliteStore } from '@baukit/data-contracts-expo-sqlite';
138
+ import { NodeSqliteDatabase } from '@baukit/data-contracts-expo-sqlite/testing';
139
+
140
+ const database = new NodeSqliteDatabase();
141
+ const storage = new ExpoSqliteStore<CachedRecord>(database, 'product', { closeDatabase: true });
142
+ await storage.initialize();
143
+ ```
144
+
145
+ `NodeSqliteDatabase` implements `ExpoSqliteDatabase`, the part of an Expo
146
+ `SQLiteDatabase` that this adapter calls: `databasePath`, `execAsync`,
147
+ `runAsync`, `getFirstAsync`, `getAllAsync`, `withExclusiveTransactionAsync`, and
148
+ `closeAsync`. A product driver typed against those methods accepts it without a
149
+ cast. With no argument it opens a new temporary file and deletes it on
150
+ `closeAsync()`. With a path it opens that file and leaves it in place, so a test
151
+ can close and reopen the same database. `:memory:` throws a `TypeError`, because
152
+ an exclusive transaction must open a second connection to the same database.
153
+
154
+ It copies the device behavior that product tests tend to hide:
155
+
156
+ - `withExclusiveTransactionAsync` runs `BEGIN`, the task, and `COMMIT` on a new
157
+ connection to the same file, and rolls back when the task throws. A write on
158
+ the root handle while that transaction is open fails with `database is locked`.
159
+ - Every connection opens with foreign keys off. `PRAGMA foreign_keys = ON` on
160
+ the root handle does not reach transaction connections.
161
+ - Booleans and integral numbers bind as integers, `undefined` binds as NULL, and
162
+ named parameters need their `$`, `:`, or `@` prefix.
163
+ - Rows are plain objects, and `getFirstAsync` returns `null` for no row.
164
+
165
+ It differs from the device in three places. An unknown named parameter or an
166
+ extra positional value throws instead of being ignored. A root read during an
167
+ open transaction succeeds and sees the committed state. An integer outside the
168
+ safe range throws. It has no `withTransactionAsync`, `prepareAsync`, or
169
+ synchronous methods.
170
+
171
+ Jest projects that transform `@baukit/*` through Babel resolve the entry through
172
+ its `default` condition.
173
+
174
+ ## Migration runner conformance
175
+
176
+ `createSqliteMigrationConformanceTests(adapter)` returns framework-neutral cases
177
+ for a product's own SQLite migration runner. Register each with your test
178
+ runner:
179
+
180
+ ```ts
181
+ import {
182
+ createSqliteMigrationConformanceTests,
183
+ type SqliteMigrationConformanceAdapter,
184
+ } from '@baukit/data-contracts-expo-sqlite/testing';
185
+
186
+ const adapter: SqliteMigrationConformanceAdapter = {
187
+ migrate: (database, steps) => runMigrations(new ProductSqliteDriver(database), steps),
188
+ };
189
+
190
+ for (const testCase of createSqliteMigrationConformanceTests(adapter)) {
191
+ it(testCase.name, testCase.run);
192
+ }
193
+ ```
194
+
195
+ `migrate` receives a `NodeSqliteDatabase` and a list of
196
+ `{ version, name, sql }` steps, the complete list that one app build ships. It
197
+ must reject when the runner fails or refuses the database. The cases check that
198
+ the runner:
199
+
200
+ - applies every step to a fresh database;
201
+ - upgrades an older database and keeps its rows;
202
+ - applies nothing again after a restart;
203
+ - rolls back a failed step completely, with no table or column from its earlier
204
+ statements left behind, and applies the fixed step after a restart;
205
+ - refuses a database that a newer build migrated, and leaves it unchanged.
206
+
207
+ The suite does not read the runner's history table or `user_version`, so any
208
+ runner that records versions somewhere passes. A step's `sql` holds several
209
+ statements, so the runner must execute it as a script (`execAsync`). Each case
210
+ uses its own temporary file. A failed case throws an error that starts with
211
+ `SQLite migration conformance failed:` and names the broken expectation.
212
+
50
213
  ## Boundaries
51
214
 
52
215
  The package implements `@baukit/data-contracts` on Expo SQLite and nothing else. It does not choose a
@@ -0,0 +1,59 @@
1
+ import type { SQLiteBindParams, SQLiteRunResult, SQLiteVariadicBindParams } from 'expo-sqlite';
2
+ import { type ExpoSqliteDatabase } from './queued-database.js';
3
+ import type { StatementScope } from './statements.js';
4
+ /**
5
+ * Raw SQL statements. Parameters bind as `expo-sqlite` binds them: variadic values, one array, or
6
+ * one object whose keys keep their `$`, `:`, or `@` prefix.
7
+ */
8
+ export interface SqliteStatements {
9
+ /** Runs a script of one or more statements without parameters. */
10
+ exec(source: string): Promise<void>;
11
+ run(source: string, params: SQLiteBindParams): Promise<SQLiteRunResult>;
12
+ run(source: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
13
+ /** Resolves to the first row, or `undefined` when there is none. */
14
+ get<TRow>(source: string, params: SQLiteBindParams): Promise<TRow | undefined>;
15
+ get<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow | undefined>;
16
+ all<TRow>(source: string, params: SQLiteBindParams): Promise<TRow[]>;
17
+ all<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow[]>;
18
+ }
19
+ /** Statements inside one open transaction. They reject once the transaction has settled. */
20
+ export interface SqliteTransaction extends SqliteStatements {
21
+ /** Always rejects: a transaction never joins or nests another one. */
22
+ transaction(work: (transaction: SqliteTransaction) => unknown): Promise<never>;
23
+ }
24
+ export interface ExpoSqliteConnectionOptions {
25
+ /** Close the supplied database when this connection closes. Defaults to false. */
26
+ readonly closeDatabase?: boolean;
27
+ }
28
+ declare class ScopedStatements implements SqliteStatements {
29
+ protected readonly scope: StatementScope;
30
+ constructor(scope: StatementScope);
31
+ exec(source: string): Promise<void>;
32
+ run(source: string, params: SQLiteBindParams): Promise<SQLiteRunResult>;
33
+ run(source: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
34
+ get<TRow>(source: string, params: SQLiteBindParams): Promise<TRow | undefined>;
35
+ get<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow | undefined>;
36
+ all<TRow>(source: string, params: SQLiteBindParams): Promise<TRow[]>;
37
+ all<TRow>(source: string, ...params: SQLiteVariadicBindParams): Promise<TRow[]>;
38
+ }
39
+ /**
40
+ * A raw SQL connection over an Expo SQLite database. Statements, transactions, and `close()` run
41
+ * one at a time in call order on the queue that every adapter store on the same database file
42
+ * shares, so a root statement never runs inside another caller's transaction. Transactions run
43
+ * `BEGIN IMMEDIATE` on the supplied handle, and the connection enables foreign keys before its
44
+ * first statement, so they stay enforced inside transactions.
45
+ */
46
+ export declare class ExpoSqliteConnection extends ScopedStatements {
47
+ private readonly root;
48
+ constructor(database: ExpoSqliteDatabase, options?: ExpoSqliteConnectionOptions);
49
+ /**
50
+ * Runs `work` in one transaction that commits when it resolves and rolls back when it rejects.
51
+ * Use only the transaction it receives: a root call on this file from inside `work` waits for
52
+ * the transaction, which waits for `work`, and neither finishes.
53
+ */
54
+ transaction<TResult>(work: (transaction: SqliteTransaction) => Promise<TResult> | TResult): Promise<TResult>;
55
+ /** Rejects new work, waits for accepted work, and settles every caller with one result. */
56
+ close(): Promise<void>;
57
+ }
58
+ export {};
59
+ //# sourceMappingURL=connection.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,114 @@
1
+ import { QueuedDatabase, TransactionScope } from './queued-database.js';
2
+ const ENFORCE_FOREIGN_KEYS = 'PRAGMA foreign_keys = ON';
3
+ const BEGIN = 'BEGIN IMMEDIATE';
4
+ const COMMIT = 'COMMIT';
5
+ const ROLLBACK = 'ROLLBACK';
6
+ class ScopedStatements {
7
+ scope;
8
+ constructor(scope) {
9
+ this.scope = scope;
10
+ }
11
+ async exec(source) {
12
+ this.scope.assertAvailable();
13
+ await this.scope.run((connection) => connection.execAsync(source));
14
+ }
15
+ async run(source, ...params) {
16
+ this.scope.assertAvailable();
17
+ return this.scope.run((connection) => connection.runAsync(source, ...variadic(params)));
18
+ }
19
+ async get(source, ...params) {
20
+ this.scope.assertAvailable();
21
+ const row = await this.scope.run((connection) => connection.getFirstAsync(source, ...variadic(params)));
22
+ return row ?? undefined;
23
+ }
24
+ async all(source, ...params) {
25
+ this.scope.assertAvailable();
26
+ return this.scope.run((connection) => connection.getAllAsync(source, ...variadic(params)));
27
+ }
28
+ }
29
+ class ConnectionTransaction extends ScopedStatements {
30
+ transaction() {
31
+ return Promise.reject(new TypeError('A SQLite transaction cannot start another transaction. Run the statements on the current transaction instead.'));
32
+ }
33
+ }
34
+ /** The root scope: queued on the database file, with foreign keys enabled before any work. */
35
+ class ConnectionScope {
36
+ queued;
37
+ foreignKeysEnforced = false;
38
+ constructor(queued) {
39
+ this.queued = queued;
40
+ }
41
+ assertAvailable() {
42
+ this.queued.assertOpen();
43
+ }
44
+ run(statement) {
45
+ return this.queued.enqueue(async () => {
46
+ await this.enforceForeignKeys();
47
+ return statement(this.queued.database);
48
+ });
49
+ }
50
+ async enforceForeignKeys() {
51
+ if (this.foreignKeysEnforced) {
52
+ return;
53
+ }
54
+ await this.queued.database.execAsync(ENFORCE_FOREIGN_KEYS);
55
+ this.foreignKeysEnforced = true;
56
+ }
57
+ }
58
+ /**
59
+ * A raw SQL connection over an Expo SQLite database. Statements, transactions, and `close()` run
60
+ * one at a time in call order on the queue that every adapter store on the same database file
61
+ * shares, so a root statement never runs inside another caller's transaction. Transactions run
62
+ * `BEGIN IMMEDIATE` on the supplied handle, and the connection enables foreign keys before its
63
+ * first statement, so they stay enforced inside transactions.
64
+ */
65
+ export class ExpoSqliteConnection extends ScopedStatements {
66
+ root;
67
+ constructor(database, options = {}) {
68
+ const root = new ConnectionScope(new QueuedDatabase(database, options.closeDatabase === true));
69
+ super(root);
70
+ this.root = root;
71
+ }
72
+ /**
73
+ * Runs `work` in one transaction that commits when it resolves and rolls back when it rejects.
74
+ * Use only the transaction it receives: a root call on this file from inside `work` waits for
75
+ * the transaction, which waits for `work`, and neither finishes.
76
+ */
77
+ async transaction(work) {
78
+ this.root.assertAvailable();
79
+ return this.root.run((connection) => runTransaction(connection, work));
80
+ }
81
+ /** Rejects new work, waits for accepted work, and settles every caller with one result. */
82
+ close() {
83
+ return this.root.queued.close();
84
+ }
85
+ }
86
+ async function runTransaction(connection, work) {
87
+ await connection.execAsync(BEGIN);
88
+ const scope = new TransactionScope(connection);
89
+ try {
90
+ const result = await work(new ConnectionTransaction(scope));
91
+ await connection.execAsync(COMMIT);
92
+ return result;
93
+ }
94
+ catch (cause) {
95
+ await rollback(connection);
96
+ throw cause;
97
+ }
98
+ finally {
99
+ scope.finish();
100
+ }
101
+ }
102
+ /** Keeps the original failure when SQLite has already rolled the transaction back. */
103
+ async function rollback(connection) {
104
+ try {
105
+ await connection.execAsync(ROLLBACK);
106
+ }
107
+ catch {
108
+ return;
109
+ }
110
+ }
111
+ function variadic(params) {
112
+ return params;
113
+ }
114
+ //# sourceMappingURL=connection.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -1,59 +1,44 @@
1
- import { type JsonValue, type KeyValueStore, type Page, type PageOptions, type RecordStore, type ReentrantStorageTransaction, type SchemaMeta, type SchemaMetadataStore, type StoredRecord, type TransactionalStorageStore } from '@baukit/data-contracts';
2
- import type { SQLiteDatabase } from 'expo-sqlite';
3
- type SQLiteConnection = Pick<SQLiteDatabase, 'execAsync' | 'getAllAsync' | 'getFirstAsync' | 'runAsync'>;
4
- /** A namespaced Expo SQLite implementation of Baukit's provider-neutral RecordStore. */
5
- export declare class SqliteRecordStore<T extends StoredRecord> implements RecordStore<T> {
6
- private readonly database;
7
- private readonly namespace;
8
- private readonly assertAvailable;
9
- constructor(database: SQLiteConnection, namespace: string, assertAvailable?: () => void);
10
- /** Creates the shared adapter table if needed. Safe to call repeatedly. */
11
- initialize(): Promise<void>;
12
- put(record: T): Promise<void>;
13
- get(id: string): Promise<T | undefined>;
14
- delete(id: string): Promise<void>;
15
- list(options?: PageOptions): Promise<Page<T>>;
1
+ import { type KeyValueStore, type RecordStore, type ReentrantStorageTransaction, type SchemaMetadataStore, type StoredRecord, type TransactionalStorageStore } from '@baukit/data-contracts';
2
+ import { type ExpoSqliteDatabase, type SQLiteFileConnection } from './queued-database.js';
3
+ import { KeyValueStatements, RecordStatements, SchemaMetadataStatements } from './statements.js';
4
+ export type { ExpoSqliteDatabase } from './queued-database.js';
5
+ export { ExpoSqliteConnection, type ExpoSqliteConnectionOptions, type SqliteStatements, type SqliteTransaction, } from './connection.js';
6
+ /**
7
+ * A namespaced Expo SQLite implementation of Baukit's provider-neutral RecordStore.
8
+ * Statements share one queue with every adapter store that uses the same database file.
9
+ */
10
+ export declare class SqliteRecordStore<T extends StoredRecord> extends RecordStatements<T> {
11
+ constructor(database: SQLiteFileConnection, namespace: string);
16
12
  }
17
- /** Namespaced key/value storage used by the composite SQLite adapter. */
18
- export declare class SqliteKeyValueStore implements KeyValueStore {
19
- private readonly database;
20
- private readonly namespace;
21
- private readonly assertAvailable;
22
- constructor(database: SQLiteConnection, namespace: string, assertAvailable?: () => void);
23
- initialize(): Promise<void>;
24
- get(key: string): Promise<JsonValue | undefined>;
25
- set(key: string, value: JsonValue): Promise<void>;
26
- delete(key: string): Promise<void>;
27
- clear(): Promise<void>;
13
+ /** Namespaced key/value storage ordered with every adapter store on the same database file. */
14
+ export declare class SqliteKeyValueStore extends KeyValueStatements {
15
+ constructor(database: SQLiteFileConnection, namespace: string);
28
16
  }
29
- /** Namespaced portable schema metadata used by the composite SQLite adapter. */
30
- export declare class SqliteSchemaMetadataStore implements SchemaMetadataStore {
31
- private readonly database;
32
- private readonly namespace;
33
- private readonly assertAvailable;
34
- constructor(database: SQLiteConnection, namespace: string, assertAvailable?: () => void);
35
- initialize(): Promise<void>;
36
- getSchemaMeta(): Promise<SchemaMeta | undefined>;
37
- setSchemaMeta(metadata: SchemaMeta): Promise<void>;
17
+ /** Namespaced schema metadata ordered with every adapter store on the same database file. */
18
+ export declare class SqliteSchemaMetadataStore extends SchemaMetadataStatements {
19
+ constructor(database: SQLiteFileConnection, namespace: string);
38
20
  }
39
21
  export interface ExpoSqliteStoreOptions {
40
22
  /** Close the supplied database when this adapter closes. Defaults to false. */
41
23
  readonly closeDatabase?: boolean;
42
24
  }
43
- /** Complete namespaced adapter using Expo SQLite exclusive write transactions. */
25
+ /**
26
+ * Complete namespaced adapter using Expo SQLite exclusive write transactions.
27
+ * Root statements, transactions, and close run one at a time in call order, shared with every
28
+ * adapter store on the same database file.
29
+ */
44
30
  export declare class ExpoSqliteStore<T extends StoredRecord> implements TransactionalStorageStore<T> {
45
- private readonly database;
46
- private readonly options;
47
- readonly keyValues: SqliteKeyValueStore;
48
- readonly records: SqliteRecordStore<T>;
49
- readonly schemaMetadata: SqliteSchemaMetadataStore;
50
- private readonly lifecycle;
51
- private transactionTail;
52
- constructor(database: SQLiteDatabase, namespace: string, options?: ExpoSqliteStoreOptions);
53
31
  private readonly namespace;
32
+ readonly keyValues: KeyValueStore;
33
+ readonly records: RecordStore<T>;
34
+ readonly schemaMetadata: SchemaMetadataStore;
35
+ private readonly root;
36
+ private readonly queued;
37
+ constructor(database: ExpoSqliteDatabase, namespace: string, options?: ExpoSqliteStoreOptions);
54
38
  initialize(): Promise<void>;
55
39
  withTransaction<TResult>(operation: (context: ReentrantStorageTransaction<T>) => Promise<TResult> | TResult): Promise<TResult>;
40
+ /** Rejects new work, waits for accepted work, and settles every caller with one result. */
56
41
  close(): Promise<void>;
42
+ private runExclusive;
57
43
  }
58
- export {};
59
44
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,2BAA2B,EAChC,KAAK,UAAU,EACf,KAAK,mBAAmB,EAExB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAE/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD,KAAK,gBAAgB,GAAG,IAAI,CAC1B,cAAc,EACd,WAAW,GAAG,aAAa,GAAG,eAAe,GAAG,UAAU,CAC3D,CAAC;AAsBF,wFAAwF;AACxF,qBAAa,iBAAiB,CAAC,CAAC,SAAS,YAAY,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAE5E,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAFf,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,MAAM,IAAsB;IAOhE,2EAA2E;IAC9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAUvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAkB/D;AAED,yEAAyE;AACzE,qBAAa,mBAAoB,YAAW,aAAa;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAFf,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,MAAM,IAAsB;IAGnD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAUhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAMpC;AAED,gFAAgF;AAChF,qBAAa,yBAA0B,YAAW,mBAAmB;IAEjE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAFf,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,MAAM,IAAsB;IAGnD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,aAAa,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAShD,aAAa,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAYhE;AAqCD,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,kFAAkF;AAClF,qBAAa,eAAe,CAAC,CAAC,SAAS,YAAY,CAAE,YAAW,yBAAyB,CAAC,CAAC,CAAC;IAQxF,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,SAAgB,SAAS,EAAE,mBAAmB,CAAC;IAC/C,SAAgB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC9C,SAAgB,cAAc,EAAE,yBAAyB,CAAC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,eAAe,CAAoC;gBAGxC,QAAQ,EAAE,cAAc,EACzC,SAAS,EAAE,MAAM,EACA,OAAO,GAAE,sBAA2B;IAcvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEtB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,eAAe,CAAC,OAAO,EAClC,SAAS,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GACjF,OAAO,CAAC,OAAO,CAAC;IA6BN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAcpC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAE/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,kBAAkB,EAClB,gBAAgB,EAEhB,wBAAwB,EAGzB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAIzB;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,CAAC,SAAS,YAAY,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;gBAC7D,QAAQ,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM;CAGrE;AAED,+FAA+F;AAC/F,qBAAa,mBAAoB,SAAQ,kBAAkB;gBACtC,QAAQ,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM;CAGrE;AAED,6FAA6F;AAC7F,qBAAa,yBAA0B,SAAQ,wBAAwB;gBAClD,QAAQ,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM;CAGrE;AA+BD,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,YAAY,CAAE,YAAW,yBAAyB,CAAC,CAAC,CAAC;IASxF,OAAO,CAAC,QAAQ,CAAC,SAAS;IAR5B,SAAgB,SAAS,EAAE,aAAa,CAAC;IACzC,SAAgB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACxC,SAAgB,cAAc,EAAE,mBAAmB,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAGtC,QAAQ,EAAE,kBAAkB,EACX,SAAS,EAAE,MAAM,EAClC,OAAO,GAAE,sBAA2B;IAczB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,eAAe,CAAC,OAAO,EAClC,SAAS,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GACjF,OAAO,CAAC,OAAO,CAAC;IASnB,2FAA2F;IACpF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAIf,YAAY;CAkB3B"}