@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.
- package/AGENTS.md +134 -31
- package/API.md +190 -24
- package/README.md +225 -32
- package/dist/adapter/postgres.d.ts +6 -3
- package/dist/adapter/postgres.js +94 -126
- package/dist/adapter/sqlite.d.ts +23 -7
- package/dist/adapter/sqlite.js +231 -106
- package/dist/kv.d.ts +12 -2
- package/dist/kv.js +10 -2
- package/dist/utils/driver.d.ts +26 -0
- package/dist/utils/driver.js +54 -0
- package/dist/utils/sqlite-driver.d.ts +37 -0
- package/dist/utils/sqlite-driver.js +67 -0
- package/package.json +13 -15
package/dist/adapter/sqlite.js
CHANGED
|
@@ -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)
|
|
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
|
|
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
|
-
/**
|
|
49
|
-
|
|
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
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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:
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
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
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 {
|
|
107
|
-
|
|
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
|
-
|
|
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
|
|
200
|
+
this._initialized = false;
|
|
128
201
|
if (hard) {
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
139
|
-
|
|
140
|
-
if (
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
-
|
|
150
|
-
|
|
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
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
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 {
|
|
195
|
-
WHERE expires_at IS NOT NULL AND expires_at <=
|
|
196
|
-
|
|
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.#
|
|
203
|
-
this.#
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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 {
|
|
359
|
+
const { rowCount } = await this.#q(`UPDATE ${tableName}
|
|
250
360
|
SET value = ?${hasTtl ? ", expires_at = ?" : ""}
|
|
251
|
-
WHERE key = ? AND value = ? AND ${LIVE}
|
|
252
|
-
return
|
|
253
|
-
}
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
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 {
|
|
266
|
-
return
|
|
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
|
-
|
|
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
|
|
276
|
-
return
|
|
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.#
|
|
404
|
+
const { rows } = await this.#q(`SELECT key FROM ${this.options.tableName}
|
|
282
405
|
WHERE key GLOB ? AND ${LIVE}
|
|
283
|
-
ORDER BY key
|
|
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.#
|
|
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}
|
|
300
|
-
: this.#
|
|
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}
|
|
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 {
|
|
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
|
-
|
|
322
|
-
WHERE key GLOB ? AND expires_at IS NOT NULL AND expires_at <=
|
|
323
|
-
return
|
|
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.#
|
|
461
|
+
await this.#atomic((tx) => {
|
|
462
|
+
const upsert = this.#upsertSql();
|
|
340
463
|
for (const params of rows)
|
|
341
|
-
|
|
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.#
|
|
353
|
-
WHERE key IN (SELECT j.value FROM json_each(?) AS j) AND ${LIVE}
|
|
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 {
|
|
491
|
+
const { rowCount } = await this.#q(`UPDATE ${this.options.tableName}
|
|
369
492
|
SET expires_at = ?
|
|
370
|
-
WHERE key = ? AND ${LIVE}
|
|
371
|
-
return
|
|
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.#
|
|
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
|
-
|
|
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.#
|
|
522
|
+
results.push(this.#valueOf(tx.query(...this.#getStatement(op.key))
|
|
523
|
+
.rows));
|
|
399
524
|
break;
|
|
400
525
|
case "delete":
|
|
401
|
-
results.push(this.#
|
|
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.#
|
|
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
|
|
56
|
-
*
|
|
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
|
|
33
|
-
*
|
|
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;
|