@marianmeres/kv 2.4.0 → 3.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 +92 -54
- package/API.md +201 -202
- package/README.md +95 -42
- package/dist/adapter/abstract.d.ts +8 -19
- package/dist/adapter/abstract.js +12 -26
- package/dist/adapter/memory.d.ts +2 -3
- package/dist/adapter/memory.js +2 -5
- package/dist/adapter/postgres.d.ts +1 -2
- package/dist/adapter/postgres.js +5 -6
- package/dist/adapter/redis.d.ts +1 -2
- package/dist/adapter/redis.js +4 -7
- package/dist/adapter/sqlite.d.ts +102 -0
- package/dist/adapter/sqlite.js +410 -0
- package/dist/{mod.d.ts → index.d.ts} +2 -2
- package/dist/{mod.js → index.js} +1 -1
- package/dist/kv.d.ts +19 -20
- package/dist/kv.js +12 -17
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +71 -37
- package/CLAUDE.md +0 -3
- package/dist/adapter/deno-kv.d.ts +0 -107
- package/dist/adapter/deno-kv.js +0 -396
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module
|
|
3
|
+
*
|
|
4
|
+
* SQLite key-value storage adapter implementation (`node:sqlite`).
|
|
5
|
+
*/
|
|
6
|
+
import type { DatabaseSync } from "node:sqlite";
|
|
7
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.ts";
|
|
8
|
+
/**
|
|
9
|
+
* Configuration options for the SQLite KV adapter.
|
|
10
|
+
*/
|
|
11
|
+
export interface AdapterSqliteOptions extends AdapterAbstractOptions {
|
|
12
|
+
/**
|
|
13
|
+
* An open `node:sqlite` database, e.g. `new DatabaseSync("kv.db")`. The caller owns
|
|
14
|
+
* it: `destroy()` never closes it, so one handle can be shared across adapters.
|
|
15
|
+
*/
|
|
16
|
+
db: DatabaseSync;
|
|
17
|
+
/**
|
|
18
|
+
* Name of the table to use for storing key-value pairs.
|
|
19
|
+
* The table will be created automatically if it doesn't exist.
|
|
20
|
+
* Only word characters are allowed (no `schema.` prefix).
|
|
21
|
+
* @default "__kv"
|
|
22
|
+
*/
|
|
23
|
+
tableName: string;
|
|
24
|
+
/**
|
|
25
|
+
* Interval in seconds for automatic cleanup of expired keys.
|
|
26
|
+
* Set to 0 to disable automatic cleanup.
|
|
27
|
+
*/
|
|
28
|
+
ttlCleanupIntervalSec: number;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* SQLite key-value storage adapter.
|
|
32
|
+
*
|
|
33
|
+
* Provides persistent key-value storage on a `node:sqlite` database: values are JSON
|
|
34
|
+
* text, expirations are epoch milliseconds. Automatically creates the required table
|
|
35
|
+
* and index on initialization.
|
|
36
|
+
*
|
|
37
|
+
* @remarks
|
|
38
|
+
* - `node:sqlite` is synchronous, so every operation blocks the event loop for its
|
|
39
|
+
* duration (typically microseconds) and nothing else on the handle interleaves.
|
|
40
|
+
* - Multi-statement operations run in `BEGIN IMMEDIATE`, so they stay atomic against
|
|
41
|
+
* other connections and processes on the same file. Inside a transaction the caller
|
|
42
|
+
* already opened on the same handle, they use a savepoint instead.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```typescript
|
|
46
|
+
* import { DatabaseSync } from "node:sqlite";
|
|
47
|
+
*
|
|
48
|
+
* const client = createKVClient("myapp:", "sqlite", {
|
|
49
|
+
* db: new DatabaseSync("kv.db"),
|
|
50
|
+
* });
|
|
51
|
+
* await client.initialize();
|
|
52
|
+
* await client.set("session:abc", { userId: 123 }, { ttl: 3600 });
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
export declare class AdapterSqlite extends AdapterAbstract {
|
|
56
|
+
#private;
|
|
57
|
+
_type: string;
|
|
58
|
+
readonly options: AdapterSqliteOptions;
|
|
59
|
+
constructor(namespace?: string, options?: Partial<AdapterSqliteOptions>);
|
|
60
|
+
/** @inheritdoc */
|
|
61
|
+
initialize(): Promise<void>;
|
|
62
|
+
/** @inheritdoc */
|
|
63
|
+
destroy(hard?: boolean): Promise<void>;
|
|
64
|
+
/** @inheritdoc */
|
|
65
|
+
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
66
|
+
/** @inheritdoc */
|
|
67
|
+
setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
68
|
+
/** @inheritdoc */
|
|
69
|
+
getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>;
|
|
70
|
+
/** @inheritdoc */
|
|
71
|
+
incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
72
|
+
/** @inheritdoc */
|
|
73
|
+
decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
74
|
+
/** @inheritdoc */
|
|
75
|
+
cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
76
|
+
/** @inheritdoc */
|
|
77
|
+
get(key: string): Promise<any>;
|
|
78
|
+
/** @inheritdoc */
|
|
79
|
+
delete(key: string): Promise<boolean>;
|
|
80
|
+
/** @inheritdoc */
|
|
81
|
+
exists(key: string): Promise<boolean>;
|
|
82
|
+
/** @inheritdoc */
|
|
83
|
+
keys(pattern: string): Promise<string[]>;
|
|
84
|
+
/** @inheritdoc */
|
|
85
|
+
keysIter(pattern: string): AsyncIterable<string>;
|
|
86
|
+
/** @inheritdoc */
|
|
87
|
+
clear(pattern: string): Promise<number>;
|
|
88
|
+
/** @inheritdoc */
|
|
89
|
+
setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
90
|
+
/** @inheritdoc */
|
|
91
|
+
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
92
|
+
/** @inheritdoc */
|
|
93
|
+
expire(key: string, ttl: number): Promise<boolean>;
|
|
94
|
+
/** @inheritdoc */
|
|
95
|
+
ttl(key: string): Promise<TtlResult>;
|
|
96
|
+
/** @inheritdoc */
|
|
97
|
+
transaction(operations: Operation[]): Promise<any[]>;
|
|
98
|
+
__debug_dump(): Promise<Record<string, {
|
|
99
|
+
value: any;
|
|
100
|
+
ttl: Date | null;
|
|
101
|
+
}>>;
|
|
102
|
+
}
|
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module
|
|
3
|
+
*
|
|
4
|
+
* SQLite key-value storage adapter implementation (`node:sqlite`).
|
|
5
|
+
*/
|
|
6
|
+
import { createClog } from "@marianmeres/clog";
|
|
7
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
8
|
+
/** Rows fetched per page by {@link AdapterSqlite.keysIter}. */
|
|
9
|
+
const KEYS_ITER_PAGE = 500;
|
|
10
|
+
/** A row is live when it has no expiry or expires after the bound `now` (epoch ms). */
|
|
11
|
+
const LIVE = "(expires_at IS NULL OR expires_at > ?)";
|
|
12
|
+
/**
|
|
13
|
+
* SQLite key-value storage adapter.
|
|
14
|
+
*
|
|
15
|
+
* Provides persistent key-value storage on a `node:sqlite` database: values are JSON
|
|
16
|
+
* text, expirations are epoch milliseconds. Automatically creates the required table
|
|
17
|
+
* and index on initialization.
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* - `node:sqlite` is synchronous, so every operation blocks the event loop for its
|
|
21
|
+
* duration (typically microseconds) and nothing else on the handle interleaves.
|
|
22
|
+
* - Multi-statement operations run in `BEGIN IMMEDIATE`, so they stay atomic against
|
|
23
|
+
* 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.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```typescript
|
|
28
|
+
* import { DatabaseSync } from "node:sqlite";
|
|
29
|
+
*
|
|
30
|
+
* const client = createKVClient("myapp:", "sqlite", {
|
|
31
|
+
* db: new DatabaseSync("kv.db"),
|
|
32
|
+
* });
|
|
33
|
+
* await client.initialize();
|
|
34
|
+
* await client.set("session:abc", { userId: 123 }, { ttl: 3600 });
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
export class AdapterSqlite extends AdapterAbstract {
|
|
38
|
+
_type = "sqlite";
|
|
39
|
+
options = {
|
|
40
|
+
defaultTtl: 0, // no ttl by default
|
|
41
|
+
logger: createClog("KV/sqlite"),
|
|
42
|
+
db: null, // will be set in constructor via options merge
|
|
43
|
+
tableName: "__kv",
|
|
44
|
+
ttlCleanupIntervalSec: 0,
|
|
45
|
+
validateKeys: true,
|
|
46
|
+
};
|
|
47
|
+
#cleanupTimer;
|
|
48
|
+
/** Prepared statements by SQL text — a small, fixed set per adapter. */
|
|
49
|
+
#statements = new Map();
|
|
50
|
+
constructor(namespace = "", options = {}) {
|
|
51
|
+
super(namespace);
|
|
52
|
+
this.options = Object.freeze({ ...this.options, ...(options || {}) });
|
|
53
|
+
if (!this.options.db) {
|
|
54
|
+
throw new Error("Missing sqlite database instance");
|
|
55
|
+
}
|
|
56
|
+
// tableName is spliced into SQL verbatim, so guard against surprises.
|
|
57
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(this.options.tableName)) {
|
|
58
|
+
throw new Error(`Invalid tableName "${this.options.tableName}". Only word characters are allowed.`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
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;
|
|
68
|
+
}
|
|
69
|
+
#expiresAt(ttl) {
|
|
70
|
+
return ttl ? Math.round(Date.now() + ttl * 1000) : null;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
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.
|
|
78
|
+
*/
|
|
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);
|
|
85
|
+
try {
|
|
86
|
+
const result = fn();
|
|
87
|
+
db.exec(commit);
|
|
88
|
+
return result;
|
|
89
|
+
}
|
|
90
|
+
catch (err) {
|
|
91
|
+
try {
|
|
92
|
+
db.exec(rollback);
|
|
93
|
+
// a savepoint survives ROLLBACK TO; release it to leave the caller's
|
|
94
|
+
// transaction exactly as it was
|
|
95
|
+
if (begin.startsWith("SAVEPOINT"))
|
|
96
|
+
db.exec(commit);
|
|
97
|
+
}
|
|
98
|
+
catch (rollbackErr) {
|
|
99
|
+
logger?.error?.(`Rollback failed: ${rollbackErr}`);
|
|
100
|
+
}
|
|
101
|
+
throw err;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/** @inheritdoc */
|
|
105
|
+
async initialize() {
|
|
106
|
+
const { db, tableName } = this.options;
|
|
107
|
+
db.exec(`
|
|
108
|
+
CREATE TABLE IF NOT EXISTS ${tableName} (
|
|
109
|
+
key TEXT NOT NULL PRIMARY KEY,
|
|
110
|
+
value TEXT NOT NULL,
|
|
111
|
+
expires_at INTEGER
|
|
112
|
+
)
|
|
113
|
+
`);
|
|
114
|
+
db.exec(`
|
|
115
|
+
CREATE INDEX IF NOT EXISTS idx_${tableName}_expires_at
|
|
116
|
+
ON ${tableName} (expires_at)
|
|
117
|
+
WHERE expires_at IS NOT NULL
|
|
118
|
+
`);
|
|
119
|
+
this._initialized = true;
|
|
120
|
+
this.#maybeTTLCleanup();
|
|
121
|
+
}
|
|
122
|
+
/** @inheritdoc */
|
|
123
|
+
async destroy(hard) {
|
|
124
|
+
// stop the timer first so a pending tick cannot fire during DROP
|
|
125
|
+
clearTimeout(this.#cleanupTimer);
|
|
126
|
+
this.#cleanupTimer = undefined;
|
|
127
|
+
this.#statements.clear();
|
|
128
|
+
if (hard) {
|
|
129
|
+
const { db, tableName } = this.options;
|
|
130
|
+
db.exec(`DROP TABLE IF EXISTS ${tableName}`);
|
|
131
|
+
}
|
|
132
|
+
this._initialized = false;
|
|
133
|
+
}
|
|
134
|
+
#maybeTTLCleanup() {
|
|
135
|
+
clearTimeout(this.#cleanupTimer); // safety
|
|
136
|
+
if (this.options.ttlCleanupIntervalSec) {
|
|
137
|
+
const { tableName, logger } = this.options;
|
|
138
|
+
// do the cleanup now
|
|
139
|
+
try {
|
|
140
|
+
this.#stmt(`DELETE FROM ${tableName}
|
|
141
|
+
WHERE expires_at IS NOT NULL AND expires_at <= ?`).run(Date.now());
|
|
142
|
+
}
|
|
143
|
+
catch (err) {
|
|
144
|
+
logger?.error?.(`TTL cleanup error: ${err}`);
|
|
145
|
+
}
|
|
146
|
+
// schedule next...
|
|
147
|
+
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Convert a Redis-style glob to an SQLite GLOB pattern. GLOB already reads `*` and `?`
|
|
152
|
+
* as wildcards; its one other metacharacter, `[`, is made literal as `[[]`. Unlike
|
|
153
|
+
* LIKE, GLOB is case-sensitive and can use the primary-key index for a literal prefix.
|
|
154
|
+
*/
|
|
155
|
+
#globPattern(pattern) {
|
|
156
|
+
return pattern.replace(/\[/g, "[[]");
|
|
157
|
+
}
|
|
158
|
+
#withNsGlob(pattern) {
|
|
159
|
+
// namespace is a literal prefix — its own `*`/`?`/`[` must be escaped too
|
|
160
|
+
const ns = this.namespace.replace(/[*?[]/g, "[$&]");
|
|
161
|
+
return ns + this.#globPattern(pattern);
|
|
162
|
+
}
|
|
163
|
+
#upsertSql() {
|
|
164
|
+
return `INSERT INTO ${this.options.tableName} (key, value, expires_at)
|
|
165
|
+
VALUES (?, ?, ?)
|
|
166
|
+
ON CONFLICT (key) DO UPDATE SET
|
|
167
|
+
value = excluded.value,
|
|
168
|
+
expires_at = excluded.expires_at`;
|
|
169
|
+
}
|
|
170
|
+
#set(key, value, options = {}) {
|
|
171
|
+
this._assertInitialized();
|
|
172
|
+
this.#stmt(this.#upsertSql()).run(this._withNs(key), JSON.stringify(value ?? null), this.#expiresAt(this._resolveTtl(options)));
|
|
173
|
+
return true;
|
|
174
|
+
}
|
|
175
|
+
/** @inheritdoc */
|
|
176
|
+
async set(key, value, options = {}) {
|
|
177
|
+
return this.#set(key, value, options);
|
|
178
|
+
}
|
|
179
|
+
/** @inheritdoc */
|
|
180
|
+
async setIfAbsent(key, value, options = {}) {
|
|
181
|
+
this._assertInitialized();
|
|
182
|
+
const nsKey = this._withNs(key);
|
|
183
|
+
// INSERT on new keys; UPDATE only when the existing row is expired.
|
|
184
|
+
// (Live keys stay untouched — the hallmark of setIfAbsent.)
|
|
185
|
+
const { changes } = this.#stmt(`${this.#upsertSql()}
|
|
186
|
+
WHERE expires_at IS NOT NULL AND expires_at <= ?`).run(nsKey, JSON.stringify(value ?? null), this.#expiresAt(this._resolveTtl(options)), Date.now());
|
|
187
|
+
return Number(changes) > 0;
|
|
188
|
+
}
|
|
189
|
+
/** @inheritdoc */
|
|
190
|
+
async getSet(key, value, options = {}) {
|
|
191
|
+
this._assertInitialized();
|
|
192
|
+
return this.#atomic(() => {
|
|
193
|
+
const previous = this.#get(key);
|
|
194
|
+
this.#set(key, value, options);
|
|
195
|
+
return previous;
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
#incrBy(key, delta, options = {}) {
|
|
199
|
+
this._assertInitialized();
|
|
200
|
+
const nsKey = this._withNs(key);
|
|
201
|
+
const { tableName } = this.options;
|
|
202
|
+
// Read-modify-write in JS, so the arithmetic is exactly the memory adapter's.
|
|
203
|
+
return this.#atomic(() => {
|
|
204
|
+
const row = this.#stmt(`SELECT value FROM ${tableName} WHERE key = ? AND ${LIVE}`).get(nsKey, Date.now());
|
|
205
|
+
// - New key OR expired key: value = delta, expires_at = $ttl
|
|
206
|
+
// - Live key: value = old + delta, preserve existing expires_at
|
|
207
|
+
if (!row) {
|
|
208
|
+
this.#stmt(this.#upsertSql()).run(nsKey, JSON.stringify(delta), this.#expiresAt(this._resolveTtl(options)));
|
|
209
|
+
return delta;
|
|
210
|
+
}
|
|
211
|
+
const current = JSON.parse(row.value);
|
|
212
|
+
if (typeof current !== "number") {
|
|
213
|
+
throw new TypeError("KV value is not a number");
|
|
214
|
+
}
|
|
215
|
+
const next = current + delta;
|
|
216
|
+
this.#stmt(`UPDATE ${tableName} SET value = ? WHERE key = ?`).run(JSON.stringify(next), nsKey);
|
|
217
|
+
return next;
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
/** @inheritdoc */
|
|
221
|
+
async incr(key, by = 1, options = {}) {
|
|
222
|
+
return this.#incrBy(key, by, options);
|
|
223
|
+
}
|
|
224
|
+
/** @inheritdoc */
|
|
225
|
+
async decr(key, by = 1, options = {}) {
|
|
226
|
+
return this.#incrBy(key, -by, options);
|
|
227
|
+
}
|
|
228
|
+
/** @inheritdoc */
|
|
229
|
+
async cas(key, expected, next, options = {}) {
|
|
230
|
+
this._assertInitialized();
|
|
231
|
+
const nsKey = this._withNs(key);
|
|
232
|
+
const { tableName } = this.options;
|
|
233
|
+
const hasTtl = options.ttl !== undefined;
|
|
234
|
+
// Stored values are `JSON.stringify` output, so comparing the text is comparing
|
|
235
|
+
// the values — with the memory and Redis adapters' key-order sensitivity.
|
|
236
|
+
const params = [JSON.stringify(next ?? null)];
|
|
237
|
+
if (hasTtl)
|
|
238
|
+
params.push(this.#expiresAt(this._resolveTtl(options)));
|
|
239
|
+
params.push(nsKey, JSON.stringify(expected ?? null), Date.now());
|
|
240
|
+
const { changes } = this.#stmt(`UPDATE ${tableName}
|
|
241
|
+
SET value = ?${hasTtl ? ", expires_at = ?" : ""}
|
|
242
|
+
WHERE key = ? AND value = ? AND ${LIVE}`).run(...params);
|
|
243
|
+
return Number(changes) > 0;
|
|
244
|
+
}
|
|
245
|
+
#get(key) {
|
|
246
|
+
this._assertInitialized();
|
|
247
|
+
const row = this.#stmt(`SELECT value FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`).get(this._withNs(key), Date.now());
|
|
248
|
+
return row ? JSON.parse(row.value) : null;
|
|
249
|
+
}
|
|
250
|
+
/** @inheritdoc */
|
|
251
|
+
async get(key) {
|
|
252
|
+
return this.#get(key);
|
|
253
|
+
}
|
|
254
|
+
#delete(key) {
|
|
255
|
+
this._assertInitialized();
|
|
256
|
+
const { changes } = this.#stmt(`DELETE FROM ${this.options.tableName} WHERE key = ?`).run(this._withNs(key));
|
|
257
|
+
return Number(changes) > 0;
|
|
258
|
+
}
|
|
259
|
+
/** @inheritdoc */
|
|
260
|
+
async delete(key) {
|
|
261
|
+
return this.#delete(key);
|
|
262
|
+
}
|
|
263
|
+
/** @inheritdoc */
|
|
264
|
+
async exists(key) {
|
|
265
|
+
this._assertInitialized();
|
|
266
|
+
const row = this.#stmt(`SELECT 1 FROM ${this.options.tableName} WHERE key = ? AND ${LIVE}`).get(this._withNs(key), Date.now());
|
|
267
|
+
return row !== undefined;
|
|
268
|
+
}
|
|
269
|
+
/** @inheritdoc */
|
|
270
|
+
async keys(pattern) {
|
|
271
|
+
this._assertInitialized();
|
|
272
|
+
const rows = this.#stmt(`SELECT key FROM ${this.options.tableName}
|
|
273
|
+
WHERE key GLOB ? AND ${LIVE}
|
|
274
|
+
ORDER BY key`).all(this.#withNsGlob(pattern), Date.now());
|
|
275
|
+
return rows.map((row) => this._withoutNs(row.key)).toSorted();
|
|
276
|
+
}
|
|
277
|
+
/** @inheritdoc */
|
|
278
|
+
async *keysIter(pattern) {
|
|
279
|
+
this._assertInitialized();
|
|
280
|
+
const { tableName } = this.options;
|
|
281
|
+
const glob = this.#withNsGlob(pattern);
|
|
282
|
+
// Keyset pages instead of one open statement: nothing is left open (no read
|
|
283
|
+
// snapshot held) while the consumer awaits between yields, and an early break
|
|
284
|
+
// leaves nothing to release.
|
|
285
|
+
let after;
|
|
286
|
+
while (true) {
|
|
287
|
+
const rows = (after === undefined
|
|
288
|
+
? this.#stmt(`SELECT key FROM ${tableName}
|
|
289
|
+
WHERE key GLOB ? AND ${LIVE}
|
|
290
|
+
ORDER BY key LIMIT ${KEYS_ITER_PAGE}`).all(glob, Date.now())
|
|
291
|
+
: this.#stmt(`SELECT key FROM ${tableName}
|
|
292
|
+
WHERE key GLOB ? AND key > ? AND ${LIVE}
|
|
293
|
+
ORDER BY key LIMIT ${KEYS_ITER_PAGE}`).all(glob, after, Date.now()));
|
|
294
|
+
for (const row of rows) {
|
|
295
|
+
yield this._withoutNs(row.key);
|
|
296
|
+
}
|
|
297
|
+
if (rows.length < KEYS_ITER_PAGE)
|
|
298
|
+
return;
|
|
299
|
+
after = rows[rows.length - 1].key;
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
/** @inheritdoc */
|
|
303
|
+
async clear(pattern) {
|
|
304
|
+
this._assertInitialized();
|
|
305
|
+
const { tableName } = this.options;
|
|
306
|
+
const glob = this.#withNsGlob(pattern);
|
|
307
|
+
const now = Date.now();
|
|
308
|
+
return this.#atomic(() => {
|
|
309
|
+
const { changes } = this.#stmt(`DELETE FROM ${tableName} WHERE key GLOB ? AND ${LIVE}`).run(glob, now);
|
|
310
|
+
// expired rows under the pattern are already invisible; drop them too, but
|
|
311
|
+
// don't count them
|
|
312
|
+
this.#stmt(`DELETE FROM ${tableName}
|
|
313
|
+
WHERE key GLOB ? AND expires_at IS NOT NULL AND expires_at <= ?`).run(glob, now);
|
|
314
|
+
return Number(changes);
|
|
315
|
+
});
|
|
316
|
+
}
|
|
317
|
+
/** @inheritdoc */
|
|
318
|
+
async setMultiple(entries, options = {}) {
|
|
319
|
+
this._assertInitialized();
|
|
320
|
+
if (entries.length === 0)
|
|
321
|
+
return [];
|
|
322
|
+
// validate every key before writing any
|
|
323
|
+
const rows = this._normalizePairs(entries).map(({ key, value, ttl }) => [
|
|
324
|
+
this._withNs(key),
|
|
325
|
+
JSON.stringify(value ?? null),
|
|
326
|
+
this.#expiresAt(this._resolveTtl({ ttl: ttl ?? options.ttl })),
|
|
327
|
+
]);
|
|
328
|
+
// one transaction: all-or-nothing, and a single commit instead of one per row
|
|
329
|
+
this.#atomic(() => {
|
|
330
|
+
const upsert = this.#stmt(this.#upsertSql());
|
|
331
|
+
for (const params of rows)
|
|
332
|
+
upsert.run(...params);
|
|
333
|
+
});
|
|
334
|
+
return rows.map(() => true);
|
|
335
|
+
}
|
|
336
|
+
/** @inheritdoc */
|
|
337
|
+
async getMultiple(keys) {
|
|
338
|
+
this._assertInitialized();
|
|
339
|
+
if (keys.length === 0)
|
|
340
|
+
return {};
|
|
341
|
+
// one JSON-array parameter instead of N placeholders: no bound-variable limit,
|
|
342
|
+
// and a single cached statement for every batch size
|
|
343
|
+
const rows = this.#stmt(`SELECT key, value FROM ${this.options.tableName}
|
|
344
|
+
WHERE key IN (SELECT j.value FROM json_each(?) AS j) AND ${LIVE}`).all(JSON.stringify(keys.map((k) => this._withNs(k))), Date.now());
|
|
345
|
+
const found = Object.create(null);
|
|
346
|
+
for (const row of rows) {
|
|
347
|
+
found[this._withoutNs(row.key)] = JSON.parse(row.value);
|
|
348
|
+
}
|
|
349
|
+
// preserve explicit null / false / 0 / "" — missing keys become null
|
|
350
|
+
const resultMap = {};
|
|
351
|
+
for (const key of keys) {
|
|
352
|
+
resultMap[key] = key in found ? found[key] : null;
|
|
353
|
+
}
|
|
354
|
+
return resultMap;
|
|
355
|
+
}
|
|
356
|
+
/** @inheritdoc */
|
|
357
|
+
async expire(key, ttl) {
|
|
358
|
+
this._assertInitialized();
|
|
359
|
+
const { changes } = this.#stmt(`UPDATE ${this.options.tableName}
|
|
360
|
+
SET expires_at = ?
|
|
361
|
+
WHERE key = ? AND ${LIVE}`).run(Math.round(Date.now() + ttl * 1000), this._withNs(key), Date.now());
|
|
362
|
+
return Number(changes) > 0;
|
|
363
|
+
}
|
|
364
|
+
/** @inheritdoc */
|
|
365
|
+
async ttl(key) {
|
|
366
|
+
this._assertInitialized();
|
|
367
|
+
const row = this.#stmt(`SELECT expires_at FROM ${this.options.tableName} WHERE key = ?`).get(this._withNs(key));
|
|
368
|
+
if (!row)
|
|
369
|
+
return { state: "missing" };
|
|
370
|
+
if (row.expires_at === null)
|
|
371
|
+
return { state: "no-ttl" };
|
|
372
|
+
// expired-but-not-yet-cleaned counts as missing (matches get() filter)
|
|
373
|
+
const at = new Date(Number(row.expires_at));
|
|
374
|
+
if (at.valueOf() <= Date.now())
|
|
375
|
+
return { state: "missing" };
|
|
376
|
+
return { state: "expires", at };
|
|
377
|
+
}
|
|
378
|
+
/** @inheritdoc */
|
|
379
|
+
async transaction(operations) {
|
|
380
|
+
this._assertInitialized();
|
|
381
|
+
return this.#atomic(() => {
|
|
382
|
+
const results = [];
|
|
383
|
+
for (const op of operations) {
|
|
384
|
+
switch (op.type) {
|
|
385
|
+
case "set":
|
|
386
|
+
results.push(this.#set(op.key, op.value, op.options || {}));
|
|
387
|
+
break;
|
|
388
|
+
case "get":
|
|
389
|
+
results.push(this.#get(op.key));
|
|
390
|
+
break;
|
|
391
|
+
case "delete":
|
|
392
|
+
results.push(this.#delete(op.key));
|
|
393
|
+
break;
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
return results;
|
|
397
|
+
});
|
|
398
|
+
}
|
|
399
|
+
async __debug_dump() {
|
|
400
|
+
this._assertInitialized();
|
|
401
|
+
const rows = this.#stmt(`SELECT key, value, expires_at FROM ${this.options.tableName} WHERE key GLOB ?`).all(this.#withNsGlob("*"));
|
|
402
|
+
return rows.reduce((m, row) => {
|
|
403
|
+
m[this._withoutNs(row.key)] = {
|
|
404
|
+
value: JSON.parse(row.value),
|
|
405
|
+
ttl: row.expires_at === null ? null : new Date(Number(row.expires_at)),
|
|
406
|
+
};
|
|
407
|
+
return m;
|
|
408
|
+
}, {});
|
|
409
|
+
}
|
|
410
|
+
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* - **memory** - In-memory storage (default, not persisted)
|
|
8
8
|
* - **redis** - Redis server
|
|
9
9
|
* - **postgres** - PostgreSQL database
|
|
10
|
-
* - **
|
|
10
|
+
* - **sqlite** - SQLite database (`node:sqlite`)
|
|
11
11
|
*
|
|
12
12
|
* @example
|
|
13
13
|
* ```typescript
|
|
@@ -30,4 +30,4 @@
|
|
|
30
30
|
* await client.destroy();
|
|
31
31
|
* ```
|
|
32
32
|
*/
|
|
33
|
-
export * from "./kv.
|
|
33
|
+
export * from "./kv.ts";
|
package/dist/{mod.js → index.js}
RENAMED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* - **memory** - In-memory storage (default, not persisted)
|
|
8
8
|
* - **redis** - Redis server
|
|
9
9
|
* - **postgres** - PostgreSQL database
|
|
10
|
-
* - **
|
|
10
|
+
* - **sqlite** - SQLite database (`node:sqlite`)
|
|
11
11
|
*
|
|
12
12
|
* @example
|
|
13
13
|
* ```typescript
|
package/dist/kv.d.ts
CHANGED
|
@@ -6,17 +6,17 @@
|
|
|
6
6
|
* Exports the main {@link createKVClient} factory function and re-exports
|
|
7
7
|
* all adapter classes, types, and interfaces.
|
|
8
8
|
*/
|
|
9
|
-
import {
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
import {
|
|
13
|
-
export type {
|
|
14
|
-
export { AdapterAbstract
|
|
15
|
-
export { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.
|
|
16
|
-
export {
|
|
17
|
-
export {
|
|
18
|
-
export {
|
|
19
|
-
export { sleep } from "./utils/sleep.
|
|
9
|
+
import { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.ts";
|
|
10
|
+
import { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.ts";
|
|
11
|
+
import { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.ts";
|
|
12
|
+
import { AdapterSqlite, type AdapterSqliteOptions } from "./adapter/sqlite.ts";
|
|
13
|
+
export type { AdapterAbstractOptions, AdapterInfo, Operation, SetMultipleEntry, SetOptions, TtlResult, } from "./adapter/abstract.ts";
|
|
14
|
+
export { AdapterAbstract } from "./adapter/abstract.ts";
|
|
15
|
+
export { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.ts";
|
|
16
|
+
export { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.ts";
|
|
17
|
+
export { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.ts";
|
|
18
|
+
export { AdapterSqlite, type AdapterSqliteOptions } from "./adapter/sqlite.ts";
|
|
19
|
+
export { sleep } from "./utils/sleep.ts";
|
|
20
20
|
/**
|
|
21
21
|
* Type mapping for all supported KV adapter types.
|
|
22
22
|
* @internal
|
|
@@ -34,9 +34,9 @@ interface KnownTypes {
|
|
|
34
34
|
options: AdapterRedisOptions;
|
|
35
35
|
adapter: AdapterRedis;
|
|
36
36
|
};
|
|
37
|
-
|
|
38
|
-
options:
|
|
39
|
-
adapter:
|
|
37
|
+
sqlite: {
|
|
38
|
+
options: AdapterSqliteOptions;
|
|
39
|
+
adapter: AdapterSqlite;
|
|
40
40
|
};
|
|
41
41
|
}
|
|
42
42
|
/**
|
|
@@ -53,14 +53,13 @@ interface KnownTypes {
|
|
|
53
53
|
* - `"memory"` - In-memory storage (default, not persisted)
|
|
54
54
|
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
55
55
|
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
56
|
-
* - `"
|
|
56
|
+
* - `"sqlite"` - SQLite database (requires `db` option with a `node:sqlite` `DatabaseSync`)
|
|
57
57
|
* @param options - Adapter-specific configuration options.
|
|
58
58
|
*
|
|
59
59
|
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
60
60
|
*
|
|
61
61
|
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
62
62
|
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
63
|
-
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
64
63
|
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
65
64
|
*
|
|
66
65
|
* @example
|
|
@@ -81,10 +80,10 @@ interface KnownTypes {
|
|
|
81
80
|
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
82
81
|
* await postgres.initialize();
|
|
83
82
|
*
|
|
84
|
-
* //
|
|
85
|
-
*
|
|
86
|
-
* const
|
|
87
|
-
* await
|
|
83
|
+
* // SQLite storage
|
|
84
|
+
* import { DatabaseSync } from 'node:sqlite';
|
|
85
|
+
* const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
|
|
86
|
+
* await sqlite.initialize();
|
|
88
87
|
* ```
|
|
89
88
|
*/
|
|
90
89
|
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
|
@@ -6,15 +6,15 @@
|
|
|
6
6
|
* Exports the main {@link createKVClient} factory function and re-exports
|
|
7
7
|
* all adapter classes, types, and interfaces.
|
|
8
8
|
*/
|
|
9
|
-
import { AdapterDenoKv } from "./adapter/deno-kv.js";
|
|
10
9
|
import { AdapterMemory } from "./adapter/memory.js";
|
|
11
|
-
import { AdapterPostgres
|
|
10
|
+
import { AdapterPostgres } from "./adapter/postgres.js";
|
|
12
11
|
import { AdapterRedis } from "./adapter/redis.js";
|
|
13
|
-
|
|
12
|
+
import { AdapterSqlite } from "./adapter/sqlite.js";
|
|
13
|
+
export { AdapterAbstract } from "./adapter/abstract.js";
|
|
14
14
|
export { AdapterMemory } from "./adapter/memory.js";
|
|
15
|
-
export { AdapterRedis } from "./adapter/redis.js";
|
|
16
15
|
export { AdapterPostgres } from "./adapter/postgres.js";
|
|
17
|
-
export {
|
|
16
|
+
export { AdapterRedis } from "./adapter/redis.js";
|
|
17
|
+
export { AdapterSqlite } from "./adapter/sqlite.js";
|
|
18
18
|
export { sleep } from "./utils/sleep.js";
|
|
19
19
|
/**
|
|
20
20
|
* Factory function to create a KV client with the specified adapter type.
|
|
@@ -30,14 +30,13 @@ export { sleep } from "./utils/sleep.js";
|
|
|
30
30
|
* - `"memory"` - In-memory storage (default, not persisted)
|
|
31
31
|
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
32
32
|
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
33
|
-
* - `"
|
|
33
|
+
* - `"sqlite"` - SQLite database (requires `db` option with a `node:sqlite` `DatabaseSync`)
|
|
34
34
|
* @param options - Adapter-specific configuration options.
|
|
35
35
|
*
|
|
36
36
|
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
37
37
|
*
|
|
38
38
|
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
39
39
|
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
40
|
-
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
41
40
|
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
42
41
|
*
|
|
43
42
|
* @example
|
|
@@ -58,10 +57,10 @@ export { sleep } from "./utils/sleep.js";
|
|
|
58
57
|
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
59
58
|
* await postgres.initialize();
|
|
60
59
|
*
|
|
61
|
-
* //
|
|
62
|
-
*
|
|
63
|
-
* const
|
|
64
|
-
* await
|
|
60
|
+
* // SQLite storage
|
|
61
|
+
* import { DatabaseSync } from 'node:sqlite';
|
|
62
|
+
* const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
|
|
63
|
+
* await sqlite.initialize();
|
|
65
64
|
* ```
|
|
66
65
|
*/
|
|
67
66
|
export function createKVClient(namespace = "", type = "memory", options = {}) {
|
|
@@ -72,12 +71,8 @@ export function createKVClient(namespace = "", type = "memory", options = {}) {
|
|
|
72
71
|
return new AdapterPostgres(namespace, options);
|
|
73
72
|
if (type === "redis")
|
|
74
73
|
return new AdapterRedis(namespace, options);
|
|
75
|
-
if (type === "
|
|
76
|
-
|
|
77
|
-
throw new Error(`Type "${type}" is only supported under Deno runtime`);
|
|
78
|
-
}
|
|
79
|
-
return new AdapterDenoKv(namespace, options);
|
|
80
|
-
}
|
|
74
|
+
if (type === "sqlite")
|
|
75
|
+
return new AdapterSqlite(namespace, options);
|
|
81
76
|
//
|
|
82
77
|
throw new TypeError(`Unsupported KV client type "${type}"`);
|
|
83
78
|
}
|