@ocap/statedb-sqlite 1.30.24 → 1.30.25

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/esm/db.d.mts CHANGED
@@ -2,10 +2,21 @@ import { Database } from "./interfaces.mjs";
2
2
  import { SqliteConfig } from "./kysely.mjs";
3
3
  import { StateDB } from "@ocap/statedb";
4
4
  import { Kysely, Transaction } from "kysely";
5
- import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITxState } from "@ocap/types";
5
+ import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITrustedStorage, ITxState } from "@ocap/types";
6
6
 
7
7
  //#region src/db.d.ts
8
-
8
+ interface SqliteRunOptions {
9
+ retryLimit?: number;
10
+ verifyHash?: boolean;
11
+ cleanWorkingSet?: boolean;
12
+ commitMessage?: string;
13
+ context?: unknown;
14
+ onCommit?: (commitHash?: string) => void | Promise<void>;
15
+ }
16
+ interface TrustedStorageLike extends ITrustedStorage {
17
+ initStorage?: () => Promise<void>;
18
+ destroy?: () => Promise<void>;
19
+ }
9
20
  /**
10
21
  * SQLite StateDB Implementation
11
22
  * Uses SQLite via Kysely as the storage backend
@@ -13,9 +24,19 @@ import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainSt
13
24
  declare class SqliteStateDB extends StateDB implements IStateDB {
14
25
  name: string;
15
26
  version: string;
27
+ trustedStorage?: TrustedStorageLike;
16
28
  private db;
17
29
  private config;
18
30
  private initialized;
31
+ private stateCommitTableReady;
32
+ private trustedInitialized;
33
+ private commitQueue;
34
+ private walEnabled;
35
+ private walCheckpointIntervalMs?;
36
+ private walCheckpointTimer;
37
+ private walCheckpointPromise;
38
+ private _activeLambdaCount;
39
+ private closed;
19
40
  balance: IBalanceTable;
20
41
  account: IStateTable<IAccountState>;
21
42
  factory: IStateTable<IAssetFactoryState>;
@@ -52,30 +73,53 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
52
73
  */
53
74
  private initSync;
54
75
  /**
55
- * Async initialization - runs migrations
76
+ * Async initialization - runs migrations and initializes trustedStorage if configured
56
77
  * Call this after constructor to ensure database schema is ready
57
78
  */
58
79
  initialize(): Promise<void>;
80
+ /**
81
+ * Run a WAL checkpoint (`PRAGMA wal_checkpoint(<mode>)`) against the SQLite database.
82
+ * No-op returning `{ busy: 0, log: 0, checkpointed: 0 }` when WAL mode is disabled.
83
+ */
84
+ runWalCheckpoint(mode?: 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE'): Promise<{
85
+ busy: number;
86
+ log: number;
87
+ checkpointed: number;
88
+ }>;
89
+ private startWalCheckpointWorker;
90
+ private ensureStateCommitTable;
91
+ private ensureTrustedStorageInitialized;
92
+ /**
93
+ * Get the current and previous state commit hash tracked in SQLite StateDB.
94
+ *
95
+ * Note on threat model & performance:
96
+ * SQLite StateDB maintains an O(1) incremental commit-chain head (`_state_commit`)
97
+ * to detect snapshot rollback or crash desynchronization between `statedb` and
98
+ * `trustedStorage` without O(N) full-table scans on every transaction.
99
+ * End-to-end Data Availability, Merkle inclusion proofs, and corruption detection
100
+ * for RPC, Light Wallet, and Archive nodes are enforced by `@arcblock/ledger`
101
+ * checkpoints and self-verifying segments.
102
+ */
103
+ getCommitHash(executor?: Kysely<Database> | Transaction<Database>): Promise<{
104
+ currentHash: string;
105
+ prevHash: string;
106
+ }>;
107
+ private verifyTrustedHashInternal;
108
+ /**
109
+ * Verify that the current SQLite state commit hash matches the trusted storage record.
110
+ */
111
+ verifyTrustedHash(): Promise<void>;
112
+ private enqueueCommit;
59
113
  /**
60
114
  * Execute multiple operations within a database transaction
61
115
  * Provides retry logic for SQLite BUSY errors (lock conflicts)
62
116
  *
63
117
  * @param fn - Function receiving Kysely transaction object
64
- * @param options - Optional retry configuration
118
+ * @param options - Optional retry and trusted-hash verification configuration
65
119
  * @returns Result of the transaction function
66
- *
67
- * @example
68
- * ```typescript
69
- * await db.runAsLambda(async (txn) => {
70
- * await txn.insertInto('account').values({ ... }).execute();
71
- * await txn.updateTable('balance').set({ ... }).execute();
72
- * });
73
- * ```
74
120
  */
75
- runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: {
76
- retryLimit?: number;
77
- onCommit?: (commitHash?: string) => void | Promise<void>;
78
- }): Promise<T>;
121
+ runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: SqliteRunOptions): Promise<T>;
122
+ private executeRunAsLambda;
79
123
  /**
80
124
  * Reset all tables (for testing)
81
125
  */
@@ -90,4 +134,4 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
90
134
  getKysely(): Kysely<Database>;
91
135
  }
92
136
  //#endregion
93
- export { SqliteStateDB as default };
137
+ export { SqliteRunOptions, SqliteStateDB as default };
package/esm/db.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { createKysely } from "./kysely.mjs";
1
+ import { createKysely, resolveWalCheckpointIntervalMs } from "./kysely.mjs";
2
2
  import { runMigrations } from "./migrations/index.mjs";
3
3
  import base_default from "./table/base.mjs";
4
4
  import account_default from "./table/account.mjs";
@@ -6,7 +6,9 @@ import balance_default from "./table/balance.mjs";
6
6
  import rollup_default from "./table/rollup.mjs";
7
7
  import token_default from "./table/token.mjs";
8
8
  import package_default from "./package.mjs";
9
+ import crypto from "node:crypto";
9
10
  import { StateDB } from "@ocap/statedb";
11
+ import { sql } from "kysely";
10
12
 
11
13
  //#region src/db.ts
12
14
  const { name, version } = package_default;
@@ -35,9 +37,18 @@ var SqliteStateDB = class extends StateDB {
35
37
  constructor(config = { filename: ":memory:" }) {
36
38
  super();
37
39
  this.initialized = false;
40
+ this.stateCommitTableReady = false;
41
+ this.trustedInitialized = false;
42
+ this.commitQueue = Promise.resolve();
43
+ this.walEnabled = false;
44
+ this.walCheckpointTimer = null;
45
+ this.walCheckpointPromise = null;
46
+ this._activeLambdaCount = 0;
47
+ this.closed = false;
38
48
  this.name = name;
39
49
  this.version = version;
40
50
  this.config = config;
51
+ this.trustedStorage = config.trustedStorage;
41
52
  this.initSync();
42
53
  }
43
54
  /**
@@ -46,6 +57,9 @@ var SqliteStateDB = class extends StateDB {
46
57
  */
47
58
  initSync() {
48
59
  this.db = createKysely(this.config);
60
+ const filename = this.config.filename || ":memory:";
61
+ this.walEnabled = !this.config.doStorage && !this.config.dialect && this.config.walMode !== false && !this.config.readonly && filename !== ":memory:";
62
+ this.walCheckpointIntervalMs = resolveWalCheckpointIntervalMs(this.config);
49
63
  this.balance = new balance_default({ db: this.db });
50
64
  this.account = new account_default({
51
65
  db: this.db,
@@ -190,48 +204,206 @@ var SqliteStateDB = class extends StateDB {
190
204
  this.attachReadyListeners();
191
205
  }
192
206
  /**
193
- * Async initialization - runs migrations
207
+ * Async initialization - runs migrations and initializes trustedStorage if configured
194
208
  * Call this after constructor to ensure database schema is ready
195
209
  */
196
210
  async initialize() {
197
- if (this.initialized) return;
211
+ this.closed = false;
212
+ if (this.initialized) {
213
+ if (this.trustedStorage && !this.trustedInitialized) await this.ensureTrustedStorageInitialized();
214
+ this.startWalCheckpointWorker();
215
+ return;
216
+ }
198
217
  await runMigrations(this.db);
199
218
  this.initialized = true;
219
+ if (this.trustedStorage) await this.ensureTrustedStorageInitialized();
220
+ this.startWalCheckpointWorker();
221
+ }
222
+ /**
223
+ * Run a WAL checkpoint (`PRAGMA wal_checkpoint(<mode>)`) against the SQLite database.
224
+ * No-op returning `{ busy: 0, log: 0, checkpointed: 0 }` when WAL mode is disabled.
225
+ */
226
+ async runWalCheckpoint(mode = "PASSIVE") {
227
+ if (!this.walEnabled || this.closed) return {
228
+ busy: 0,
229
+ log: 0,
230
+ checkpointed: 0
231
+ };
232
+ const safeMode = mode === "FULL" || mode === "RESTART" || mode === "TRUNCATE" ? mode : "PASSIVE";
233
+ if (this.walCheckpointPromise) {
234
+ if (safeMode === "PASSIVE") return this.walCheckpointPromise;
235
+ while (this.walCheckpointPromise) try {
236
+ await this.walCheckpointPromise;
237
+ } catch {}
238
+ if (!this.walEnabled || this.closed) return {
239
+ busy: 0,
240
+ log: 0,
241
+ checkpointed: 0
242
+ };
243
+ }
244
+ const run = (async () => {
245
+ try {
246
+ const row = (await sql`
247
+ ${sql.raw(`PRAGMA wal_checkpoint(${safeMode})`)}
248
+ `.execute(this.db)).rows[0];
249
+ return {
250
+ busy: Number(row?.busy ?? 0),
251
+ log: Number(row?.log ?? 0),
252
+ checkpointed: Number(row?.checkpointed ?? 0)
253
+ };
254
+ } finally {
255
+ if (this.walCheckpointPromise === run) this.walCheckpointPromise = null;
256
+ }
257
+ })();
258
+ this.walCheckpointPromise = run;
259
+ return run;
260
+ }
261
+ startWalCheckpointWorker() {
262
+ if (!this.walEnabled || !this.walCheckpointIntervalMs || this.walCheckpointTimer || this.closed) return;
263
+ this.walCheckpointTimer = setInterval(() => {
264
+ if (this.closed || this._activeLambdaCount > 0 || this.walCheckpointPromise) return;
265
+ this.runWalCheckpoint("PASSIVE").catch(() => {});
266
+ }, this.walCheckpointIntervalMs);
267
+ if (typeof this.walCheckpointTimer.unref === "function") this.walCheckpointTimer.unref();
268
+ }
269
+ async ensureStateCommitTable() {
270
+ if (this.stateCommitTableReady) return;
271
+ await sql`
272
+ CREATE TABLE IF NOT EXISTS "_state_commit" (
273
+ "id" INTEGER PRIMARY KEY CHECK ("id" = 1),
274
+ "current_hash" TEXT NOT NULL,
275
+ "prev_hash" TEXT NOT NULL,
276
+ "seq" INTEGER NOT NULL DEFAULT 0,
277
+ "msg" TEXT NOT NULL DEFAULT ''
278
+ )
279
+ `.execute(this.db);
280
+ await sql`
281
+ INSERT OR IGNORE INTO "_state_commit" ("id", "current_hash", "prev_hash", "seq", "msg")
282
+ VALUES (1, 'GENESIS', '', 0, '')
283
+ `.execute(this.db);
284
+ this.stateCommitTableReady = true;
285
+ }
286
+ async ensureTrustedStorageInitialized() {
287
+ if (!this.trustedStorage || this.trustedInitialized) return;
288
+ await this.ensureStateCommitTable();
289
+ if (typeof this.trustedStorage.initStorage === "function") await this.trustedStorage.initStorage();
290
+ if (!await this.trustedStorage.getHash()) {
291
+ const { currentHash } = await this.getCommitHash();
292
+ const newTrustedHash = await this.trustedStorage.createHash(currentHash);
293
+ await this.trustedStorage.writeHash(newTrustedHash);
294
+ } else await this.verifyTrustedHashInternal();
295
+ this.trustedInitialized = true;
296
+ }
297
+ /**
298
+ * Get the current and previous state commit hash tracked in SQLite StateDB.
299
+ *
300
+ * Note on threat model & performance:
301
+ * SQLite StateDB maintains an O(1) incremental commit-chain head (`_state_commit`)
302
+ * to detect snapshot rollback or crash desynchronization between `statedb` and
303
+ * `trustedStorage` without O(N) full-table scans on every transaction.
304
+ * End-to-end Data Availability, Merkle inclusion proofs, and corruption detection
305
+ * for RPC, Light Wallet, and Archive nodes are enforced by `@arcblock/ledger`
306
+ * checkpoints and self-verifying segments.
307
+ */
308
+ async getCommitHash(executor = this.db) {
309
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
310
+ const row = (await sql`
311
+ SELECT "current_hash", "prev_hash" FROM "_state_commit" WHERE "id" = 1
312
+ `.execute(executor)).rows[0];
313
+ return {
314
+ currentHash: row?.current_hash || "GENESIS",
315
+ prevHash: row?.prev_hash || ""
316
+ };
317
+ }
318
+ async verifyTrustedHashInternal() {
319
+ if (!this.trustedStorage) return;
320
+ const { currentHash } = await this.getCommitHash();
321
+ if (!await this.trustedStorage.compare(currentHash)) {
322
+ const err = /* @__PURE__ */ new Error("Trusted hash verification failed");
323
+ err.code = "INVALID_HASH";
324
+ throw err;
325
+ }
326
+ }
327
+ /**
328
+ * Verify that the current SQLite state commit hash matches the trusted storage record.
329
+ */
330
+ async verifyTrustedHash() {
331
+ if (!this.trustedStorage) return;
332
+ await this.enqueueCommit(async () => {
333
+ await this.ensureTrustedStorageInitialized();
334
+ await this.verifyTrustedHashInternal();
335
+ });
336
+ }
337
+ enqueueCommit(task) {
338
+ const next = this.commitQueue.then(task, task);
339
+ this.commitQueue = next.then(() => void 0, () => void 0);
340
+ return next;
200
341
  }
201
342
  /**
202
343
  * Execute multiple operations within a database transaction
203
344
  * Provides retry logic for SQLite BUSY errors (lock conflicts)
204
345
  *
205
346
  * @param fn - Function receiving Kysely transaction object
206
- * @param options - Optional retry configuration
347
+ * @param options - Optional retry and trusted-hash verification configuration
207
348
  * @returns Result of the transaction function
208
- *
209
- * @example
210
- * ```typescript
211
- * await db.runAsLambda(async (txn) => {
212
- * await txn.insertInto('account').values({ ... }).execute();
213
- * await txn.updateTable('balance').set({ ... }).execute();
214
- * });
215
- * ```
216
349
  */
217
350
  async runAsLambda(fn, options = {}) {
218
- const { retryLimit = 2 } = options;
351
+ if (this.trustedStorage) return this.enqueueCommit(() => this.executeRunAsLambda(fn, options));
352
+ return this.executeRunAsLambda(fn, options);
353
+ }
354
+ async executeRunAsLambda(fn, options = {}) {
355
+ const { retryLimit = 2, verifyHash = false, commitMessage } = options;
356
+ if (this.trustedStorage) {
357
+ await this.ensureTrustedStorageInitialized();
358
+ if (verifyHash) await this.verifyTrustedHashInternal();
359
+ }
360
+ let result;
361
+ let committedHash;
362
+ let previousHash;
219
363
  let lastError;
364
+ let committed = false;
220
365
  for (let attempt = 0; attempt <= retryLimit; attempt++) try {
221
- const result = await this.db.transaction().execute(async (txn) => {
222
- return await fn(txn);
223
- });
224
- if (options.onCommit) try {
225
- await options.onCommit();
226
- } catch (_err) {}
227
- return result;
366
+ committedHash = void 0;
367
+ previousHash = void 0;
368
+ this._activeLambdaCount++;
369
+ try {
370
+ result = await this.db.transaction().execute(async (txn) => {
371
+ const txResult = await fn(txn);
372
+ if (this.trustedStorage) {
373
+ const row = (await sql`
374
+ SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
375
+ `.execute(txn)).rows[0];
376
+ const prevHash = row?.current_hash || "GENESIS";
377
+ const nextSeq = Number(row?.seq || 0) + 1;
378
+ const msg = commitMessage || txResult?.hash || "commit";
379
+ const nextHash = crypto.createHash("sha256").update(`${prevHash}:${nextSeq}:${msg}`).digest("hex");
380
+ await sql`
381
+ UPDATE "_state_commit"
382
+ SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
383
+ WHERE "id" = 1
384
+ `.execute(txn);
385
+ previousHash = prevHash;
386
+ committedHash = nextHash;
387
+ }
388
+ return txResult;
389
+ });
390
+ } finally {
391
+ this._activeLambdaCount--;
392
+ }
393
+ committed = true;
394
+ break;
228
395
  } catch (err) {
229
396
  lastError = err;
230
397
  const code = err?.code;
231
398
  if (!SQLITE_BUSY_CODES.includes(code)) throw err;
232
399
  if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
233
400
  }
234
- throw lastError;
401
+ if (!committed) throw lastError;
402
+ if (this.trustedStorage && committedHash) await this.trustedStorage.updateHash(committedHash, previousHash);
403
+ if (options.onCommit) try {
404
+ await options.onCommit(committedHash);
405
+ } catch (_err) {}
406
+ return result;
235
407
  }
236
408
  /**
237
409
  * Reset all tables (for testing)
@@ -242,12 +414,31 @@ var SqliteStateDB = class extends StateDB {
242
414
  const tableInstance = this[table];
243
415
  if (tableInstance?.reset) await tableInstance.reset();
244
416
  }
417
+ if (this.stateCommitTableReady) {
418
+ await sql`
419
+ UPDATE "_state_commit"
420
+ SET "current_hash" = 'GENESIS', "prev_hash" = '', "seq" = 0, "msg" = ''
421
+ WHERE "id" = 1
422
+ `.execute(this.db);
423
+ if (this.trustedStorage) {
424
+ const genesisHash = await this.trustedStorage.createHash("GENESIS");
425
+ await this.trustedStorage.writeHash(genesisHash);
426
+ }
427
+ }
245
428
  }
246
429
  /**
247
430
  * Close database connection
248
431
  */
249
432
  async close() {
433
+ this.closed = true;
434
+ if (this.walCheckpointTimer) {
435
+ clearInterval(this.walCheckpointTimer);
436
+ this.walCheckpointTimer = null;
437
+ }
438
+ if (this.walCheckpointPromise) await this.walCheckpointPromise.catch(() => void 0);
439
+ await this.commitQueue;
250
440
  await this.db.destroy();
441
+ if (this.trustedStorage && typeof this.trustedStorage.destroy === "function") await this.trustedStorage.destroy();
251
442
  }
252
443
  /**
253
444
  * Get the underlying Kysely instance (for advanced operations)
package/esm/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
1
  import { Database, SqliteOperationContext } from "./interfaces.mjs";
2
- import { SqliteConfig, getRawDatabase } from "./kysely.mjs";
2
+ import { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getRawDatabase } from "./kysely.mjs";
3
3
  import SqliteStateDB from "./db.mjs";
4
- export { type Database, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, getRawDatabase };
4
+ export { type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, createKysely, getRawDatabase };
package/esm/index.mjs CHANGED
@@ -1,8 +1,8 @@
1
- import { getRawDatabase } from "./kysely.mjs";
1
+ import { DurableObjectSqliteDialect, createKysely, getRawDatabase } from "./kysely.mjs";
2
2
  import db_default from "./db.mjs";
3
3
 
4
4
  //#region src/index.ts
5
5
  var src_default = db_default;
6
6
 
7
7
  //#endregion
8
- export { db_default as SqliteStateDB, src_default as default, getRawDatabase };
8
+ export { DurableObjectSqliteDialect, db_default as SqliteStateDB, createKysely, src_default as default, getRawDatabase };
package/esm/kysely.d.mts CHANGED
@@ -1,14 +1,64 @@
1
1
  import { Database } from "./interfaces.mjs";
2
- import { Kysely } from "kysely";
2
+ import { DatabaseConnection, Dialect, Driver, Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler } from "kysely";
3
+ import { ITrustedStorage } from "@ocap/types";
3
4
 
4
5
  //#region src/kysely.d.ts
5
6
 
7
+ /**
8
+ * Minimal Cloudflare Durable Object `SqlStorageCursor` contract (`ctx.storage.sql.exec(...)`).
9
+ */
10
+ interface IDurableObjectSqlStorageCursor<T = Record<string, unknown>> {
11
+ toArray(): T[];
12
+ one?(): T;
13
+ raw?<U = unknown[]>(): IterableIterator<U> | U[];
14
+ columnNames?: string[];
15
+ rowsRead?: number;
16
+ rowsWritten?: number;
17
+ [Symbol.iterator]?(): IterableIterator<T>;
18
+ }
19
+ /**
20
+ * Minimal Cloudflare Durable Object `SqlStorage` contract (`ctx.storage.sql`).
21
+ */
22
+ interface IDurableObjectSqlStorage {
23
+ exec<T = Record<string, unknown>>(query: string, ...bindings: unknown[]): IDurableObjectSqlStorageCursor<T>;
24
+ /**
25
+ * Optional Durable Object runtime transaction closure (`ctx.storage.transaction.bind(ctx.storage)`).
26
+ * When omitted, `DurableObjectSqliteDialect` still provides full atomic rollback via
27
+ * per-statement SQLite trigger undo logs and crash-recovery metadata without emitting
28
+ * forbidden BEGIN/SAVEPOINT SQL.
29
+ */
30
+ transaction?<T>(closure: () => Promise<T>): Promise<T>;
31
+ databaseSize?: number;
32
+ }
33
+ interface DurableObjectSqliteDialectConfig {
34
+ storage: IDurableObjectSqlStorage;
35
+ onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
36
+ }
37
+ declare function getDoStorageWriteEpoch(storage: IDurableObjectSqlStorage): number;
38
+ /**
39
+ * Kysely Dialect for Cloudflare Durable Object SQLite (`ctx.storage.sql`).
40
+ */
41
+ declare class DurableObjectSqliteDialect implements Dialect {
42
+ private readonly config;
43
+ private readonly createdOrder;
44
+ constructor(config: DurableObjectSqliteDialectConfig);
45
+ createDriver(): Driver;
46
+ createQueryCompiler(): SqliteQueryCompiler;
47
+ createAdapter(): SqliteAdapter;
48
+ createIntrospector(db: Kysely<any>): SqliteIntrospector;
49
+ }
6
50
  /**
7
51
  * SQLite configuration options
8
52
  */
9
53
  interface SqliteConfig {
10
54
  /** Database file path. Use ':memory:' for in-memory database */
11
- filename: string;
55
+ filename?: string;
56
+ /** Cloudflare Durable Object `ctx.storage.sql` instance */
57
+ doStorage?: IDurableObjectSqlStorage;
58
+ /** Custom Kysely Dialect override */
59
+ dialect?: Dialect;
60
+ /** Optional trusted storage instance for state commit hash verification */
61
+ trustedStorage?: ITrustedStorage;
12
62
  /** Open database in readonly mode */
13
63
  readonly?: boolean;
14
64
  /** Throw error if file doesn't exist (default: false, creates new file) */
@@ -27,10 +77,22 @@ interface SqliteConfig {
27
77
  * provided. If neither is set, SQLite's default (1000) is left untouched.
28
78
  */
29
79
  walAutoCheckpoint?: number;
80
+ /**
81
+ * Optional interval (in ms) for a background passive WAL checkpoint worker
82
+ * (`PRAGMA wal_checkpoint(PASSIVE)`). When > 0 and WAL mode is enabled, a
83
+ * non-blocking (`unref()`ed) periodic timer checkpoints frames back to the
84
+ * main DB file out-of-band without blocking readers or writers.
85
+ *
86
+ * Falls back to `SQLITE_WAL_CHECKPOINT_INTERVAL_MS` env when not provided.
87
+ * Disabled by default (0 / undefined).
88
+ */
89
+ walCheckpointIntervalMs?: number;
30
90
  }
91
+ declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number | undefined;
31
92
  /**
32
93
  * Create a Kysely instance with SQLite dialect
33
- * Automatically uses kysely-bun-sqlite in Bun or better-sqlite3 in Node.js
94
+ * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
95
+ * custom `config.dialect` when provided, kysely-bun-sqlite in Bun, or better-sqlite3 in Node.js
34
96
  *
35
97
  * @param config - SQLite configuration
36
98
  * @returns Kysely instance configured for the database
@@ -52,4 +114,4 @@ declare function createKysely(config: SqliteConfig): Kysely<Database>;
52
114
  */
53
115
  declare function getRawDatabase(db: Kysely<Database>): any;
54
116
  //#endregion
55
- export { SqliteConfig, createKysely, getRawDatabase };
117
+ export { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, resolveWalCheckpointIntervalMs };