@delali/sirannon-db 0.2.0 → 0.2.1

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.
Files changed (75) hide show
  1. package/dist/backup-scheduler/index.d.ts +15 -1
  2. package/dist/backup-scheduler/index.mjs +2 -2
  3. package/dist/baseline-D93hcIEE.d.ts +17 -0
  4. package/dist/{change-tracker-DKRVUC3l.d.ts → change-tracker-DDmXB754.d.ts} +56 -8
  5. package/dist/{chunk-5NOIGN5Y.mjs → chunk-2QLXDHAP.mjs} +1 -1
  6. package/dist/{chunk-LNY2VVHE.mjs → chunk-7C36BCSN.mjs} +1 -1
  7. package/dist/{chunk-NVQS53NT.mjs → chunk-7FQRQH5Z.mjs} +53 -64
  8. package/dist/{chunk-D7LAYTKN.mjs → chunk-7R4ER4FB.mjs} +1 -1
  9. package/dist/{chunk-FHWTZFI4.mjs → chunk-BQFQ65OL.mjs} +1 -1
  10. package/dist/{chunk-O7SLN3GI.mjs → chunk-BTTFW4Z4.mjs} +1 -1
  11. package/dist/{chunk-H6PIVVDN.mjs → chunk-CCZK6LCB.mjs} +38 -25
  12. package/dist/{chunk-JZGINXTN.mjs → chunk-HCCGEIZ2.mjs} +2 -2
  13. package/dist/{chunk-67M7KAH6.mjs → chunk-IWGIYDMZ.mjs} +1 -1
  14. package/dist/{chunk-LFZ37BSX.mjs → chunk-OUSWVNWT.mjs} +1 -1
  15. package/dist/{chunk-HR5CWTLC.mjs → chunk-P2VJYRVY.mjs} +60 -7
  16. package/dist/{chunk-UC3SCMIN.mjs → chunk-PBRXXISQ.mjs} +3 -0
  17. package/dist/{chunk-JU64Y7HM.mjs → chunk-SBL6GN43.mjs} +1 -1
  18. package/dist/{chunk-EBJXPQQO.mjs → chunk-UPKKSUPA.mjs} +2 -2
  19. package/dist/{chunk-TJF5GZSV.mjs → chunk-VOSJBZ6Q.mjs} +1 -1
  20. package/dist/{chunk-PIKHN33N.mjs → chunk-VOYGMAU7.mjs} +9 -1
  21. package/dist/{chunk-H237TXZW.mjs → chunk-WJ67DTD6.mjs} +48 -6
  22. package/dist/{chunk-OQVZBEBY.mjs → chunk-XF2HH5E6.mjs} +4 -61
  23. package/dist/client/index.d.ts +211 -12
  24. package/dist/client/index.mjs +155 -67
  25. package/dist/client/topology.d.ts +55 -7
  26. package/dist/client/topology.mjs +20 -1
  27. package/dist/{client-base-CLWmH5Ln.d.ts → client-base-CmZO0v3m.d.ts} +133 -24
  28. package/dist/codegen/cli.mjs +3 -3
  29. package/dist/codegen/index.d.ts +92 -2
  30. package/dist/codegen/index.mjs +3 -3
  31. package/dist/core/index.d.ts +177 -15
  32. package/dist/core/index.mjs +2481 -2226
  33. package/dist/core/writer-worker.mjs +3 -3
  34. package/dist/database-B5Qv1-cU.d.ts +380 -0
  35. package/dist/driver/better-sqlite3.d.ts +18 -1
  36. package/dist/driver/better-sqlite3.mjs +5 -5
  37. package/dist/driver/bun.d.ts +28 -0
  38. package/dist/driver/expo.d.ts +17 -0
  39. package/dist/driver/node.d.ts +18 -1
  40. package/dist/driver/node.mjs +5 -5
  41. package/dist/driver/wa-sqlite.d.ts +18 -1
  42. package/dist/{errors-Bw5MdNCu.d.ts → errors-Dei4GdBb.d.ts} +80 -7
  43. package/dist/file-migrations/index.d.ts +54 -2
  44. package/dist/file-migrations/index.mjs +3 -3
  45. package/dist/{operation-registry-9DcvxcE5.d.ts → operation-registry-hlbhqu7q.d.ts} +50 -1
  46. package/dist/{primary-wins-DPAm2AKG.d.ts → primary-wins-B0np8JS3.d.ts} +25 -1
  47. package/dist/protocol-rqANt-9Q.d.ts +152 -0
  48. package/dist/query-types-DL3LtPvY.d.ts +95 -0
  49. package/dist/react/index.d.ts +58 -3
  50. package/dist/replication/coordinator/etcd.d.ts +63 -3
  51. package/dist/replication/coordinator/etcd.mjs +82 -46
  52. package/dist/replication/index.d.ts +329 -95
  53. package/dist/replication/index.mjs +256 -141
  54. package/dist/server/index.d.ts +230 -12
  55. package/dist/server/index.mjs +63 -50
  56. package/dist/{server-options-1JHu8pid.d.ts → server-options-Dab_Jvd_.d.ts} +96 -12
  57. package/dist/sirannon-CMhiJa5Y.d.ts +111 -0
  58. package/dist/transport/grpc.d.ts +93 -9
  59. package/dist/transport/grpc.mjs +63 -20
  60. package/dist/transport/memory.d.ts +50 -20
  61. package/dist/transport/memory.mjs +25 -0
  62. package/dist/{types-CL6piSnD.d.ts → types-BCejqzNA.d.ts} +20 -0
  63. package/dist/types-CMBcFPhb.d.ts +336 -0
  64. package/dist/types-CjhxcjhA.d.ts +123 -0
  65. package/dist/types-DyrCiWuc.d.ts +499 -0
  66. package/dist/types-rVZKnKN-.d.ts +591 -0
  67. package/package.json +7 -1
  68. package/dist/baseline-Br77Fnhb.d.ts +0 -6
  69. package/dist/database-BY0L5Q2n.d.ts +0 -172
  70. package/dist/protocol-6KrSq2Hy.d.ts +0 -66
  71. package/dist/sirannon-DaQSyhbJ.d.ts +0 -36
  72. package/dist/types-B7gmEsZW.d.ts +0 -221
  73. package/dist/types-BsVabqSI.d.ts +0 -139
  74. package/dist/types-C_D8IhpO.d.ts +0 -60
  75. package/dist/types-zhnRXrsb.d.ts +0 -384
@@ -0,0 +1,591 @@
1
+ import { P as Params, W as WriteConcern, R as ReadConcern, b as ChangeOperation, E as ExecuteResult, a as ReadConcernLevel } from './query-types-DL3LtPvY.js';
2
+
3
+ /** Context passed to query hooks.
4
+ * @public
5
+ */
6
+ interface QueryHookContext {
7
+ /** Identifier of the database the statement runs against. */
8
+ databaseId: string;
9
+ /** The statement about to run, or the one that just ran. */
10
+ sql: string;
11
+ /** Parameters bound to the statement. */
12
+ params?: Params;
13
+ /** Values a caller attached to the request for its own hooks to read. */
14
+ metadata?: Record<string, unknown>;
15
+ /** Acknowledgements this write waits for. */
16
+ writeConcern?: WriteConcern;
17
+ /** Currency this read requires. */
18
+ readConcern?: ReadConcern;
19
+ }
20
+ /** Hook invoked before a query is executed. Throw to deny.
21
+ * @public
22
+ */
23
+ type BeforeQueryHook = (ctx: QueryHookContext) => void | Promise<void>;
24
+ /** Hook invoked after a query is executed.
25
+ * @public
26
+ */
27
+ type AfterQueryHook = (ctx: QueryHookContext & {
28
+ durationMs: number;
29
+ }) => void | Promise<void>;
30
+ /** Context passed to connection hooks.
31
+ * @public
32
+ */
33
+ interface ConnectionHookContext {
34
+ /** Identifier of the database being opened or closed. */
35
+ databaseId: string;
36
+ /** File path of the SQLite database. */
37
+ path: string;
38
+ }
39
+ /** Hook invoked before a database connection is established.
40
+ * @public
41
+ */
42
+ type BeforeConnectHook = (ctx: ConnectionHookContext) => void | Promise<void>;
43
+ /** Hook invoked when a database is opened.
44
+ * @public
45
+ */
46
+ type DatabaseOpenHook = (ctx: ConnectionHookContext) => void | Promise<void>;
47
+ /** Hook invoked when a database is closed.
48
+ * @public
49
+ */
50
+ type DatabaseCloseHook = (ctx: ConnectionHookContext) => void | Promise<void>;
51
+ /** Hook invoked before a subscription is created. Throw to deny.
52
+ * @public
53
+ */
54
+ type BeforeSubscribeHook = (ctx: {
55
+ databaseId: string;
56
+ table: string;
57
+ filter?: Record<string, unknown>;
58
+ }) => void | Promise<void>;
59
+ /** Aggregated hook configuration.
60
+ * @public
61
+ */
62
+ interface HookConfig {
63
+ /** Runs before each statement. Throw to refuse it. */
64
+ onBeforeQuery?: BeforeQueryHook | BeforeQueryHook[];
65
+ /** Runs after each statement, with the time it took. */
66
+ onAfterQuery?: AfterQueryHook | AfterQueryHook[];
67
+ /** Runs before a database connection opens. */
68
+ onBeforeConnect?: BeforeConnectHook | BeforeConnectHook[];
69
+ /** Runs once a database is open. */
70
+ onDatabaseOpen?: DatabaseOpenHook | DatabaseOpenHook[];
71
+ /** Runs once a database is closed. */
72
+ onDatabaseClose?: DatabaseCloseHook | DatabaseCloseHook[];
73
+ /** Runs before a change subscription starts. Throw to refuse it. */
74
+ onBeforeSubscribe?: BeforeSubscribeHook | BeforeSubscribeHook[];
75
+ }
76
+
77
+ /** Metrics emitted after a query completes.
78
+ * @public
79
+ */
80
+ interface QueryMetrics {
81
+ /** Identifier of the database the statement ran against. */
82
+ databaseId: string;
83
+ /** The statement that ran. */
84
+ sql: string;
85
+ /** How long the statement took, in milliseconds. */
86
+ durationMs: number;
87
+ /** Number of rows a read returned. */
88
+ rowsReturned?: number;
89
+ /** Number of rows a write changed. */
90
+ changes?: number;
91
+ /** Set when the statement threw. */
92
+ error?: boolean;
93
+ }
94
+ /** Metrics emitted when a connection opens or closes.
95
+ * @public
96
+ */
97
+ interface ConnectionMetrics {
98
+ /** Identifier of the database whose connection opened or closed. */
99
+ databaseId: string;
100
+ /** File path of the SQLite database. */
101
+ path: string;
102
+ /** Number of read connections the pool holds. */
103
+ readerCount: number;
104
+ /** Whether the connection opened or closed. */
105
+ event: 'open' | 'close';
106
+ }
107
+ /** Metrics emitted when a CDC event is dispatched.
108
+ * @public
109
+ */
110
+ interface CDCMetrics {
111
+ /** Identifier of the database the change came from. */
112
+ databaseId: string;
113
+ /** Table the changed row belongs to. */
114
+ table: string;
115
+ /** Whether the row was inserted, updated, or deleted. */
116
+ operation: ChangeOperation;
117
+ /** Number of subscribers the event reached. */
118
+ subscriberCount: number;
119
+ }
120
+ /** Callbacks for metrics collection.
121
+ * @public
122
+ */
123
+ interface MetricsConfig {
124
+ /** Called once each statement finishes, whether it succeeded or threw. */
125
+ onQueryComplete?: (metrics: QueryMetrics) => void;
126
+ /** Called when a database connection opens. */
127
+ onConnectionOpen?: (metrics: ConnectionMetrics) => void;
128
+ /** Called when a database connection closes. */
129
+ onConnectionClose?: (metrics: ConnectionMetrics) => void;
130
+ /** Called each time a change event reaches its subscribers. */
131
+ onCDCEvent?: (metrics: CDCMetrics) => void;
132
+ }
133
+
134
+ /**
135
+ * Runs statements inside one transaction. A function passed to {@link Database.transaction} receives it.
136
+ *
137
+ * @public
138
+ */
139
+ declare class Transaction {
140
+ private readonly conn;
141
+ private _lastInsertRowId;
142
+ constructor(conn: SQLiteConnection);
143
+ /**
144
+ * Runs a read inside this transaction.
145
+ *
146
+ * @param sql - The statement to run.
147
+ * @param params - Values bound to the statement, named or positional.
148
+ * @returns The rows the statement produced.
149
+ */
150
+ query<T = Record<string, unknown>>(sql: string, params?: Params): Promise<T[]>;
151
+ /**
152
+ * Runs one write inside this transaction.
153
+ *
154
+ * @param sql - The statement to run.
155
+ * @param params - Values bound to the statement, named or positional.
156
+ * @returns How many rows changed, and the last inserted row id.
157
+ */
158
+ execute(sql: string, params?: Params): Promise<ExecuteResult>;
159
+ /**
160
+ * Runs one statement over many parameter sets inside this transaction.
161
+ *
162
+ * @param sql - The statement to run for each parameter set.
163
+ * @param paramsBatch - One parameter set per run.
164
+ * @returns One result per parameter set, in order.
165
+ */
166
+ executeBatch(sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
167
+ /**
168
+ * Row id SQLite assigned to the last row this transaction inserted.
169
+ */
170
+ get lastInsertRowId(): number | bigint;
171
+ /** @internal */
172
+ static run<T>(conn: SQLiteConnection, fn: (tx: Transaction) => Promise<T>): Promise<T>;
173
+ }
174
+
175
+ /** Characters a migration name may use: letters, digits, and underscores.
176
+ * @public
177
+ */
178
+ declare const MIGRATION_NAME_RE: RegExp;
179
+ /** One migration a database has already applied, as recorded in its catalogue.
180
+ * @public
181
+ */
182
+ interface AppliedMigration {
183
+ /** Version number of the migration. */
184
+ version: number;
185
+ /** Name of the migration. */
186
+ name: string;
187
+ /** Milliseconds since the Unix epoch, taken when the migration was applied. */
188
+ applied_at: number;
189
+ }
190
+ /**
191
+ * Marks a migration as the point an existing database starts from, so the
192
+ * runner records every earlier version as applied without running it.
193
+ *
194
+ * @public
195
+ */
196
+ interface MigrationBaseline {
197
+ /** Highest version this baseline covers. */
198
+ through: number;
199
+ }
200
+ /** One schema change, with the statements that apply it and the statements that undo it.
201
+ * @public
202
+ */
203
+ interface Migration {
204
+ /** Version number. The runner applies migrations in ascending order. */
205
+ version: number;
206
+ /** Name of the migration, using letters, digits, and underscores. */
207
+ name: string;
208
+ /** SQL that applies the change, or a function that runs it inside the migration's transaction. */
209
+ up: string | ((tx: Transaction) => void | Promise<void>);
210
+ /** SQL that undoes the change, or a function that runs it. A migration without this cannot roll back. */
211
+ down?: string | ((tx: Transaction) => void | Promise<void>);
212
+ /** Marks this migration as the point an existing database starts from. */
213
+ baseline?: MigrationBaseline;
214
+ }
215
+ /** Migrations to apply, either as an array or as a function that produces one.
216
+ * @public
217
+ */
218
+ type MigrationSource = Migration[] | (() => Migration[] | Promise<Migration[]>);
219
+ /** One migration named in a migration or rollback result.
220
+ * @public
221
+ */
222
+ interface AppliedMigrationEntry {
223
+ /** Version number of the migration. */
224
+ version: number;
225
+ /** Name of the migration. */
226
+ name: string;
227
+ }
228
+ /** What one call to migrate did.
229
+ * @public
230
+ */
231
+ interface MigrationResult {
232
+ /** Migrations this call applied, in the order it applied them. */
233
+ applied: AppliedMigrationEntry[];
234
+ /** Number of migrations the database had already applied. */
235
+ skipped: number;
236
+ }
237
+ /** What one call to roll back did.
238
+ * @public
239
+ */
240
+ interface RollbackResult {
241
+ /** Migrations this call undid, newest first. */
242
+ rolledBack: AppliedMigrationEntry[];
243
+ }
244
+
245
+ /** One node a client can read from, and the read concerns it currently serves.
246
+ * @public
247
+ */
248
+ interface ClusterReadEndpointInfo {
249
+ /** Identifier of the node behind this endpoint. */
250
+ nodeId: string;
251
+ /** Address a client sends its reads to. */
252
+ endpoint: string;
253
+ /** Read concerns this node meets right now. */
254
+ readConcerns: ReadConcernLevel[];
255
+ }
256
+ /** The single word describing what a node can do right now.
257
+ * @public
258
+ */
259
+ type NodeHealthState = 'healthy' | 'degraded' | 'failing_over' | 'repairing' | 'syncing' | 'unavailable';
260
+ /** The condition that produced a {@link NodeHealthState}.
261
+ * @public
262
+ */
263
+ type NodeHealthReason = 'in-sync' | 'lagging' | 'coordinator-unreachable' | 'draining' | 'repairing' | 'faulted' | 'sync-pending' | 'no-group-state';
264
+ /**
265
+ * The health of one node, covering only the node that reports it.
266
+ *
267
+ * `canRead` and `canWrite` are what that node will accept at this moment;
268
+ * `state` and `reason` name the condition behind them.
269
+ *
270
+ * @public
271
+ */
272
+ interface NodeHealth {
273
+ /** What the node can do right now. */
274
+ state: NodeHealthState;
275
+ /** The condition behind that state. */
276
+ reason: NodeHealthReason;
277
+ /** Whether the node serves reads at this moment. */
278
+ canRead: boolean;
279
+ /** Whether the node accepts writes at this moment. */
280
+ canWrite: boolean;
281
+ }
282
+ /** What one node reports about its replication group, as served by `GET /db/{id}/cluster`.
283
+ * @public
284
+ */
285
+ interface ClusterStatusInfo {
286
+ /** Identifier of the database this status describes. */
287
+ databaseId: string;
288
+ /** Identifier of the replication group the node belongs to. */
289
+ replicationGroupId?: string;
290
+ /** Whether this node accepts writes or serves reads. */
291
+ role?: 'primary' | 'replica';
292
+ /** The primary this node reports as current, or null when it has none. */
293
+ currentPrimary?: {
294
+ nodeId: string;
295
+ endpoint?: string;
296
+ } | null;
297
+ /** The primary term this node reports as current. */
298
+ primaryTerm?: bigint;
299
+ /** Every node a client can read from, with the read concerns each one serves. */
300
+ readEndpoints?: ClusterReadEndpointInfo[];
301
+ /** What this node can do right now. */
302
+ health: NodeHealthState;
303
+ /** The condition behind that health. */
304
+ healthReason: NodeHealthReason;
305
+ }
306
+ /** Configuration for automatic database lifecycle management.
307
+ * @public
308
+ */
309
+ interface LifecycleConfig {
310
+ /** Opens a database the first time someone asks for an identifier the registry has not seen. */
311
+ autoOpen?: {
312
+ resolver: (id: string) => {
313
+ path: string;
314
+ options?: DatabaseOptions;
315
+ } | undefined;
316
+ };
317
+ /** Milliseconds before an idle database is closed. 0 = disabled. */
318
+ idleTimeout?: number;
319
+ /** Maximum number of concurrently open databases. 0 = unlimited. */
320
+ maxOpen?: number;
321
+ }
322
+ /** Options for opening a single database.
323
+ * @public
324
+ */
325
+ interface DatabaseOptions {
326
+ /** Open the database in read-only mode. */
327
+ readOnly?: boolean;
328
+ /** Number of read connections in the pool. Default: 4. */
329
+ readPoolSize?: number;
330
+ /** Enable WAL mode. Default: true. */
331
+ walMode?: boolean;
332
+ /**
333
+ * Writer durability (`PRAGMA synchronous`). Default: 'normal'. This is the
334
+ * level restored after every bulk load, whatever the load relaxed it to.
335
+ */
336
+ synchronous?: SynchronousLevel;
337
+ /** CDC polling interval in milliseconds. Default: 50. */
338
+ cdcPollInterval?: number;
339
+ /** CDC retention period in milliseconds. Default: 3_600_000 (1 hour). */
340
+ cdcRetention?: number;
341
+ /**
342
+ * Run writes on a dedicated worker thread so disk flushes never block the
343
+ * thread serving connections; reads stay on the calling thread. Requires a
344
+ * driver with a worker entry (the `better-sqlite3` and `node` drivers have
345
+ * one), otherwise opening throws. Default: off.
346
+ */
347
+ writerWorker?: boolean | WriterWorkerOptions;
348
+ }
349
+ /** Limits and recovery settings for the thread that runs writes.
350
+ * @public
351
+ */
352
+ interface WriterWorkerOptions {
353
+ /** Writes allowed in flight before new writes are rejected with a busy signal. Default: 1024. */
354
+ maxPendingWrites?: number;
355
+ /** Per-operation deadline in ms; when an operation stalls past it, its caller is rejected loudly while the worker keeps running, so a stalled write's outcome is indeterminate. 0 disables it. Default: 30000. */
356
+ writeTimeoutMs?: number;
357
+ /** Restarts the worker this many times after it crashes on its own before writes fail permanently. Default: 5. */
358
+ maxRestarts?: number;
359
+ }
360
+ /** Top-level options for the Sirannon database registry.
361
+ * @public
362
+ */
363
+ interface SirannonOptions {
364
+ /** SQLite driver every database in this registry opens through. */
365
+ driver: SQLiteDriver;
366
+ /** Lifecycle hooks that run for every database in this registry. */
367
+ hooks?: HookConfig;
368
+ /** Callbacks that receive statement, connection, and change-capture metrics. */
369
+ metrics?: MetricsConfig;
370
+ /** Automatic opening, idle eviction, and the limit on concurrently open databases. */
371
+ lifecycle?: LifecycleConfig;
372
+ /** Migrations every database in this registry applies when it opens. */
373
+ migrations?: MigrationSource;
374
+ /** Default writer-worker setting for the databases this registry opens. */
375
+ writerWorker?: boolean | WriterWorkerOptions;
376
+ }
377
+ /** Options for scheduled backups.
378
+ * @public
379
+ */
380
+ interface BackupScheduleOptions {
381
+ /** Cron expression (e.g., '0 * * * *' for hourly). */
382
+ cron: string;
383
+ /** Directory to store backup files. */
384
+ destDir: string;
385
+ /** Maximum number of backup files to keep. Default: 5. */
386
+ maxFiles?: number;
387
+ /**
388
+ * Sirannon evaluates the cron expression in this IANA time zone (e.g. 'America/New_York').
389
+ * When omitted, it uses the host's local time zone, which also sets the daylight saving rules that apply.
390
+ */
391
+ timezone?: string;
392
+ /** Called when a scheduled backup fails. Without this, errors are silently discarded. */
393
+ onError?: (error: Error) => void;
394
+ }
395
+
396
+ interface WorkerHostOptions {
397
+ writeTimeoutMs?: number;
398
+ maxRestarts?: number;
399
+ }
400
+
401
+ /** What one write reports back through the driver.
402
+ * @public
403
+ */
404
+ interface RunResult {
405
+ /** Number of rows the statement inserted, updated, or deleted. */
406
+ changes: number;
407
+ /** Row id SQLite assigned to the last inserted row. */
408
+ lastInsertRowId: number | bigint;
409
+ }
410
+ /**
411
+ * Tells a caller running inside the operation that holds the writer from one
412
+ * merely waiting on it. A runtime without async context tracking cannot answer
413
+ * this, and answering it wrongly runs one caller's writes inside another
414
+ * caller's transaction.
415
+ */
416
+ interface WriterContext {
417
+ /** Runs an operation marked as the one holding the writer. */
418
+ run<T>(operation: () => T): T;
419
+ /** Reports whether the caller is the operation holding the writer. */
420
+ isActive(): boolean;
421
+ /** Runs an operation outside the held writer, so its writes stay out of that transaction. */
422
+ exit<T>(operation: () => T): T;
423
+ }
424
+ /**
425
+ * Copies a database to a file, and repeats that copy on a schedule.
426
+ *
427
+ * @internal
428
+ */
429
+ interface BackupEngine {
430
+ /** Copies the database behind a connection to a destination path. */
431
+ backup(conn: SQLiteConnection, destPath: string): Promise<void>;
432
+ /** Starts a repeating backup and returns a function that stops it. */
433
+ schedule(conn: SQLiteConnection, options: BackupScheduleOptions, runExclusive: (op: () => Promise<void>) => Promise<void>): () => void;
434
+ }
435
+ /** Totals for one statement applied over many parameter sets.
436
+ * @public
437
+ */
438
+ interface BatchSummary {
439
+ /** Number of parameter sets the driver applied. */
440
+ rowsLoaded: number;
441
+ /** Number of rows those statements inserted, updated, or deleted. */
442
+ changes: number;
443
+ }
444
+ /** One prepared statement a driver hands back, ready to run many times.
445
+ * @public
446
+ */
447
+ interface SQLiteStatement {
448
+ /** Runs the statement and returns every row. */
449
+ all<T = unknown>(...params: unknown[]): Promise<T[]>;
450
+ /** Runs the statement and returns the first row, or undefined when there is none. */
451
+ get<T = unknown>(...params: unknown[]): Promise<T | undefined>;
452
+ /** Runs the statement as a write and reports what it changed. */
453
+ run(...params: unknown[]): Promise<RunResult>;
454
+ /**
455
+ * Like {@link SQLiteStatement.all} but skips the safe-range BigInt narrowing, leaving every
456
+ * integer as a BigInt. The server wire path narrows and tags in one pass, so
457
+ * feeding it raw rows avoids a second walk. Optional: a driver that omits it
458
+ * falls back to {@link SQLiteStatement.all}, still correct but with the extra narrowing walk.
459
+ */
460
+ allRaw?<T = unknown>(...params: unknown[]): Promise<T[]>;
461
+ }
462
+ /**
463
+ * Why one unit of a grouped run failed.
464
+ *
465
+ * @internal
466
+ */
467
+ interface GroupRunError {
468
+ /** Message SQLite or the driver raised. */
469
+ message: string;
470
+ /** Name of the error class. */
471
+ name?: string;
472
+ /** Machine-readable code, where the driver supplies one. */
473
+ code?: string;
474
+ }
475
+ /**
476
+ * What one unit of a grouped run produced.
477
+ *
478
+ * @internal
479
+ */
480
+ type GroupRunOutcome = {
481
+ ok: true;
482
+ results: RunResult[];
483
+ } | {
484
+ ok: false;
485
+ error: GroupRunError;
486
+ };
487
+ /** One open connection to a SQLite database.
488
+ * @public
489
+ */
490
+ interface SQLiteConnection {
491
+ /** Runs one or more statements and returns no rows. */
492
+ exec(sql: string): Promise<void>;
493
+ /** Compiles a statement so the caller can run it many times. */
494
+ prepare(sql: string): Promise<SQLiteStatement>;
495
+ /** Runs a function inside one transaction, committing when it returns and rolling back when it throws. */
496
+ transaction<T>(fn: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
497
+ /** Closes the connection. */
498
+ close(): Promise<void>;
499
+ /** Optional fast path that applies one statement over many parameter sets. */
500
+ runBatch?(sql: string, paramsBatch: readonly unknown[][]): Promise<RunResult[]>;
501
+ /** Optional fast path that applies one statement over many parameter sets and returns only the totals. */
502
+ runBatchSummary?(sql: string, paramsBatch: readonly unknown[][]): Promise<BatchSummary>;
503
+ /**
504
+ * Runs several independent units in one transaction, one outcome per unit in
505
+ * order. A unit is one write or one whole transaction, and a unit that fails
506
+ * must not disturb the others.
507
+ */
508
+ runGroup?(units: readonly {
509
+ statements: readonly {
510
+ sql: string;
511
+ params?: readonly unknown[];
512
+ trusted?: boolean;
513
+ }[];
514
+ }[]): Promise<GroupRunOutcome[]>;
515
+ }
516
+ /**
517
+ * SQLite `PRAGMA synchronous` level applied to a connection. `normal` is safe
518
+ * from corruption in WAL mode but can lose the most recent commits on power
519
+ * loss; `full` fsyncs every commit; `extra` adds a directory sync after the
520
+ * rollback journal is unlinked in DELETE journal mode and equals `full` in
521
+ * WAL mode; `off` hands writes to the OS without syncing and is sanctioned
522
+ * only for re-runnable bulk loads.
523
+ *
524
+ * @public
525
+ */
526
+ type SynchronousLevel = 'off' | 'normal' | 'full' | 'extra';
527
+ /** How a driver opens one database file.
528
+ * @public
529
+ */
530
+ interface OpenOptions {
531
+ /** Opens the file for reads only. */
532
+ readonly?: boolean;
533
+ /** Puts the database in write-ahead logging mode. */
534
+ walMode?: boolean;
535
+ /** Writer durability the connection runs at. */
536
+ synchronous?: SynchronousLevel;
537
+ }
538
+ /** What a driver's runtime supports.
539
+ * @public
540
+ */
541
+ interface DriverCapabilities {
542
+ /** Whether the runtime opens more than one connection to the same file. */
543
+ multipleConnections: boolean;
544
+ /** Whether the runtime loads SQLite extensions. */
545
+ extensions: boolean;
546
+ }
547
+ /**
548
+ * Lets a worker thread rebuild the driver, since the driver's `open` function
549
+ * cannot cross the thread boundary. `specifier` must be importable from the
550
+ * worker and `config` must survive a structured clone; the worker imports the
551
+ * module and calls its `exportName` factory (default export otherwise) with it.
552
+ *
553
+ * @public
554
+ */
555
+ interface DriverWorkerEntry {
556
+ /** Module the worker imports to rebuild the driver. */
557
+ specifier: string;
558
+ /** Named export the worker calls, or the default export when absent. */
559
+ exportName?: string;
560
+ /** Value passed to that factory, which must survive a structured clone. */
561
+ config?: unknown;
562
+ }
563
+ /** How Sirannon opens SQLite on one runtime.
564
+ * @public
565
+ */
566
+ interface SQLiteDriver {
567
+ /** What this driver's runtime supports. */
568
+ readonly capabilities: DriverCapabilities;
569
+ /** Opens a database file and returns a connection to it. */
570
+ open(path: string, options?: OpenOptions): Promise<SQLiteConnection>;
571
+ /** How a worker thread rebuilds this driver. */
572
+ readonly worker?: DriverWorkerEntry;
573
+ /**
574
+ * Offloads writes to a worker thread. Only a driver whose runtime has
575
+ * threads implements this, which is what keeps the thread machinery out of
576
+ * bundles built for runtimes that do not.
577
+ */
578
+ startWriterHost?(path: string, options: OpenOptions, hostOptions?: WorkerHostOptions): Promise<SQLiteConnection>;
579
+ /** Builds the tracker that tells the caller holding the writer from one waiting on it. */
580
+ createWriterContext?(): WriterContext;
581
+ /** Builds the engine that copies a database to a file. */
582
+ createBackupEngine?(): BackupEngine;
583
+ /**
584
+ * Makes an extension path absolute. Passing a bare name to `load_extension`
585
+ * would let the dynamic linker search its own paths and open a different
586
+ * library than the operator named.
587
+ */
588
+ resolveExtensionPath?(extensionPath: string): string;
589
+ }
590
+
591
+ export { type AfterQueryHook as A, type BeforeQueryHook as B, type ClusterStatusInfo as C, type DatabaseOptions as D, type SQLiteStatement as E, type WriterWorkerOptions as F, type HookConfig as H, type LifecycleConfig as L, type Migration as M, type NodeHealth as N, type OpenOptions as O, type QueryHookContext as Q, type RollbackResult as R, type SirannonOptions as S, Transaction as T, type WorkerHostOptions as W, type SQLiteDriver as a, type BeforeConnectHook as b, type DatabaseOpenHook as c, type DatabaseCloseHook as d, type SQLiteConnection as e, type BackupScheduleOptions as f, type ConnectionHookContext as g, type BeforeSubscribeHook as h, type MetricsConfig as i, type QueryMetrics as j, type ConnectionMetrics as k, type CDCMetrics as l, type MigrationResult as m, type SynchronousLevel as n, type AppliedMigration as o, type AppliedMigrationEntry as p, type BatchSummary as q, type ClusterReadEndpointInfo as r, type DriverCapabilities as s, type DriverWorkerEntry as t, MIGRATION_NAME_RE as u, type MigrationBaseline as v, type MigrationSource as w, type NodeHealthReason as x, type NodeHealthState as y, type RunResult as z };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@delali/sirannon-db",
3
3
  "type": "module",
4
- "version": "0.2.0",
4
+ "version": "0.2.1",
5
5
  "description": "A production-grade library that turns SQLite databases into a networked data layer with real-time subscriptions.",
6
6
  "author": "Delali (https://sondelali.com)",
7
7
  "license": "Apache-2.0",
@@ -41,6 +41,7 @@
41
41
  "import": "./dist/driver/node.mjs"
42
42
  },
43
43
  "./driver/bun": {
44
+ "types": "./dist/driver/bun.d.ts",
44
45
  "import": "./dist/driver/bun.mjs"
45
46
  },
46
47
  "./driver/wa-sqlite": {
@@ -48,6 +49,7 @@
48
49
  "import": "./dist/driver/wa-sqlite.mjs"
49
50
  },
50
51
  "./driver/expo": {
52
+ "types": "./dist/driver/expo.d.ts",
51
53
  "import": "./dist/driver/expo.mjs"
52
54
  },
53
55
  "./file-migrations": {
@@ -162,6 +164,7 @@
162
164
  "devDependencies": {
163
165
  "@bufbuild/protobuf": "2.11.0",
164
166
  "@grpc/grpc-js": "1.14.4",
167
+ "@microsoft/api-extractor": "7.58.12",
165
168
  "@types/better-sqlite3": "7.6.13",
166
169
  "@types/node": "26.1.2",
167
170
  "@types/react": "19.2.15",
@@ -169,6 +172,7 @@
169
172
  "@vitest/coverage-v8": "4.0.18",
170
173
  "better-sqlite3": "13.0.2",
171
174
  "etcd3": "1.1.2",
175
+ "expo-sqlite": "55.0.10",
172
176
  "grpc-health-check": "2.1.0",
173
177
  "grpc-tools": "1.13.1",
174
178
  "jsdom": "29.1.1",
@@ -186,6 +190,8 @@
186
190
  "build": "rm -rf dist && tsup",
187
191
  "check:bundle": "node scripts/assert-browser-bundle.mjs",
188
192
  "check:types": "node scripts/assert-consumer-types.mjs",
193
+ "check:api": "node scripts/assert-api-reports.mjs",
194
+ "api:update": "node scripts/assert-api-reports.mjs --update",
189
195
  "test": "vitest run",
190
196
  "test:coverage": "vitest run --coverage",
191
197
  "test:e2e": "vitest run --config vitest.e2e.config.ts",
@@ -1,6 +0,0 @@
1
- interface BaselineFileOption {
2
- version: number;
3
- through: number;
4
- }
5
-
6
- export type { BaselineFileOption as B };