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