@marianmeres/kv 4.0.0 → 4.1.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.
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * @module
3
3
  *
4
- * SQLite key-value storage adapter implementation (`node:sqlite`).
4
+ * SQLite key-value storage adapter implementation (`node:sqlite`, through a sqlkit
5
+ * driver: kv's own over a handle, or the host's).
5
6
  */
6
7
  import { createClog } from "@marianmeres/clog";
7
8
  import { isDriver } from "../utils/driver.js";
9
+ import { assertSqliteDriver, isDatabaseSync, ownSqliteDriver, } from "../utils/sqlite-driver.js";
8
10
  import { AdapterAbstract, } from "./abstract.js";
9
11
  /** Rows fetched per page by {@link AdapterSqlite.keysIter}. */
10
12
  const KEYS_ITER_PAGE = 500;
@@ -18,11 +20,20 @@ const LIVE = "(expires_at IS NULL OR expires_at > ?)";
18
20
  * and index on initialization.
19
21
  *
20
22
  * @remarks
23
+ * - Over a `DatabaseSync`, every statement goes through kv's own sqlkit driver over the
24
+ * handle, on its synchronous tier: one driver per handle, imported on first use. A
25
+ * statement runs inside the call, and nothing else on the handle interleaves.
26
+ * - Over a sqlkit `Driver` the host passed, a statement takes its turn on the driver's
27
+ * async tier: it waits for a transaction the host has open elsewhere, and joins one
28
+ * it was issued inside.
21
29
  * - `node:sqlite` is synchronous, so every operation blocks the event loop for its
22
- * duration (typically microseconds) and nothing else on the handle interleaves.
30
+ * duration (typically microseconds).
23
31
  * - Multi-statement operations run in `BEGIN IMMEDIATE`, so they stay atomic against
24
32
  * other connections and processes on the same file. Inside a transaction the caller
25
- * already opened on the same handle, they use a savepoint instead.
33
+ * already opened (on the same handle, or through the same `Driver`), they use a
34
+ * savepoint instead.
35
+ * - A statement SQLite refused rejects with sqlkit's `SqlError`, node:sqlite's error as
36
+ * its `cause`.
26
37
  *
27
38
  * @example
28
39
  * ```typescript
@@ -33,6 +44,10 @@ const LIVE = "(expires_at IS NULL OR expires_at > ?)";
33
44
  * });
34
45
  * await client.initialize();
35
46
  * await client.set("session:abc", { userId: 123 }, { ttl: 3600 });
47
+ *
48
+ * // or on a sqlkit Driver
49
+ * import { openSqlite } from "@marianmeres/sqlkit/sqlite";
50
+ * const onDriver = createKVClient("myapp:", "sqlite", { db: openSqlite("kv.db") });
36
51
  * ```
37
52
  */
38
53
  export class AdapterSqlite extends AdapterAbstract {
@@ -46,8 +61,18 @@ export class AdapterSqlite extends AdapterAbstract {
46
61
  validateKeys: true,
47
62
  };
48
63
  #cleanupTimer;
49
- /** Prepared statements by SQL text — a small, fixed set per adapter. */
50
- #statements = new Map();
64
+ /**
65
+ * What every statement runs on, set by {@link #open}: kv's own driver over
66
+ * `options.db`, or `options.db` itself when it is a `Driver`. Never closed: either
67
+ * way that would close what the host owns.
68
+ */
69
+ #driver;
70
+ /**
71
+ * Whether `options.db` is a host's `Driver` rather than a handle. The one flag that
72
+ * decides the path, read in {@link #open}, {@link #q}, {@link #atomic},
73
+ * {@link #exec} and the cleanup, and nowhere else.
74
+ */
75
+ #onHostDriver = false;
51
76
  constructor(namespace = "", options = {}) {
52
77
  super(namespace);
53
78
  this.options = Object.freeze({ ...this.options, ...(options || {}) });
@@ -55,67 +80,110 @@ export class AdapterSqlite extends AdapterAbstract {
55
80
  throw new Error("Missing sqlite database instance");
56
81
  }
57
82
  if (isDriver(this.options.db)) {
58
- throw new TypeError("The sqlite adapter takes a node:sqlite DatabaseSync; a sqlkit Driver is not supported yet");
83
+ assertSqliteDriver(this.options.db);
84
+ this.#onHostDriver = true;
85
+ }
86
+ else if (!isDatabaseSync(this.options.db)) {
87
+ throw new TypeError("The sqlite adapter takes a node:sqlite DatabaseSync or a sqlkit Driver of the sqlite dialect as db");
59
88
  }
60
89
  // tableName is spliced into SQL verbatim, so guard against surprises.
61
90
  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(this.options.tableName)) {
62
91
  throw new Error(`Invalid tableName "${this.options.tableName}". Only word characters are allowed.`);
63
92
  }
64
93
  }
65
- #stmt(sql) {
66
- let stmt = this.#statements.get(sql);
67
- if (!stmt) {
68
- stmt = this.options.db.prepare(sql);
69
- this.#statements.set(sql, stmt);
70
- }
71
- return stmt;
94
+ /**
95
+ * The driver: a host's `Driver` as it is, or kv's own over the handle, built (and its
96
+ * module imported) on the first call.
97
+ */
98
+ async #open() {
99
+ this.#driver ??= this.#onHostDriver
100
+ ? this.options.db
101
+ : await ownSqliteDriver(this.options.db);
102
+ return this.#driver;
103
+ }
104
+ /**
105
+ * kv's own driver's sync tier: a statement runs inside the call. Never on a host's
106
+ * `Driver`, outside {@link #atomic}: there it is a `TypeError` whenever the host has a
107
+ * transaction open elsewhere.
108
+ */
109
+ get #sync() {
110
+ return this.#driver.sync;
111
+ }
112
+ /**
113
+ * Run one statement. On a host's `Driver`, on its async tier: it waits its turn, and
114
+ * joins the host's transaction when the call was issued inside it. On kv's own
115
+ * driver, on the sync tier: it has run when this returns.
116
+ */
117
+ #q(text, params) {
118
+ if (this.#onHostDriver)
119
+ return this.#driver.query(text, params);
120
+ return this.#sync.query(text, params);
121
+ }
122
+ /** Run a script: the DDL of `initialize()` and `destroy(true)`. */
123
+ #exec(script) {
124
+ if (this.#onHostDriver)
125
+ return this.#driver.exec(script);
126
+ this.#sync.exec(script);
72
127
  }
73
128
  #expiresAt(ttl) {
74
129
  return ttl ? Math.round(Date.now() + ttl * 1000) : null;
75
130
  }
76
131
  /**
77
- * Runs `fn` as one unit: `BEGIN IMMEDIATE` takes the write lock up front, so no other
78
- * connection can write between its statements. Inside a transaction the caller opened
79
- * on this handle, a savepoint keeps `fn` all-or-nothing without committing theirs.
80
- * `fn` must stay synchronous — an `await` inside would let other work join the
81
- * transaction.
132
+ * Runs `fn` as one unit: the driver's `sync.savepoint()`, which outside a transaction
133
+ * is `BEGIN IMMEDIATE` … `COMMIT`, so no other connection can write between its
134
+ * statements. `fn` must stay synchronous (an `await` inside would let other work join
135
+ * the transaction), and there is no `await` here either: the unit is over when the
136
+ * call returns.
137
+ *
138
+ * On a host's `Driver`, the same `fn` runs inside the driver's async `savepoint()`,
139
+ * on its sync tier (sqlkit's rule S3): the unit waits its turn, is a savepoint of the
140
+ * host's transaction when it was issued inside one, and runs without a break.
82
141
  */
83
- #atomic(fn) {
84
- const { db, logger } = this.options;
85
- const [begin, commit, rollback] = db.isTransaction
86
- ? ["SAVEPOINT kv_atomic", "RELEASE kv_atomic", "ROLLBACK TO kv_atomic"]
87
- : ["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"];
88
- db.exec(begin);
142
+ async #atomic(fn) {
143
+ if (this.#onHostDriver) {
144
+ const driver = this.#driver;
145
+ return driver.savepoint(async () => fn(driver.sync));
146
+ }
147
+ const sync = this.#sync;
148
+ const handle = this.options.db;
149
+ // No transaction of the caller's: the driver's own. (A closed handle goes this way
150
+ // too: `isTransaction` would throw, the driver answers with a `SqlError`.)
151
+ if (!handle.isOpen || !handle.isTransaction)
152
+ return sync.savepoint(fn);
153
+ // The caller's BEGIN on the handle. The driver does not know that transaction and
154
+ // SQLite refuses a second one, so the savepoint goes to the handle and the unit's
155
+ // statements through the driver.
156
+ handle.exec("SAVEPOINT kv_atomic");
89
157
  try {
90
- const result = fn();
91
- db.exec(commit);
158
+ const result = fn(sync);
159
+ handle.exec("RELEASE kv_atomic");
92
160
  return result;
93
161
  }
94
162
  catch (err) {
95
163
  try {
96
- db.exec(rollback);
164
+ handle.exec("ROLLBACK TO kv_atomic");
97
165
  // a savepoint survives ROLLBACK TO; release it to leave the caller's
98
166
  // transaction exactly as it was
99
- if (begin.startsWith("SAVEPOINT"))
100
- db.exec(commit);
167
+ handle.exec("RELEASE kv_atomic");
101
168
  }
102
169
  catch (rollbackErr) {
103
- logger?.error?.(`Rollback failed: ${rollbackErr}`);
170
+ this.options.logger?.error?.(`Rollback failed: ${rollbackErr}`);
104
171
  }
105
172
  throw err;
106
173
  }
107
174
  }
108
175
  /** @inheritdoc */
109
176
  async initialize() {
110
- const { db, tableName } = this.options;
111
- db.exec(`
177
+ const { tableName } = this.options;
178
+ await this.#open();
179
+ await this.#exec(`
112
180
  CREATE TABLE IF NOT EXISTS ${tableName} (
113
181
  key TEXT NOT NULL PRIMARY KEY,
114
182
  value TEXT NOT NULL,
115
183
  expires_at INTEGER
116
184
  )
117
185
  `);
118
- db.exec(`
186
+ await this.#exec(`
119
187
  CREATE INDEX IF NOT EXISTS idx_${tableName}_expires_at
120
188
  ON ${tableName} (expires_at)
121
189
  WHERE expires_at IS NOT NULL
@@ -125,33 +193,51 @@ export class AdapterSqlite extends AdapterAbstract {
125
193
  }
126
194
  /** @inheritdoc */
127
195
  async destroy(hard) {
128
- // stop the timer first so a pending tick cannot fire during DROP
196
+ // stop the timer first so a pending tick cannot fire during DROP, and mark the
197
+ // adapter down before any await
129
198
  clearTimeout(this.#cleanupTimer);
130
199
  this.#cleanupTimer = undefined;
131
- this.#statements.clear();
200
+ this._initialized = false;
132
201
  if (hard) {
133
- const { db, tableName } = this.options;
134
- db.exec(`DROP TABLE IF EXISTS ${tableName}`);
202
+ // `destroy(true)` may come before `initialize()`: open the driver here too
203
+ await this.#open();
204
+ await this.#exec(`DROP TABLE IF EXISTS ${this.options.tableName}`);
135
205
  }
136
- this._initialized = false;
137
206
  }
138
- #maybeTTLCleanup() {
207
+ async #maybeTTLCleanup() {
139
208
  clearTimeout(this.#cleanupTimer); // safety
140
209
  if (this.options.ttlCleanupIntervalSec) {
141
210
  const { db, tableName, logger } = this.options;
142
- // The caller closed the handle without destroy(). Every later tick would fail
143
- // the same way, so say it once and stop.
144
- if (!db.isOpen) {
145
- logger?.error?.("TTL cleanup stopped: the database handle was closed before destroy()");
146
- return;
147
- }
148
- // do the cleanup now
149
- try {
150
- this.#stmt(`DELETE FROM ${tableName}
151
- WHERE expires_at IS NOT NULL AND expires_at <= ?`).run(Date.now());
211
+ const expired = `DELETE FROM ${tableName}
212
+ WHERE expires_at IS NOT NULL AND expires_at <= ?`;
213
+ if (this.#onHostDriver) {
214
+ // The PostgreSQL adapter's tick: the delete waits its turn. A closed driver
215
+ // cannot be told from another failure but by its message, so every failure
216
+ // is logged and the tick goes on.
217
+ try {
218
+ await this.#q(expired, [Date.now()]);
219
+ }
220
+ catch (err) {
221
+ logger?.error?.(`TTL cleanup error: ${err}`);
222
+ }
223
+ // destroy() ran while the delete was waiting or running
224
+ if (!this._initialized)
225
+ return;
152
226
  }
153
- catch (err) {
154
- logger?.error?.(`TTL cleanup error: ${err}`);
227
+ else {
228
+ // The caller closed the handle without destroy(). Every later tick would
229
+ // fail the same way, so say it once and stop.
230
+ if (!db.isOpen) {
231
+ logger?.error?.("TTL cleanup stopped: the database handle was closed before destroy()");
232
+ return;
233
+ }
234
+ // do the cleanup now
235
+ try {
236
+ this.#q(expired, [Date.now()]);
237
+ }
238
+ catch (err) {
239
+ logger?.error?.(`TTL cleanup error: ${err}`);
240
+ }
155
241
  }
156
242
  // schedule next...
157
243
  this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
@@ -180,14 +266,22 @@ export class AdapterSqlite extends AdapterAbstract {
180
266
  value = excluded.value,
181
267
  expires_at = excluded.expires_at`;
182
268
  }
183
- #set(key, value, options = {}) {
184
- this._assertInitialized();
185
- this.#stmt(this.#upsertSql()).run(this._withNs(key), JSON.stringify(value ?? null), this.#expiresAt(this._resolveTtl(options)));
186
- return true;
269
+ /** The upsert `set()` sends, shared with the units. Validates the key. */
270
+ #setStatement(key, value, options = {}) {
271
+ return [
272
+ this.#upsertSql(),
273
+ [
274
+ this._withNs(key),
275
+ JSON.stringify(value ?? null),
276
+ this.#expiresAt(this._resolveTtl(options)),
277
+ ],
278
+ ];
187
279
  }
188
280
  /** @inheritdoc */
189
281
  async set(key, value, options = {}) {
190
- return this.#set(key, value, options);
282
+ this._assertInitialized();
283
+ await this.#q(...this.#setStatement(key, value, options));
284
+ return true;
191
285
  }
192
286
  /** @inheritdoc */
193
287
  async setIfAbsent(key, value, options = {}) {
@@ -195,16 +289,21 @@ export class AdapterSqlite extends AdapterAbstract {
195
289
  const nsKey = this._withNs(key);
196
290
  // INSERT on new keys; UPDATE only when the existing row is expired.
197
291
  // (Live keys stay untouched — the hallmark of setIfAbsent.)
198
- const { changes } = this.#stmt(`${this.#upsertSql()}
199
- WHERE expires_at IS NOT NULL AND expires_at <= ?`).run(nsKey, JSON.stringify(value ?? null), this.#expiresAt(this._resolveTtl(options)), Date.now());
200
- return Number(changes) > 0;
292
+ const { rowCount } = await this.#q(`${this.#upsertSql()}
293
+ WHERE expires_at IS NOT NULL AND expires_at <= ?`, [
294
+ nsKey,
295
+ JSON.stringify(value ?? null),
296
+ this.#expiresAt(this._resolveTtl(options)),
297
+ Date.now(),
298
+ ]);
299
+ return rowCount > 0;
201
300
  }
202
301
  /** @inheritdoc */
203
302
  async getSet(key, value, options = {}) {
204
303
  this._assertInitialized();
205
- return this.#atomic(() => {
206
- const previous = this.#get(key);
207
- this.#set(key, value, options);
304
+ return this.#atomic((tx) => {
305
+ const previous = this.#valueOf(tx.query(...this.#getStatement(key)).rows);
306
+ tx.query(...this.#setStatement(key, value, options));
208
307
  return previous;
209
308
  });
210
309
  }
@@ -213,12 +312,16 @@ export class AdapterSqlite extends AdapterAbstract {
213
312
  const nsKey = this._withNs(key);
214
313
  const { tableName } = this.options;
215
314
  // Read-modify-write in JS, so the arithmetic is exactly the memory adapter's.
216
- return this.#atomic(() => {
217
- const row = this.#stmt(`SELECT value FROM ${tableName} WHERE key = ? AND ${LIVE}`).get(nsKey, Date.now());
315
+ return this.#atomic((tx) => {
316
+ const [row] = tx.query(`SELECT value FROM ${tableName} WHERE key = ? AND ${LIVE}`, [nsKey, Date.now()]).rows;
218
317
  // - New key OR expired key: value = delta, expires_at = $ttl
219
318
  // - Live key: value = old + delta, preserve existing expires_at
220
319
  if (!row) {
221
- this.#stmt(this.#upsertSql()).run(nsKey, JSON.stringify(delta), this.#expiresAt(this._resolveTtl(options)));
320
+ tx.query(this.#upsertSql(), [
321
+ nsKey,
322
+ JSON.stringify(delta),
323
+ this.#expiresAt(this._resolveTtl(options)),
324
+ ]);
222
325
  return delta;
223
326
  }
224
327
  const current = JSON.parse(row.value);
@@ -226,7 +329,10 @@ export class AdapterSqlite extends AdapterAbstract {
226
329
  throw new TypeError("KV value is not a number");
227
330
  }
228
331
  const next = current + delta;
229
- this.#stmt(`UPDATE ${tableName} SET value = ? WHERE key = ?`).run(JSON.stringify(next), nsKey);
332
+ tx.query(`UPDATE ${tableName} SET value = ? WHERE key = ?`, [
333
+ JSON.stringify(next),
334
+ nsKey,
335
+ ]);
230
336
  return next;
231
337
  });
232
338
  }
@@ -250,41 +356,54 @@ export class AdapterSqlite extends AdapterAbstract {
250
356
  if (hasTtl)
251
357
  params.push(this.#expiresAt(this._resolveTtl(options)));
252
358
  params.push(nsKey, JSON.stringify(expected ?? null), Date.now());
253
- const { changes } = this.#stmt(`UPDATE ${tableName}
359
+ const { rowCount } = await this.#q(`UPDATE ${tableName}
254
360
  SET value = ?${hasTtl ? ", expires_at = ?" : ""}
255
- WHERE key = ? AND value = ? AND ${LIVE}`).run(...params);
256
- return Number(changes) > 0;
257
- }
258
- #get(key) {
259
- this._assertInitialized();
260
- const row = this.#stmt(`SELECT value FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`).get(this._withNs(key), Date.now());
361
+ WHERE key = ? AND value = ? AND ${LIVE}`, params);
362
+ return rowCount > 0;
363
+ }
364
+ /** The read `get()` sends, shared with the units. Validates the key. */
365
+ #getStatement(key) {
366
+ return [
367
+ `SELECT value FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`,
368
+ [this._withNs(key), Date.now()],
369
+ ];
370
+ }
371
+ /** The value a {@link #getStatement} read: `null` when it found no live row. */
372
+ #valueOf(rows) {
373
+ const [row] = rows;
261
374
  return row ? JSON.parse(row.value) : null;
262
375
  }
263
376
  /** @inheritdoc */
264
377
  async get(key) {
265
- return this.#get(key);
266
- }
267
- #delete(key) {
268
378
  this._assertInitialized();
269
- const { changes } = this.#stmt(`DELETE FROM ${this.options.tableName} WHERE key = ?`).run(this._withNs(key));
270
- return Number(changes) > 0;
379
+ const { rows } = await this.#q(...this.#getStatement(key));
380
+ return this.#valueOf(rows);
381
+ }
382
+ /** The delete `delete()` sends, shared with the units. Validates the key. */
383
+ #deleteStatement(key) {
384
+ return [
385
+ `DELETE FROM ${this.options.tableName} WHERE key = ?`,
386
+ [this._withNs(key)],
387
+ ];
271
388
  }
272
389
  /** @inheritdoc */
273
390
  async delete(key) {
274
- return this.#delete(key);
391
+ this._assertInitialized();
392
+ const { rowCount } = await this.#q(...this.#deleteStatement(key));
393
+ return rowCount > 0;
275
394
  }
276
395
  /** @inheritdoc */
277
396
  async exists(key) {
278
397
  this._assertInitialized();
279
- const row = this.#stmt(`SELECT 1 FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`).get(this._withNs(key), Date.now());
280
- return row !== undefined;
398
+ const { rowCount } = await this.#q(`SELECT 1 FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`, [this._withNs(key), Date.now()]);
399
+ return rowCount > 0;
281
400
  }
282
401
  /** @inheritdoc */
283
402
  async keys(pattern) {
284
403
  this._assertInitialized();
285
- const rows = this.#stmt(`SELECT key FROM ${this.options.tableName}
404
+ const { rows } = await this.#q(`SELECT key FROM ${this.options.tableName}
286
405
  WHERE key GLOB ? AND ${LIVE}
287
- ORDER BY key`).all(this.#withNsGlob(pattern), Date.now());
406
+ ORDER BY key`, [this.#withNsGlob(pattern), Date.now()]);
288
407
  return rows.map((row) => this._withoutNs(row.key)).toSorted();
289
408
  }
290
409
  /** @inheritdoc */
@@ -297,13 +416,13 @@ export class AdapterSqlite extends AdapterAbstract {
297
416
  // leaves nothing to release.
298
417
  let after;
299
418
  while (true) {
300
- const rows = (after === undefined
301
- ? this.#stmt(`SELECT key FROM ${tableName}
419
+ const { rows } = await (after === undefined
420
+ ? this.#q(`SELECT key FROM ${tableName}
302
421
  WHERE key GLOB ? AND ${LIVE}
303
- ORDER BY key LIMIT ${KEYS_ITER_PAGE}`).all(glob, Date.now())
304
- : this.#stmt(`SELECT key FROM ${tableName}
422
+ ORDER BY key LIMIT ${KEYS_ITER_PAGE}`, [glob, Date.now()])
423
+ : this.#q(`SELECT key FROM ${tableName}
305
424
  WHERE key GLOB ? AND key > ? AND ${LIVE}
306
- ORDER BY key LIMIT ${KEYS_ITER_PAGE}`).all(glob, after, Date.now()));
425
+ ORDER BY key LIMIT ${KEYS_ITER_PAGE}`, [glob, after, Date.now()]));
307
426
  for (const row of rows) {
308
427
  yield this._withoutNs(row.key);
309
428
  }
@@ -318,13 +437,13 @@ export class AdapterSqlite extends AdapterAbstract {
318
437
  const { tableName } = this.options;
319
438
  const glob = this.#withNsGlob(pattern);
320
439
  const now = Date.now();
321
- return this.#atomic(() => {
322
- const { changes } = this.#stmt(`DELETE FROM ${tableName} WHERE key GLOB ? AND ${LIVE}`).run(glob, now);
440
+ return this.#atomic((tx) => {
441
+ const { rowCount } = tx.query(`DELETE FROM ${tableName} WHERE key GLOB ? AND ${LIVE}`, [glob, now]);
323
442
  // expired rows under the pattern are already invisible; drop them too, but
324
443
  // don't count them
325
- this.#stmt(`DELETE FROM ${tableName}
326
- WHERE key GLOB ? AND expires_at IS NOT NULL AND expires_at <= ?`).run(glob, now);
327
- return Number(changes);
444
+ tx.query(`DELETE FROM ${tableName}
445
+ WHERE key GLOB ? AND expires_at IS NOT NULL AND expires_at <= ?`, [glob, now]);
446
+ return rowCount;
328
447
  });
329
448
  }
330
449
  /** @inheritdoc */
@@ -339,10 +458,10 @@ export class AdapterSqlite extends AdapterAbstract {
339
458
  this.#expiresAt(this._resolveTtl({ ttl: ttl ?? options.ttl })),
340
459
  ]);
341
460
  // one transaction: all-or-nothing, and a single commit instead of one per row
342
- this.#atomic(() => {
343
- const upsert = this.#stmt(this.#upsertSql());
461
+ await this.#atomic((tx) => {
462
+ const upsert = this.#upsertSql();
344
463
  for (const params of rows)
345
- upsert.run(...params);
464
+ tx.query(upsert, params);
346
465
  });
347
466
  return rows.map(() => true);
348
467
  }
@@ -353,8 +472,8 @@ export class AdapterSqlite extends AdapterAbstract {
353
472
  return {};
354
473
  // one JSON-array parameter instead of N placeholders: no bound-variable limit,
355
474
  // and a single cached statement for every batch size
356
- const rows = this.#stmt(`SELECT key, value FROM ${this.options.tableName}
357
- WHERE key IN (SELECT j.value FROM json_each(?) AS j) AND ${LIVE}`).all(JSON.stringify(keys.map((k) => this._withNs(k))), Date.now());
475
+ const { rows } = await this.#q(`SELECT key, value FROM ${this.options.tableName}
476
+ WHERE key IN (SELECT j.value FROM json_each(?) AS j) AND ${LIVE}`, [JSON.stringify(keys.map((k) => this._withNs(k))), Date.now()]);
358
477
  const found = Object.create(null);
359
478
  for (const row of rows) {
360
479
  found[this._withoutNs(row.key)] = JSON.parse(row.value);
@@ -369,15 +488,15 @@ export class AdapterSqlite extends AdapterAbstract {
369
488
  /** @inheritdoc */
370
489
  async expire(key, ttl) {
371
490
  this._assertInitialized();
372
- const { changes } = this.#stmt(`UPDATE ${this.options.tableName}
491
+ const { rowCount } = await this.#q(`UPDATE ${this.options.tableName}
373
492
  SET expires_at = ?
374
- WHERE key = ? AND ${LIVE}`).run(Math.round(Date.now() + ttl * 1000), this._withNs(key), Date.now());
375
- return Number(changes) > 0;
493
+ WHERE key = ? AND ${LIVE}`, [Math.round(Date.now() + ttl * 1000), this._withNs(key), Date.now()]);
494
+ return rowCount > 0;
376
495
  }
377
496
  /** @inheritdoc */
378
497
  async ttl(key) {
379
498
  this._assertInitialized();
380
- const row = this.#stmt(`SELECT expires_at FROM ${this.options.tableName} WHERE key = ?`).get(this._withNs(key));
499
+ const [row] = (await this.#q(`SELECT expires_at FROM ${this.options.tableName} WHERE key = ?`, [this._withNs(key)])).rows;
381
500
  if (!row)
382
501
  return { state: "missing" };
383
502
  if (row.expires_at === null)
@@ -391,18 +510,20 @@ export class AdapterSqlite extends AdapterAbstract {
391
510
  /** @inheritdoc */
392
511
  async transaction(operations) {
393
512
  this._assertInitialized();
394
- return this.#atomic(() => {
513
+ return this.#atomic((tx) => {
395
514
  const results = [];
396
515
  for (const op of operations) {
397
516
  switch (op.type) {
398
517
  case "set":
399
- results.push(this.#set(op.key, op.value, op.options || {}));
518
+ tx.query(...this.#setStatement(op.key, op.value, op.options || {}));
519
+ results.push(true);
400
520
  break;
401
521
  case "get":
402
- results.push(this.#get(op.key));
522
+ results.push(this.#valueOf(tx.query(...this.#getStatement(op.key))
523
+ .rows));
403
524
  break;
404
525
  case "delete":
405
- results.push(this.#delete(op.key));
526
+ results.push(tx.query(...this.#deleteStatement(op.key)).rowCount > 0);
406
527
  break;
407
528
  }
408
529
  }
@@ -411,7 +532,7 @@ export class AdapterSqlite extends AdapterAbstract {
411
532
  }
412
533
  async __debug_dump() {
413
534
  this._assertInitialized();
414
- const rows = this.#stmt(`SELECT key, value, expires_at FROM ${this.options.tableName} WHERE key GLOB ?`).all(this.#withNsGlob("*"));
535
+ const { rows } = await this.#q(`SELECT key, value, expires_at FROM ${this.options.tableName} WHERE key GLOB ?`, [this.#withNsGlob("*")]);
415
536
  return rows.reduce((m, row) => {
416
537
  m[this._withoutNs(row.key)] = {
417
538
  value: JSON.parse(row.value),
package/dist/kv.d.ts CHANGED
@@ -18,6 +18,7 @@ export { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.ts";
18
18
  export { AdapterSqlite, type AdapterSqliteOptions } from "./adapter/sqlite.ts";
19
19
  export type { PostgresDb } from "./utils/driver.ts";
20
20
  export { sleep } from "./utils/sleep.ts";
21
+ export type { SqliteDb } from "./utils/sqlite-driver.ts";
21
22
  /**
22
23
  * Type mapping for all supported KV adapter types.
23
24
  * @internal
@@ -55,7 +56,9 @@ interface KnownTypes {
55
56
  * - `"redis"` - Redis server (requires `db` option with Redis client)
56
57
  * - `"postgres"` - PostgreSQL database (requires `db` option: a `pg.Pool`, a
57
58
  * connected `pg.Client`, or a sqlkit `Driver` of the `pg` dialect)
58
- * - `"sqlite"` - SQLite database (requires `db` option with a `node:sqlite` `DatabaseSync`)
59
+ * - `"sqlite"` - SQLite database (requires `db` option: a `node:sqlite`
60
+ * `DatabaseSync`, or a sqlkit `Driver` of the `sqlite` dialect with a sync
61
+ * tier, e.g. `openSqlite()`'s)
59
62
  * @param options - Adapter-specific configuration options.
60
63
  *
61
64
  * @returns A configured adapter instance. Call `initialize()` before use.
@@ -86,6 +89,11 @@ interface KnownTypes {
86
89
  * import { DatabaseSync } from 'node:sqlite';
87
90
  * const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
88
91
  * await sqlite.initialize();
92
+ *
93
+ * // SQLite storage on a sqlkit Driver
94
+ * import { openSqlite } from '@marianmeres/sqlkit/sqlite';
95
+ * const onDriver = createKVClient("myapp:", "sqlite", { db: openSqlite("kv.db") });
96
+ * await onDriver.initialize();
89
97
  * ```
90
98
  */
91
99
  export declare function createKVClient<T extends keyof KnownTypes>(namespace?: string, type?: T, options?: Partial<KnownTypes[T]["options"]>): KnownTypes[T]["adapter"];
package/dist/kv.js CHANGED
@@ -31,7 +31,9 @@ export { sleep } from "./utils/sleep.js";
31
31
  * - `"redis"` - Redis server (requires `db` option with Redis client)
32
32
  * - `"postgres"` - PostgreSQL database (requires `db` option: a `pg.Pool`, a
33
33
  * connected `pg.Client`, or a sqlkit `Driver` of the `pg` dialect)
34
- * - `"sqlite"` - SQLite database (requires `db` option with a `node:sqlite` `DatabaseSync`)
34
+ * - `"sqlite"` - SQLite database (requires `db` option: a `node:sqlite`
35
+ * `DatabaseSync`, or a sqlkit `Driver` of the `sqlite` dialect with a sync
36
+ * tier, e.g. `openSqlite()`'s)
35
37
  * @param options - Adapter-specific configuration options.
36
38
  *
37
39
  * @returns A configured adapter instance. Call `initialize()` before use.
@@ -62,6 +64,11 @@ export { sleep } from "./utils/sleep.js";
62
64
  * import { DatabaseSync } from 'node:sqlite';
63
65
  * const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
64
66
  * await sqlite.initialize();
67
+ *
68
+ * // SQLite storage on a sqlkit Driver
69
+ * import { openSqlite } from '@marianmeres/sqlkit/sqlite';
70
+ * const onDriver = createKVClient("myapp:", "sqlite", { db: openSqlite("kv.db") });
71
+ * await onDriver.initialize();
65
72
  * ```
66
73
  */
67
74
  export function createKVClient(namespace = "", type = "memory", options = {}) {
@@ -20,6 +20,7 @@ export declare function isPool(db: unknown): db is PgPoolLike;
20
20
  * The `Driver` the postgres adapter runs on. A host's `Driver` is used as it is; a
21
21
  * pool or a client gets one driver per object. The adapter never closes any of them.
22
22
  *
23
- * @throws {TypeError} For a `Driver` of another dialect.
23
+ * @throws {TypeError} For a `Driver` of another dialect, or one without `savepoint()`
24
+ * (built by a sqlkit older than 0.3.0).
24
25
  */
25
26
  export declare function toPgDriver(db: PostgresDb): Driver;
@@ -30,13 +30,19 @@ export function isPool(db) {
30
30
  * The `Driver` the postgres adapter runs on. A host's `Driver` is used as it is; a
31
31
  * pool or a client gets one driver per object. The adapter never closes any of them.
32
32
  *
33
- * @throws {TypeError} For a `Driver` of another dialect.
33
+ * @throws {TypeError} For a `Driver` of another dialect, or one without `savepoint()`
34
+ * (built by a sqlkit older than 0.3.0).
34
35
  */
35
36
  export function toPgDriver(db) {
36
37
  if (isDriver(db)) {
37
38
  if (db.dialect !== "pg") {
38
39
  throw new TypeError(`The postgres adapter runs on PostgreSQL: got a "${db.dialect}" driver (${db.adapter})`);
39
40
  }
41
+ // `transaction()` runs in the driver's `savepoint()`. The type requires it; a
42
+ // driver from an older sqlkit, passed past the type, would fail there instead.
43
+ if (typeof db.savepoint !== "function") {
44
+ throw new TypeError("The postgres adapter needs a Driver from @marianmeres/sqlkit 0.3.0 or newer: this one has no savepoint()");
45
+ }
40
46
  return db;
41
47
  }
42
48
  let driver = drivers.get(db);