@marianmeres/kv 1.1.3 → 1.2.1
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/dist/adapter/abstract.d.ts +256 -29
- package/dist/adapter/abstract.js +219 -24
- package/dist/adapter/deno-kv.d.ts +48 -14
- package/dist/adapter/deno-kv.js +45 -19
- package/dist/adapter/memory.d.ts +43 -15
- package/dist/adapter/memory.js +38 -17
- package/dist/adapter/postgres.d.ts +53 -15
- package/dist/adapter/postgres.js +44 -16
- package/dist/adapter/redis.d.ts +49 -12
- package/dist/adapter/redis.js +40 -14
- package/dist/kv.d.ts +52 -1
- package/dist/kv.js +49 -2
- package/package.json +2 -2
package/dist/adapter/postgres.js
CHANGED
|
@@ -1,11 +1,38 @@
|
|
|
1
1
|
import { AdapterAbstract, } from "./abstract.js";
|
|
2
|
-
import {
|
|
2
|
+
import { createClog } from "@marianmeres/clog";
|
|
3
|
+
/**
|
|
4
|
+
* PostgreSQL key-value storage adapter.
|
|
5
|
+
*
|
|
6
|
+
* Provides persistent key-value storage using PostgreSQL with JSONB values.
|
|
7
|
+
* Automatically creates the required table and indexes on initialization.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
|
|
11
|
+
* - Uses PostgreSQL transactions for the `transaction()` method
|
|
12
|
+
* - Values are stored as JSONB for efficient querying
|
|
13
|
+
* - Supports automatic TTL cleanup via background timer
|
|
14
|
+
* - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import pg from 'pg';
|
|
19
|
+
*
|
|
20
|
+
* const pool = new pg.Pool({ connectionString: 'postgres://...' });
|
|
21
|
+
* const client = createKVClient("myapp:", "postgres", {
|
|
22
|
+
* db: pool,
|
|
23
|
+
* tableName: "kv_store",
|
|
24
|
+
* ttlCleanupIntervalSec: 300, // Clean expired keys every 5 minutes
|
|
25
|
+
* });
|
|
26
|
+
* await client.initialize();
|
|
27
|
+
* await client.set("config:theme", { dark: true });
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
3
30
|
export class AdapterPostgres extends AdapterAbstract {
|
|
4
31
|
namespace;
|
|
5
32
|
_type = "postgres";
|
|
6
33
|
options = {
|
|
7
34
|
defaultTtl: 0, // no ttl by default
|
|
8
|
-
logger:
|
|
35
|
+
logger: createClog("KV/postgres"),
|
|
9
36
|
db: null,
|
|
10
37
|
tableName: "__kv",
|
|
11
38
|
ttlCleanupIntervalSec: 0,
|
|
@@ -20,6 +47,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
20
47
|
throw new Error("Missing pg instance");
|
|
21
48
|
}
|
|
22
49
|
}
|
|
50
|
+
/** @inheritdoc */
|
|
23
51
|
async initialize() {
|
|
24
52
|
const { db, tableName } = this.options;
|
|
25
53
|
// so we can work with "schema." prefix in naming things...
|
|
@@ -34,13 +62,14 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
34
62
|
)
|
|
35
63
|
`);
|
|
36
64
|
await db.query(`
|
|
37
|
-
CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_expires_at
|
|
38
|
-
ON ${tableName} (expires_at)
|
|
65
|
+
CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_expires_at
|
|
66
|
+
ON ${tableName} (expires_at)
|
|
39
67
|
WHERE expires_at IS NOT NULL
|
|
40
68
|
`);
|
|
41
69
|
this._initialized = true;
|
|
42
70
|
this.#maybeTTLCleanup();
|
|
43
71
|
}
|
|
72
|
+
/** @inheritdoc */
|
|
44
73
|
async destroy(hard) {
|
|
45
74
|
if (hard) {
|
|
46
75
|
const { db, tableName } = this.options;
|
|
@@ -70,7 +99,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
70
99
|
#likePattern(pattern) {
|
|
71
100
|
return pattern.replace(/\*/g, "%").replace(/\?/g, "_");
|
|
72
101
|
}
|
|
73
|
-
/**
|
|
102
|
+
/** @inheritdoc */
|
|
74
103
|
async set(key, value, options = {}) {
|
|
75
104
|
this._assertInitialized();
|
|
76
105
|
key = this._withNs(key);
|
|
@@ -86,7 +115,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
86
115
|
updated_at = NOW()`, [key, JSON.stringify(value ?? null), expiresAt]);
|
|
87
116
|
return true;
|
|
88
117
|
}
|
|
89
|
-
/**
|
|
118
|
+
/** @inheritdoc */
|
|
90
119
|
async get(key) {
|
|
91
120
|
this._assertInitialized();
|
|
92
121
|
key = this._withNs(key);
|
|
@@ -98,7 +127,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
98
127
|
return null;
|
|
99
128
|
return rows[0].value;
|
|
100
129
|
}
|
|
101
|
-
/**
|
|
130
|
+
/** @inheritdoc */
|
|
102
131
|
async delete(key) {
|
|
103
132
|
this._assertInitialized();
|
|
104
133
|
key = this._withNs(key);
|
|
@@ -106,7 +135,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
106
135
|
const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE key = $1`, [key]);
|
|
107
136
|
return rowCount > 0;
|
|
108
137
|
}
|
|
109
|
-
/**
|
|
138
|
+
/** @inheritdoc */
|
|
110
139
|
async exists(key) {
|
|
111
140
|
this._assertInitialized();
|
|
112
141
|
key = this._withNs(key);
|
|
@@ -115,8 +144,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
115
144
|
WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key]);
|
|
116
145
|
return rows.length > 0;
|
|
117
146
|
}
|
|
118
|
-
/**
|
|
119
|
-
* Recognizes redis-like star wildcard format. */
|
|
147
|
+
/** @inheritdoc */
|
|
120
148
|
async keys(pattern) {
|
|
121
149
|
this._assertInitialized();
|
|
122
150
|
const { db, tableName } = this.options;
|
|
@@ -143,7 +171,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
143
171
|
})
|
|
144
172
|
.toSorted();
|
|
145
173
|
}
|
|
146
|
-
/**
|
|
174
|
+
/** @inheritdoc */
|
|
147
175
|
async clear(pattern) {
|
|
148
176
|
this._assertInitialized();
|
|
149
177
|
const { db, tableName } = this.options;
|
|
@@ -158,7 +186,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
158
186
|
const { rowCount } = await db.query(query, params);
|
|
159
187
|
return rowCount;
|
|
160
188
|
}
|
|
161
|
-
/**
|
|
189
|
+
/** @inheritdoc */
|
|
162
190
|
async setMultiple(keyValuePairs, options = {}) {
|
|
163
191
|
this._assertInitialized();
|
|
164
192
|
const { db, tableName } = this.options;
|
|
@@ -181,7 +209,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
181
209
|
await db.query(sql, params);
|
|
182
210
|
return keyValuePairs.map(() => true);
|
|
183
211
|
}
|
|
184
|
-
/**
|
|
212
|
+
/** @inheritdoc */
|
|
185
213
|
async getMultiple(keys) {
|
|
186
214
|
this._assertInitialized();
|
|
187
215
|
if (keys.length === 0)
|
|
@@ -208,7 +236,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
208
236
|
});
|
|
209
237
|
return resultMap;
|
|
210
238
|
}
|
|
211
|
-
/**
|
|
239
|
+
/** @inheritdoc */
|
|
212
240
|
async expire(key, ttl) {
|
|
213
241
|
this._assertInitialized();
|
|
214
242
|
key = this._withNs(key);
|
|
@@ -219,7 +247,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
219
247
|
WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key, expiresAt]);
|
|
220
248
|
return rowCount > 0;
|
|
221
249
|
}
|
|
222
|
-
/**
|
|
250
|
+
/** @inheritdoc */
|
|
223
251
|
async ttl(key) {
|
|
224
252
|
this._assertInitialized();
|
|
225
253
|
key = this._withNs(key);
|
|
@@ -234,7 +262,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
234
262
|
return null;
|
|
235
263
|
return new Date(expiresAt);
|
|
236
264
|
}
|
|
237
|
-
/**
|
|
265
|
+
/** @inheritdoc */
|
|
238
266
|
async transaction(operations) {
|
|
239
267
|
this._assertInitialized();
|
|
240
268
|
const { db, logger } = this.options;
|
package/dist/adapter/redis.d.ts
CHANGED
|
@@ -1,38 +1,75 @@
|
|
|
1
1
|
import type { createClient, createClientPool } from "redis";
|
|
2
2
|
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetOptions } from "./abstract.js";
|
|
3
|
+
/**
|
|
4
|
+
* Configuration options for the Redis KV adapter.
|
|
5
|
+
*/
|
|
3
6
|
export interface AdapterRedisOptions extends AdapterAbstractOptions {
|
|
7
|
+
/**
|
|
8
|
+
* Redis client instance created via `createClient()` or `createClientPool()`.
|
|
9
|
+
* Pool support is experimental and not fully tested.
|
|
10
|
+
*/
|
|
4
11
|
db: ReturnType<typeof createClient> | ReturnType<typeof createClientPool>;
|
|
12
|
+
/**
|
|
13
|
+
* Set to `true` if connecting to a Redis Cluster.
|
|
14
|
+
* Note: `keys()` and `clear()` operations are not supported in cluster mode.
|
|
15
|
+
*/
|
|
5
16
|
isCluster: boolean;
|
|
6
17
|
}
|
|
18
|
+
/**
|
|
19
|
+
* Redis key-value storage adapter.
|
|
20
|
+
*
|
|
21
|
+
* Provides persistent key-value storage using Redis as the backend.
|
|
22
|
+
* Supports all Redis features including TTL, pipelining, and transactions.
|
|
23
|
+
*
|
|
24
|
+
* @remarks
|
|
25
|
+
* - Namespace is required (cannot be empty)
|
|
26
|
+
* - Uses Redis MULTI for transactions (atomic operations)
|
|
27
|
+
* - Uses pipelining for batch operations (setMultiple)
|
|
28
|
+
* - `keys()` and `clear()` are not supported in cluster mode
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```typescript
|
|
32
|
+
* import { createClient } from 'redis';
|
|
33
|
+
*
|
|
34
|
+
* const redisClient = createClient({ url: 'redis://localhost:6379' });
|
|
35
|
+
* const client = createKVClient("myapp:", "redis", {
|
|
36
|
+
* db: redisClient,
|
|
37
|
+
* defaultTtl: 3600,
|
|
38
|
+
* });
|
|
39
|
+
* await client.initialize();
|
|
40
|
+
* await client.set("session:abc", { userId: 123 });
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
7
43
|
export declare class AdapterRedis extends AdapterAbstract {
|
|
8
44
|
readonly namespace: string;
|
|
9
45
|
_type: string;
|
|
10
46
|
readonly options: AdapterRedisOptions;
|
|
11
47
|
constructor(namespace?: string, options?: Partial<AdapterRedisOptions>);
|
|
48
|
+
/** @inheritdoc */
|
|
12
49
|
initialize(): Promise<void>;
|
|
50
|
+
/** @inheritdoc */
|
|
13
51
|
destroy(_hard?: boolean): Promise<void>;
|
|
14
|
-
/**
|
|
52
|
+
/** @inheritdoc */
|
|
15
53
|
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
16
|
-
/**
|
|
54
|
+
/** @inheritdoc */
|
|
17
55
|
get(key: string): Promise<any>;
|
|
18
|
-
/**
|
|
56
|
+
/** @inheritdoc */
|
|
19
57
|
delete(key: string): Promise<boolean>;
|
|
20
|
-
/**
|
|
58
|
+
/** @inheritdoc */
|
|
21
59
|
exists(key: string): Promise<boolean>;
|
|
22
|
-
/**
|
|
23
|
-
* Recognizes redis-like star wildcard format. */
|
|
60
|
+
/** @inheritdoc */
|
|
24
61
|
keys(pattern: string): Promise<string[]>;
|
|
25
|
-
/**
|
|
62
|
+
/** @inheritdoc */
|
|
26
63
|
clear(pattern: string): Promise<number>;
|
|
27
|
-
/**
|
|
64
|
+
/** @inheritdoc */
|
|
28
65
|
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
29
|
-
/**
|
|
66
|
+
/** @inheritdoc */
|
|
30
67
|
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
31
|
-
/**
|
|
68
|
+
/** @inheritdoc */
|
|
32
69
|
expire(key: string, ttl: number): Promise<boolean>;
|
|
33
|
-
/**
|
|
70
|
+
/** @inheritdoc */
|
|
34
71
|
ttl(key: string): Promise<Date | null | false>;
|
|
35
|
-
/**
|
|
72
|
+
/** @inheritdoc */
|
|
36
73
|
transaction(operations: Operation[]): Promise<any[]>;
|
|
37
74
|
__debug_dump(): Promise<Record<string, {
|
|
38
75
|
value: any;
|
package/dist/adapter/redis.js
CHANGED
|
@@ -1,11 +1,36 @@
|
|
|
1
1
|
import { AdapterAbstract, } from "./abstract.js";
|
|
2
|
-
import {
|
|
2
|
+
import { createClog } from "@marianmeres/clog";
|
|
3
|
+
/**
|
|
4
|
+
* Redis key-value storage adapter.
|
|
5
|
+
*
|
|
6
|
+
* Provides persistent key-value storage using Redis as the backend.
|
|
7
|
+
* Supports all Redis features including TTL, pipelining, and transactions.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* - Namespace is required (cannot be empty)
|
|
11
|
+
* - Uses Redis MULTI for transactions (atomic operations)
|
|
12
|
+
* - Uses pipelining for batch operations (setMultiple)
|
|
13
|
+
* - `keys()` and `clear()` are not supported in cluster mode
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```typescript
|
|
17
|
+
* import { createClient } from 'redis';
|
|
18
|
+
*
|
|
19
|
+
* const redisClient = createClient({ url: 'redis://localhost:6379' });
|
|
20
|
+
* const client = createKVClient("myapp:", "redis", {
|
|
21
|
+
* db: redisClient,
|
|
22
|
+
* defaultTtl: 3600,
|
|
23
|
+
* });
|
|
24
|
+
* await client.initialize();
|
|
25
|
+
* await client.set("session:abc", { userId: 123 });
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
3
28
|
export class AdapterRedis extends AdapterAbstract {
|
|
4
29
|
namespace;
|
|
5
30
|
_type = "redis";
|
|
6
31
|
options = {
|
|
7
32
|
defaultTtl: 0, // no ttl by default
|
|
8
|
-
logger:
|
|
33
|
+
logger: createClog("KV/redis"),
|
|
9
34
|
db: null,
|
|
10
35
|
isCluster: false,
|
|
11
36
|
};
|
|
@@ -21,6 +46,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
21
46
|
throw new Error("Missing redis db client instance");
|
|
22
47
|
}
|
|
23
48
|
}
|
|
49
|
+
/** @inheritdoc */
|
|
24
50
|
async initialize() {
|
|
25
51
|
const { db, logger } = this.options;
|
|
26
52
|
db.on("error", (err) => logger?.error?.(err));
|
|
@@ -29,11 +55,12 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
29
55
|
await db?.connect();
|
|
30
56
|
this._initialized = true;
|
|
31
57
|
}
|
|
58
|
+
/** @inheritdoc */
|
|
32
59
|
destroy(_hard) {
|
|
33
60
|
this._initialized = false;
|
|
34
61
|
return Promise.resolve();
|
|
35
62
|
}
|
|
36
|
-
/**
|
|
63
|
+
/** @inheritdoc */
|
|
37
64
|
async set(key, value, options = {}) {
|
|
38
65
|
this._assertInitialized();
|
|
39
66
|
key = this._withNs(key);
|
|
@@ -45,7 +72,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
45
72
|
const r = await db.set(key, value, { EX: ttl });
|
|
46
73
|
return r === "OK";
|
|
47
74
|
}
|
|
48
|
-
/**
|
|
75
|
+
/** @inheritdoc */
|
|
49
76
|
async get(key) {
|
|
50
77
|
this._assertInitialized();
|
|
51
78
|
key = this._withNs(key);
|
|
@@ -60,22 +87,21 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
60
87
|
return value;
|
|
61
88
|
}
|
|
62
89
|
}
|
|
63
|
-
/**
|
|
90
|
+
/** @inheritdoc */
|
|
64
91
|
async delete(key) {
|
|
65
92
|
this._assertInitialized();
|
|
66
93
|
key = this._withNs(key);
|
|
67
94
|
const { db } = this.options;
|
|
68
95
|
return parseInt((await db.del(key))) > 0;
|
|
69
96
|
}
|
|
70
|
-
/**
|
|
97
|
+
/** @inheritdoc */
|
|
71
98
|
async exists(key) {
|
|
72
99
|
this._assertInitialized();
|
|
73
100
|
key = this._withNs(key);
|
|
74
101
|
const { db } = this.options;
|
|
75
102
|
return (await db.exists(key)) === 1;
|
|
76
103
|
}
|
|
77
|
-
/**
|
|
78
|
-
* Recognizes redis-like star wildcard format. */
|
|
104
|
+
/** @inheritdoc */
|
|
79
105
|
async keys(pattern) {
|
|
80
106
|
this._assertInitialized();
|
|
81
107
|
const { db, isCluster } = this.options;
|
|
@@ -92,7 +118,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
92
118
|
})
|
|
93
119
|
.toSorted();
|
|
94
120
|
}
|
|
95
|
-
/**
|
|
121
|
+
/** @inheritdoc */
|
|
96
122
|
async clear(pattern) {
|
|
97
123
|
this._assertInitialized();
|
|
98
124
|
const { db, isCluster } = this.options;
|
|
@@ -104,7 +130,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
104
130
|
return 0;
|
|
105
131
|
return parseInt((await db.del(keys.map((k) => this._withNs(k)))));
|
|
106
132
|
}
|
|
107
|
-
/**
|
|
133
|
+
/** @inheritdoc */
|
|
108
134
|
async setMultiple(keyValuePairs, options = {}) {
|
|
109
135
|
this._assertInitialized();
|
|
110
136
|
const { db } = this.options;
|
|
@@ -117,7 +143,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
117
143
|
const res = await pipeline.exec();
|
|
118
144
|
return res.map((v) => v === "OK");
|
|
119
145
|
}
|
|
120
|
-
/**
|
|
146
|
+
/** @inheritdoc */
|
|
121
147
|
async getMultiple(keys) {
|
|
122
148
|
this._assertInitialized();
|
|
123
149
|
const { db } = this.options;
|
|
@@ -141,13 +167,13 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
141
167
|
});
|
|
142
168
|
return result;
|
|
143
169
|
}
|
|
144
|
-
/**
|
|
170
|
+
/** @inheritdoc */
|
|
145
171
|
async expire(key, ttl) {
|
|
146
172
|
this._assertInitialized();
|
|
147
173
|
key = this._withNs(key);
|
|
148
174
|
return parseInt((await this.options.db.expire(key, ttl))) > 0;
|
|
149
175
|
}
|
|
150
|
-
/**
|
|
176
|
+
/** @inheritdoc */
|
|
151
177
|
async ttl(key) {
|
|
152
178
|
this._assertInitialized();
|
|
153
179
|
key = this._withNs(key);
|
|
@@ -161,7 +187,7 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
161
187
|
// Positive number: TTL in seconds remaining
|
|
162
188
|
return new Date(Date.now() + parseInt(`${ttl}`) * 1_000);
|
|
163
189
|
}
|
|
164
|
-
/**
|
|
190
|
+
/** @inheritdoc */
|
|
165
191
|
async transaction(operations) {
|
|
166
192
|
this._assertInitialized();
|
|
167
193
|
const { db } = this.options;
|
package/dist/kv.d.ts
CHANGED
|
@@ -2,6 +2,10 @@ import { AdapterDenoKv, type AdapterDenoKvOptions } from "./adapter/deno-kv.js";
|
|
|
2
2
|
import { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.js";
|
|
3
3
|
import { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.js";
|
|
4
4
|
import { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.js";
|
|
5
|
+
/**
|
|
6
|
+
* Type mapping for all supported KV adapter types.
|
|
7
|
+
* @internal
|
|
8
|
+
*/
|
|
5
9
|
interface KnownTypes {
|
|
6
10
|
memory: {
|
|
7
11
|
options: AdapterMemoryOptions;
|
|
@@ -20,6 +24,53 @@ interface KnownTypes {
|
|
|
20
24
|
adapter: AdapterDenoKv;
|
|
21
25
|
};
|
|
22
26
|
}
|
|
23
|
-
/**
|
|
27
|
+
/**
|
|
28
|
+
* Factory function to create a KV client with the specified adapter type.
|
|
29
|
+
*
|
|
30
|
+
* Creates and returns an adapter instance configured for the specified storage backend.
|
|
31
|
+
* The returned client must be initialized with `await client.initialize()` before use.
|
|
32
|
+
*
|
|
33
|
+
* @typeParam T - The adapter type (inferred from the `type` parameter).
|
|
34
|
+
*
|
|
35
|
+
* @param namespace - Key prefix applied to all operations. Must end with `:` or be empty.
|
|
36
|
+
* Used to isolate different applications or environments sharing the same storage.
|
|
37
|
+
* @param type - The storage backend to use:
|
|
38
|
+
* - `"memory"` - In-memory storage (default, not persisted)
|
|
39
|
+
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
40
|
+
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
41
|
+
* - `"deno-kv"` - Deno KV (Deno runtime only, requires `db` option with Deno.Kv)
|
|
42
|
+
* @param options - Adapter-specific configuration options.
|
|
43
|
+
*
|
|
44
|
+
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
45
|
+
*
|
|
46
|
+
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
47
|
+
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
48
|
+
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
49
|
+
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* ```typescript
|
|
53
|
+
* // In-memory storage (great for testing)
|
|
54
|
+
* const memoryClient = createKVClient("test:", "memory");
|
|
55
|
+
* await memoryClient.initialize();
|
|
56
|
+
*
|
|
57
|
+
* // Redis storage
|
|
58
|
+
* import { createClient } from 'redis';
|
|
59
|
+
* const redisClient = createClient();
|
|
60
|
+
* const redis = createKVClient("myapp:", "redis", { db: redisClient });
|
|
61
|
+
* await redis.initialize();
|
|
62
|
+
*
|
|
63
|
+
* // PostgreSQL storage
|
|
64
|
+
* import pg from 'pg';
|
|
65
|
+
* const pool = new pg.Pool({ connectionString: '...' });
|
|
66
|
+
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
67
|
+
* await postgres.initialize();
|
|
68
|
+
*
|
|
69
|
+
* // Deno KV (Deno runtime only)
|
|
70
|
+
* const kv = await Deno.openKv();
|
|
71
|
+
* const denoKv = createKVClient("myapp:", "deno-kv", { db: kv });
|
|
72
|
+
* await denoKv.initialize();
|
|
73
|
+
* ```
|
|
74
|
+
*/
|
|
24
75
|
export declare function createKVClient<T extends keyof KnownTypes>(namespace?: string, type?: T, options?: Partial<KnownTypes[T]["options"]>): KnownTypes[T]["adapter"];
|
|
25
76
|
export {};
|
package/dist/kv.js
CHANGED
|
@@ -2,8 +2,55 @@ import { AdapterDenoKv } from "./adapter/deno-kv.js";
|
|
|
2
2
|
import { AdapterMemory } from "./adapter/memory.js";
|
|
3
3
|
import { AdapterPostgres, } from "./adapter/postgres.js";
|
|
4
4
|
import { AdapterRedis } from "./adapter/redis.js";
|
|
5
|
-
/**
|
|
6
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Factory function to create a KV client with the specified adapter type.
|
|
7
|
+
*
|
|
8
|
+
* Creates and returns an adapter instance configured for the specified storage backend.
|
|
9
|
+
* The returned client must be initialized with `await client.initialize()` before use.
|
|
10
|
+
*
|
|
11
|
+
* @typeParam T - The adapter type (inferred from the `type` parameter).
|
|
12
|
+
*
|
|
13
|
+
* @param namespace - Key prefix applied to all operations. Must end with `:` or be empty.
|
|
14
|
+
* Used to isolate different applications or environments sharing the same storage.
|
|
15
|
+
* @param type - The storage backend to use:
|
|
16
|
+
* - `"memory"` - In-memory storage (default, not persisted)
|
|
17
|
+
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
18
|
+
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
19
|
+
* - `"deno-kv"` - Deno KV (Deno runtime only, requires `db` option with Deno.Kv)
|
|
20
|
+
* @param options - Adapter-specific configuration options.
|
|
21
|
+
*
|
|
22
|
+
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
23
|
+
*
|
|
24
|
+
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
25
|
+
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
26
|
+
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
27
|
+
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```typescript
|
|
31
|
+
* // In-memory storage (great for testing)
|
|
32
|
+
* const memoryClient = createKVClient("test:", "memory");
|
|
33
|
+
* await memoryClient.initialize();
|
|
34
|
+
*
|
|
35
|
+
* // Redis storage
|
|
36
|
+
* import { createClient } from 'redis';
|
|
37
|
+
* const redisClient = createClient();
|
|
38
|
+
* const redis = createKVClient("myapp:", "redis", { db: redisClient });
|
|
39
|
+
* await redis.initialize();
|
|
40
|
+
*
|
|
41
|
+
* // PostgreSQL storage
|
|
42
|
+
* import pg from 'pg';
|
|
43
|
+
* const pool = new pg.Pool({ connectionString: '...' });
|
|
44
|
+
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
45
|
+
* await postgres.initialize();
|
|
46
|
+
*
|
|
47
|
+
* // Deno KV (Deno runtime only)
|
|
48
|
+
* const kv = await Deno.openKv();
|
|
49
|
+
* const denoKv = createKVClient("myapp:", "deno-kv", { db: kv });
|
|
50
|
+
* await denoKv.initialize();
|
|
51
|
+
* ```
|
|
52
|
+
*/
|
|
53
|
+
export function createKVClient(namespace = "", type = "memory", options = {}) {
|
|
7
54
|
//
|
|
8
55
|
if (type === "memory")
|
|
9
56
|
return new AdapterMemory(namespace, options);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@marianmeres/kv",
|
|
3
|
-
"version": "1.1
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "dist/mod.js",
|
|
6
6
|
"types": "dist/mod.d.ts",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"url": "https://github.com/marianmeres/kv/issues"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
17
|
-
"@marianmeres/clog": "^
|
|
17
|
+
"@marianmeres/clog": "^3.0.0",
|
|
18
18
|
"pg": "^8.16.3",
|
|
19
19
|
"redis": "^5.10.0"
|
|
20
20
|
},
|