@marianmeres/kv 1.1.2 → 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/README.md +34 -8
- 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 +46 -21
- 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 +50 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -23,19 +23,25 @@ npm i @marianmeres/kv
|
|
|
23
23
|
```typescript
|
|
24
24
|
import { createKVClient } from '@marianmeres/kv';
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
// Basic usage with memory adapter (default)
|
|
27
|
+
const client = createKVClient("my-app-namespace:");
|
|
28
|
+
|
|
29
|
+
// Or specify a different adapter type
|
|
30
|
+
const redisClient = createKVClient(
|
|
31
|
+
"my-app-namespace:",
|
|
32
|
+
'redis', // 'redis' | 'postgres' | 'deno-kv' | 'memory'
|
|
33
|
+
{ db: myRedisClient } // adapter-specific options
|
|
30
34
|
);
|
|
31
35
|
|
|
32
|
-
//
|
|
33
|
-
await client.set('my:foo:key', { my: "value" })
|
|
36
|
+
// Use the client
|
|
37
|
+
await client.set('my:foo:key', { my: "value" });
|
|
34
38
|
await client.get('my:foo:key'); // { my: "value" }
|
|
35
39
|
await client.keys('my:*'); // ['my:foo:key']
|
|
36
40
|
```
|
|
37
41
|
|
|
38
|
-
|
|
42
|
+
**Important**: Namespace must end with a colon (`:`) or be an empty string.
|
|
43
|
+
|
|
44
|
+
## API
|
|
39
45
|
|
|
40
46
|
```typescript
|
|
41
47
|
client.set(key: string, value: any, options?): Promise<boolean>
|
|
@@ -49,4 +55,24 @@ client.getMultiple(keys: string[]): Promise<Record<string, any>>
|
|
|
49
55
|
client.transaction(operations: Operation[]): Promise<any[]>
|
|
50
56
|
client.expire(key: string, ttl: number): Promise<boolean>
|
|
51
57
|
client.ttl(key: string): Promise<Date | null | false>
|
|
52
|
-
```
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Adapter-Specific Limitations
|
|
61
|
+
|
|
62
|
+
### Deno KV
|
|
63
|
+
- **`delete()`**: Always returns `true`, even for non-existent keys (Deno.Kv limitation)
|
|
64
|
+
- **`expire()`**: Not supported - always returns `false`
|
|
65
|
+
- **`ttl()`**: Not supported - always returns `null`
|
|
66
|
+
- **Note**: TTL can be set during `set()` operation, but cannot be queried or modified after
|
|
67
|
+
|
|
68
|
+
### Redis
|
|
69
|
+
- **`keys()` and `clear()`**: Not supported in cluster mode (throws error)
|
|
70
|
+
- **Namespace**: Required (cannot be empty string)
|
|
71
|
+
|
|
72
|
+
### PostgreSQL
|
|
73
|
+
- Creates a table (default: `__kv`) in your database
|
|
74
|
+
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option
|
|
75
|
+
|
|
76
|
+
### Memory
|
|
77
|
+
- Data is not persisted (in-memory only)
|
|
78
|
+
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option
|
|
@@ -1,74 +1,301 @@
|
|
|
1
1
|
import type { Logger } from "@marianmeres/clog";
|
|
2
|
+
/**
|
|
3
|
+
* Options for the `set` operation.
|
|
4
|
+
*/
|
|
2
5
|
export interface SetOptions extends Record<string, any> {
|
|
6
|
+
/** Time-to-live in seconds. After this time, the key will expire. */
|
|
3
7
|
ttl: number;
|
|
4
8
|
}
|
|
9
|
+
/**
|
|
10
|
+
* Information about the adapter instance.
|
|
11
|
+
*/
|
|
5
12
|
export interface AdapterInfo {
|
|
13
|
+
/** The adapter type identifier (e.g., "redis", "postgres", "memory", "deno-kv"). */
|
|
6
14
|
type: string;
|
|
7
15
|
}
|
|
16
|
+
/**
|
|
17
|
+
* Base options shared by all adapter implementations.
|
|
18
|
+
*/
|
|
8
19
|
export interface AdapterAbstractOptions extends Record<string, any> {
|
|
20
|
+
/** Default TTL in seconds applied to all `set` operations when not explicitly specified. Set to 0 to disable. */
|
|
9
21
|
defaultTtl: number;
|
|
22
|
+
/** Optional logger instance for debugging and error logging. */
|
|
10
23
|
logger?: Logger;
|
|
11
24
|
}
|
|
25
|
+
/**
|
|
26
|
+
* Represents a single operation within a transaction.
|
|
27
|
+
*/
|
|
12
28
|
export interface Operation {
|
|
29
|
+
/** The type of operation to perform. */
|
|
13
30
|
type: "set" | "get" | "delete";
|
|
31
|
+
/** The key to operate on. */
|
|
14
32
|
key: string;
|
|
33
|
+
/** The value to set (only used for "set" operations). */
|
|
15
34
|
value?: any;
|
|
35
|
+
/** Optional settings for the operation (only used for "set" operations). */
|
|
16
36
|
options?: Partial<SetOptions>;
|
|
17
37
|
}
|
|
18
|
-
/**
|
|
38
|
+
/**
|
|
39
|
+
* Abstract base class for all KV storage adapters.
|
|
40
|
+
*
|
|
41
|
+
* Provides a unified interface for key-value operations across different storage backends.
|
|
42
|
+
* All adapters must extend this class and implement the abstract methods.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```typescript
|
|
46
|
+
* const client = createKVClient("myapp:", "memory");
|
|
47
|
+
* await client.initialize();
|
|
48
|
+
* await client.set("user:123", { name: "John" });
|
|
49
|
+
* const user = await client.get("user:123");
|
|
50
|
+
* await client.destroy();
|
|
51
|
+
* ```
|
|
52
|
+
*/
|
|
19
53
|
export declare abstract class AdapterAbstract {
|
|
20
|
-
/**
|
|
21
|
-
* "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
|
|
22
|
-
* level namespace (similar to db schema), not something you consider when working
|
|
23
|
-
* with kv pairs
|
|
24
|
-
*/
|
|
25
54
|
readonly namespace: string;
|
|
26
55
|
protected _type: string;
|
|
27
56
|
readonly options: AdapterAbstractOptions;
|
|
28
57
|
protected _initialized: boolean;
|
|
29
|
-
constructor(
|
|
30
58
|
/**
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
* with
|
|
59
|
+
* Creates a new adapter instance.
|
|
60
|
+
*
|
|
61
|
+
* @param namespace - Internal key prefix applied to all keys. Must end with a colon (`:`) or be empty.
|
|
62
|
+
* Acts as a low-level namespace (similar to a database schema).
|
|
63
|
+
* @param options - Adapter configuration options.
|
|
64
|
+
* @throws {TypeError} If namespace doesn't end with a colon and is not empty.
|
|
34
65
|
*/
|
|
35
|
-
namespace?: string, options?: Partial<AdapterAbstractOptions>);
|
|
66
|
+
constructor(namespace?: string, options?: Partial<AdapterAbstractOptions>);
|
|
36
67
|
protected _assertInitialized(): void;
|
|
37
68
|
protected _assertValidNamespace(): void;
|
|
38
69
|
protected _withNs(key: string): string;
|
|
39
70
|
protected _withoutNs(key: string): string;
|
|
40
|
-
/**
|
|
71
|
+
/**
|
|
72
|
+
* Initializes the adapter and connects to the underlying storage.
|
|
73
|
+
*
|
|
74
|
+
* Must be called before any other operations. For some adapters (like memory),
|
|
75
|
+
* this is a no-op, but it should always be called for consistency.
|
|
76
|
+
*
|
|
77
|
+
* @returns A promise that resolves when the connection is established.
|
|
78
|
+
* @throws {Error} If connection fails.
|
|
79
|
+
*/
|
|
41
80
|
abstract initialize(): Promise<void>;
|
|
42
|
-
/**
|
|
81
|
+
/**
|
|
82
|
+
* Destroys the adapter and releases all resources.
|
|
83
|
+
*
|
|
84
|
+
* Should be called when the adapter is no longer needed to clean up
|
|
85
|
+
* connections, timers, and other resources.
|
|
86
|
+
*
|
|
87
|
+
* @param hard - If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL).
|
|
88
|
+
* @returns A promise that resolves when cleanup is complete.
|
|
89
|
+
*/
|
|
43
90
|
abstract destroy(hard?: boolean): Promise<void>;
|
|
44
|
-
/**
|
|
91
|
+
/**
|
|
92
|
+
* Stores a key-value pair in the storage.
|
|
93
|
+
*
|
|
94
|
+
* Values are automatically serialized to JSON. If the key already exists, it will be overwritten.
|
|
95
|
+
*
|
|
96
|
+
* @param key - The key to store the value under.
|
|
97
|
+
* @param value - The value to store. Can be any JSON-serializable value. `undefined` is stored as `null`.
|
|
98
|
+
* @param options - Optional settings including TTL.
|
|
99
|
+
* @returns A promise that resolves to `true` if the operation was successful.
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```typescript
|
|
103
|
+
* await client.set("user:123", { name: "John" });
|
|
104
|
+
* await client.set("session:abc", { token: "xyz" }, { ttl: 3600 }); // expires in 1 hour
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
45
107
|
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
46
|
-
/**
|
|
108
|
+
/**
|
|
109
|
+
* Retrieves a value by its key.
|
|
110
|
+
*
|
|
111
|
+
* @param key - The key to retrieve.
|
|
112
|
+
* @returns A promise that resolves to the stored value, or `null` if the key doesn't exist or has expired.
|
|
113
|
+
*
|
|
114
|
+
* @example
|
|
115
|
+
* ```typescript
|
|
116
|
+
* const user = await client.get("user:123");
|
|
117
|
+
* if (user) {
|
|
118
|
+
* console.log(user.name);
|
|
119
|
+
* }
|
|
120
|
+
* ```
|
|
121
|
+
*/
|
|
47
122
|
get(key: string): Promise<any>;
|
|
48
|
-
/**
|
|
123
|
+
/**
|
|
124
|
+
* Deletes a key from the storage.
|
|
125
|
+
*
|
|
126
|
+
* @param key - The key to delete.
|
|
127
|
+
* @returns A promise that resolves to `true` if the key existed and was deleted,
|
|
128
|
+
* `false` if the key didn't exist. Note: Deno KV always returns `true`.
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```typescript
|
|
132
|
+
* const wasDeleted = await client.delete("user:123");
|
|
133
|
+
* ```
|
|
134
|
+
*/
|
|
49
135
|
delete(key: string): Promise<boolean>;
|
|
50
|
-
/**
|
|
136
|
+
/**
|
|
137
|
+
* Checks if a key exists in the storage.
|
|
138
|
+
*
|
|
139
|
+
* @param key - The key to check.
|
|
140
|
+
* @returns A promise that resolves to `true` if the key exists and hasn't expired, `false` otherwise.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```typescript
|
|
144
|
+
* if (await client.exists("user:123")) {
|
|
145
|
+
* console.log("User exists");
|
|
146
|
+
* }
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
51
149
|
exists(key: string): Promise<boolean>;
|
|
52
|
-
/**
|
|
53
|
-
*
|
|
150
|
+
/**
|
|
151
|
+
* Lists all keys matching a pattern.
|
|
152
|
+
*
|
|
153
|
+
* Uses Redis-style wildcard patterns:
|
|
154
|
+
* - `*` matches any number of characters
|
|
155
|
+
* - `?` matches exactly one character
|
|
156
|
+
*
|
|
157
|
+
* @param pattern - The pattern to match keys against (e.g., `"user:*"`, `"session:???"`).
|
|
158
|
+
* @returns A promise that resolves to an array of matching keys (without namespace prefix), sorted alphabetically.
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* ```typescript
|
|
162
|
+
* const userKeys = await client.keys("user:*");
|
|
163
|
+
* const allKeys = await client.keys("*");
|
|
164
|
+
* ```
|
|
165
|
+
*
|
|
166
|
+
* @throws {Error} In Redis cluster mode.
|
|
167
|
+
*/
|
|
54
168
|
keys(pattern: string): Promise<string[]>;
|
|
55
|
-
/**
|
|
56
|
-
*
|
|
169
|
+
/**
|
|
170
|
+
* Deletes all keys matching a pattern.
|
|
171
|
+
*
|
|
172
|
+
* Uses the same pattern syntax as {@link keys}.
|
|
173
|
+
*
|
|
174
|
+
* @param pattern - The pattern to match keys against.
|
|
175
|
+
* @returns A promise that resolves to the number of keys deleted.
|
|
176
|
+
*
|
|
177
|
+
* @example
|
|
178
|
+
* ```typescript
|
|
179
|
+
* const deleted = await client.clear("session:*"); // Clear all sessions
|
|
180
|
+
* const clearedAll = await client.clear("*"); // Clear everything
|
|
181
|
+
* ```
|
|
182
|
+
*
|
|
183
|
+
* @throws {Error} In Redis cluster mode.
|
|
184
|
+
*/
|
|
57
185
|
clear(pattern: string): Promise<number>;
|
|
58
|
-
/**
|
|
186
|
+
/**
|
|
187
|
+
* Stores multiple key-value pairs in a single batch operation.
|
|
188
|
+
*
|
|
189
|
+
* More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
|
|
190
|
+
*
|
|
191
|
+
* @param keyValuePairs - An array of `[key, value]` tuples to store.
|
|
192
|
+
* @param options - Optional settings applied to all pairs (e.g., TTL).
|
|
193
|
+
* @returns A promise that resolves to an array of boolean results for each operation.
|
|
194
|
+
*
|
|
195
|
+
* @example
|
|
196
|
+
* ```typescript
|
|
197
|
+
* await client.setMultiple([
|
|
198
|
+
* ["user:1", { name: "Alice" }],
|
|
199
|
+
* ["user:2", { name: "Bob" }],
|
|
200
|
+
* ], { ttl: 3600 });
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
59
203
|
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<any[]>;
|
|
60
|
-
/**
|
|
204
|
+
/**
|
|
205
|
+
* Retrieves multiple values in a single batch operation.
|
|
206
|
+
*
|
|
207
|
+
* More efficient than multiple individual `get` calls, especially for Redis and PostgreSQL.
|
|
208
|
+
*
|
|
209
|
+
* @param keys - An array of keys to retrieve.
|
|
210
|
+
* @returns A promise that resolves to an object mapping keys to their values.
|
|
211
|
+
* Missing or expired keys will have a value of `null`.
|
|
212
|
+
*
|
|
213
|
+
* @example
|
|
214
|
+
* ```typescript
|
|
215
|
+
* const users = await client.getMultiple(["user:1", "user:2", "user:3"]);
|
|
216
|
+
* // { "user:1": { name: "Alice" }, "user:2": null, "user:3": { name: "Charlie" } }
|
|
217
|
+
* ```
|
|
218
|
+
*/
|
|
61
219
|
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
62
|
-
/**
|
|
220
|
+
/**
|
|
221
|
+
* Executes multiple operations within a single transaction.
|
|
222
|
+
*
|
|
223
|
+
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
224
|
+
* For memory and Deno KV, operations are executed sequentially.
|
|
225
|
+
*
|
|
226
|
+
* @param operations - An array of operations to execute.
|
|
227
|
+
* @returns A promise that resolves to an array of results for each operation.
|
|
228
|
+
*
|
|
229
|
+
* @example
|
|
230
|
+
* ```typescript
|
|
231
|
+
* const results = await client.transaction([
|
|
232
|
+
* { type: "set", key: "counter", value: 1 },
|
|
233
|
+
* { type: "get", key: "counter" },
|
|
234
|
+
* { type: "delete", key: "old:key" },
|
|
235
|
+
* ]);
|
|
236
|
+
* // [true, 1, true]
|
|
237
|
+
* ```
|
|
238
|
+
*/
|
|
63
239
|
transaction(operations: Operation[]): Promise<any[]>;
|
|
64
|
-
/**
|
|
240
|
+
/**
|
|
241
|
+
* Sets a new expiration time on an existing key.
|
|
242
|
+
*
|
|
243
|
+
* @param key - The key to set expiration on.
|
|
244
|
+
* @param ttl - Time-to-live in seconds from now.
|
|
245
|
+
* @returns A promise that resolves to `true` if the expiration was set,
|
|
246
|
+
* `false` if the key doesn't exist. Note: Not supported in Deno KV (always returns `false`).
|
|
247
|
+
*
|
|
248
|
+
* @example
|
|
249
|
+
* ```typescript
|
|
250
|
+
* await client.set("session:abc", { user: "john" });
|
|
251
|
+
* await client.expire("session:abc", 1800); // Expire in 30 minutes
|
|
252
|
+
* ```
|
|
253
|
+
*/
|
|
65
254
|
expire(key: string, ttl: number): Promise<boolean>;
|
|
66
|
-
/**
|
|
255
|
+
/**
|
|
256
|
+
* Gets the expiration time of a key.
|
|
257
|
+
*
|
|
258
|
+
* @param key - The key to check.
|
|
259
|
+
* @returns A promise that resolves to:
|
|
260
|
+
* - `Date` - The expiration date if TTL is set
|
|
261
|
+
* - `null` - If the key exists but has no expiration
|
|
262
|
+
* - `false` - If the key doesn't exist or has expired
|
|
263
|
+
* Note: Deno KV always returns `null` (TTL query not supported).
|
|
264
|
+
*
|
|
265
|
+
* @example
|
|
266
|
+
* ```typescript
|
|
267
|
+
* const expiry = await client.ttl("session:abc");
|
|
268
|
+
* if (expiry instanceof Date) {
|
|
269
|
+
* console.log(`Expires at: ${expiry.toISOString()}`);
|
|
270
|
+
* } else if (expiry === null) {
|
|
271
|
+
* console.log("No expiration set");
|
|
272
|
+
* } else {
|
|
273
|
+
* console.log("Key does not exist");
|
|
274
|
+
* }
|
|
275
|
+
* ```
|
|
276
|
+
*/
|
|
67
277
|
ttl(key: string): Promise<Date | null | false>;
|
|
68
|
-
/**
|
|
278
|
+
/**
|
|
279
|
+
* Returns information about the current adapter instance.
|
|
280
|
+
*
|
|
281
|
+
* @returns An object containing adapter metadata.
|
|
282
|
+
*
|
|
283
|
+
* @example
|
|
284
|
+
* ```typescript
|
|
285
|
+
* const info = client.info();
|
|
286
|
+
* console.log(info.type); // "redis", "postgres", "memory", or "deno-kv"
|
|
287
|
+
* ```
|
|
288
|
+
*/
|
|
69
289
|
info(): AdapterInfo;
|
|
70
|
-
/**
|
|
71
|
-
*
|
|
290
|
+
/**
|
|
291
|
+
* Dumps all stored data for debugging purposes.
|
|
292
|
+
*
|
|
293
|
+
* **Warning**: This method is intended for testing only. Do not use in production
|
|
294
|
+
* as it may be slow and resource-intensive for large datasets.
|
|
295
|
+
*
|
|
296
|
+
* @returns A promise that resolves to an object mapping keys to their values and TTL info.
|
|
297
|
+
* @internal
|
|
298
|
+
*/
|
|
72
299
|
__debug_dump(): Promise<Record<string, {
|
|
73
300
|
value: any;
|
|
74
301
|
ttl: Date | null | false;
|
package/dist/adapter/abstract.js
CHANGED
|
@@ -1,21 +1,37 @@
|
|
|
1
1
|
function notImplemented() {
|
|
2
2
|
throw new Error("Not implemented");
|
|
3
3
|
}
|
|
4
|
-
/**
|
|
4
|
+
/**
|
|
5
|
+
* Abstract base class for all KV storage adapters.
|
|
6
|
+
*
|
|
7
|
+
* Provides a unified interface for key-value operations across different storage backends.
|
|
8
|
+
* All adapters must extend this class and implement the abstract methods.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```typescript
|
|
12
|
+
* const client = createKVClient("myapp:", "memory");
|
|
13
|
+
* await client.initialize();
|
|
14
|
+
* await client.set("user:123", { name: "John" });
|
|
15
|
+
* const user = await client.get("user:123");
|
|
16
|
+
* await client.destroy();
|
|
17
|
+
* ```
|
|
18
|
+
*/
|
|
5
19
|
export class AdapterAbstract {
|
|
6
20
|
namespace;
|
|
7
21
|
_type = "abstract";
|
|
8
22
|
options = {
|
|
9
|
-
defaultTtl: 0,
|
|
23
|
+
defaultTtl: 0,
|
|
10
24
|
};
|
|
11
25
|
_initialized = false;
|
|
12
|
-
constructor(
|
|
13
26
|
/**
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* with
|
|
27
|
+
* Creates a new adapter instance.
|
|
28
|
+
*
|
|
29
|
+
* @param namespace - Internal key prefix applied to all keys. Must end with a colon (`:`) or be empty.
|
|
30
|
+
* Acts as a low-level namespace (similar to a database schema).
|
|
31
|
+
* @param options - Adapter configuration options.
|
|
32
|
+
* @throws {TypeError} If namespace doesn't end with a colon and is not empty.
|
|
17
33
|
*/
|
|
18
|
-
namespace = "", options = {}) {
|
|
34
|
+
constructor(namespace = "", options = {}) {
|
|
19
35
|
this.namespace = namespace;
|
|
20
36
|
this.options = { ...this.options, ...(options || {}) };
|
|
21
37
|
this._assertValidNamespace();
|
|
@@ -38,61 +54,240 @@ export class AdapterAbstract {
|
|
|
38
54
|
key = key.slice(this.namespace.length);
|
|
39
55
|
return key;
|
|
40
56
|
}
|
|
41
|
-
/**
|
|
57
|
+
/**
|
|
58
|
+
* Stores a key-value pair in the storage.
|
|
59
|
+
*
|
|
60
|
+
* Values are automatically serialized to JSON. If the key already exists, it will be overwritten.
|
|
61
|
+
*
|
|
62
|
+
* @param key - The key to store the value under.
|
|
63
|
+
* @param value - The value to store. Can be any JSON-serializable value. `undefined` is stored as `null`.
|
|
64
|
+
* @param options - Optional settings including TTL.
|
|
65
|
+
* @returns A promise that resolves to `true` if the operation was successful.
|
|
66
|
+
*
|
|
67
|
+
* @example
|
|
68
|
+
* ```typescript
|
|
69
|
+
* await client.set("user:123", { name: "John" });
|
|
70
|
+
* await client.set("session:abc", { token: "xyz" }, { ttl: 3600 }); // expires in 1 hour
|
|
71
|
+
* ```
|
|
72
|
+
*/
|
|
42
73
|
set(key, value, options) {
|
|
43
74
|
return notImplemented();
|
|
44
75
|
}
|
|
45
|
-
/**
|
|
76
|
+
/**
|
|
77
|
+
* Retrieves a value by its key.
|
|
78
|
+
*
|
|
79
|
+
* @param key - The key to retrieve.
|
|
80
|
+
* @returns A promise that resolves to the stored value, or `null` if the key doesn't exist or has expired.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* ```typescript
|
|
84
|
+
* const user = await client.get("user:123");
|
|
85
|
+
* if (user) {
|
|
86
|
+
* console.log(user.name);
|
|
87
|
+
* }
|
|
88
|
+
* ```
|
|
89
|
+
*/
|
|
46
90
|
get(key) {
|
|
47
91
|
return notImplemented();
|
|
48
92
|
}
|
|
49
|
-
/**
|
|
93
|
+
/**
|
|
94
|
+
* Deletes a key from the storage.
|
|
95
|
+
*
|
|
96
|
+
* @param key - The key to delete.
|
|
97
|
+
* @returns A promise that resolves to `true` if the key existed and was deleted,
|
|
98
|
+
* `false` if the key didn't exist. Note: Deno KV always returns `true`.
|
|
99
|
+
*
|
|
100
|
+
* @example
|
|
101
|
+
* ```typescript
|
|
102
|
+
* const wasDeleted = await client.delete("user:123");
|
|
103
|
+
* ```
|
|
104
|
+
*/
|
|
50
105
|
delete(key) {
|
|
51
106
|
return notImplemented();
|
|
52
107
|
}
|
|
53
|
-
/**
|
|
108
|
+
/**
|
|
109
|
+
* Checks if a key exists in the storage.
|
|
110
|
+
*
|
|
111
|
+
* @param key - The key to check.
|
|
112
|
+
* @returns A promise that resolves to `true` if the key exists and hasn't expired, `false` otherwise.
|
|
113
|
+
*
|
|
114
|
+
* @example
|
|
115
|
+
* ```typescript
|
|
116
|
+
* if (await client.exists("user:123")) {
|
|
117
|
+
* console.log("User exists");
|
|
118
|
+
* }
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
54
121
|
exists(key) {
|
|
55
122
|
return notImplemented();
|
|
56
123
|
}
|
|
57
|
-
/**
|
|
58
|
-
*
|
|
124
|
+
/**
|
|
125
|
+
* Lists all keys matching a pattern.
|
|
126
|
+
*
|
|
127
|
+
* Uses Redis-style wildcard patterns:
|
|
128
|
+
* - `*` matches any number of characters
|
|
129
|
+
* - `?` matches exactly one character
|
|
130
|
+
*
|
|
131
|
+
* @param pattern - The pattern to match keys against (e.g., `"user:*"`, `"session:???"`).
|
|
132
|
+
* @returns A promise that resolves to an array of matching keys (without namespace prefix), sorted alphabetically.
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```typescript
|
|
136
|
+
* const userKeys = await client.keys("user:*");
|
|
137
|
+
* const allKeys = await client.keys("*");
|
|
138
|
+
* ```
|
|
139
|
+
*
|
|
140
|
+
* @throws {Error} In Redis cluster mode.
|
|
141
|
+
*/
|
|
59
142
|
keys(pattern) {
|
|
60
143
|
return notImplemented();
|
|
61
144
|
}
|
|
62
|
-
/**
|
|
63
|
-
*
|
|
145
|
+
/**
|
|
146
|
+
* Deletes all keys matching a pattern.
|
|
147
|
+
*
|
|
148
|
+
* Uses the same pattern syntax as {@link keys}.
|
|
149
|
+
*
|
|
150
|
+
* @param pattern - The pattern to match keys against.
|
|
151
|
+
* @returns A promise that resolves to the number of keys deleted.
|
|
152
|
+
*
|
|
153
|
+
* @example
|
|
154
|
+
* ```typescript
|
|
155
|
+
* const deleted = await client.clear("session:*"); // Clear all sessions
|
|
156
|
+
* const clearedAll = await client.clear("*"); // Clear everything
|
|
157
|
+
* ```
|
|
158
|
+
*
|
|
159
|
+
* @throws {Error} In Redis cluster mode.
|
|
160
|
+
*/
|
|
64
161
|
clear(pattern) {
|
|
65
162
|
return notImplemented();
|
|
66
163
|
}
|
|
67
|
-
/**
|
|
164
|
+
/**
|
|
165
|
+
* Stores multiple key-value pairs in a single batch operation.
|
|
166
|
+
*
|
|
167
|
+
* More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
|
|
168
|
+
*
|
|
169
|
+
* @param keyValuePairs - An array of `[key, value]` tuples to store.
|
|
170
|
+
* @param options - Optional settings applied to all pairs (e.g., TTL).
|
|
171
|
+
* @returns A promise that resolves to an array of boolean results for each operation.
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* ```typescript
|
|
175
|
+
* await client.setMultiple([
|
|
176
|
+
* ["user:1", { name: "Alice" }],
|
|
177
|
+
* ["user:2", { name: "Bob" }],
|
|
178
|
+
* ], { ttl: 3600 });
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
68
181
|
setMultiple(keyValuePairs, options) {
|
|
69
182
|
return notImplemented();
|
|
70
183
|
}
|
|
71
|
-
/**
|
|
184
|
+
/**
|
|
185
|
+
* Retrieves multiple values in a single batch operation.
|
|
186
|
+
*
|
|
187
|
+
* More efficient than multiple individual `get` calls, especially for Redis and PostgreSQL.
|
|
188
|
+
*
|
|
189
|
+
* @param keys - An array of keys to retrieve.
|
|
190
|
+
* @returns A promise that resolves to an object mapping keys to their values.
|
|
191
|
+
* Missing or expired keys will have a value of `null`.
|
|
192
|
+
*
|
|
193
|
+
* @example
|
|
194
|
+
* ```typescript
|
|
195
|
+
* const users = await client.getMultiple(["user:1", "user:2", "user:3"]);
|
|
196
|
+
* // { "user:1": { name: "Alice" }, "user:2": null, "user:3": { name: "Charlie" } }
|
|
197
|
+
* ```
|
|
198
|
+
*/
|
|
72
199
|
getMultiple(keys) {
|
|
73
200
|
return notImplemented();
|
|
74
201
|
}
|
|
75
|
-
/**
|
|
202
|
+
/**
|
|
203
|
+
* Executes multiple operations within a single transaction.
|
|
204
|
+
*
|
|
205
|
+
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
206
|
+
* For memory and Deno KV, operations are executed sequentially.
|
|
207
|
+
*
|
|
208
|
+
* @param operations - An array of operations to execute.
|
|
209
|
+
* @returns A promise that resolves to an array of results for each operation.
|
|
210
|
+
*
|
|
211
|
+
* @example
|
|
212
|
+
* ```typescript
|
|
213
|
+
* const results = await client.transaction([
|
|
214
|
+
* { type: "set", key: "counter", value: 1 },
|
|
215
|
+
* { type: "get", key: "counter" },
|
|
216
|
+
* { type: "delete", key: "old:key" },
|
|
217
|
+
* ]);
|
|
218
|
+
* // [true, 1, true]
|
|
219
|
+
* ```
|
|
220
|
+
*/
|
|
76
221
|
transaction(operations) {
|
|
77
222
|
return notImplemented();
|
|
78
223
|
}
|
|
79
|
-
/**
|
|
224
|
+
/**
|
|
225
|
+
* Sets a new expiration time on an existing key.
|
|
226
|
+
*
|
|
227
|
+
* @param key - The key to set expiration on.
|
|
228
|
+
* @param ttl - Time-to-live in seconds from now.
|
|
229
|
+
* @returns A promise that resolves to `true` if the expiration was set,
|
|
230
|
+
* `false` if the key doesn't exist. Note: Not supported in Deno KV (always returns `false`).
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* ```typescript
|
|
234
|
+
* await client.set("session:abc", { user: "john" });
|
|
235
|
+
* await client.expire("session:abc", 1800); // Expire in 30 minutes
|
|
236
|
+
* ```
|
|
237
|
+
*/
|
|
80
238
|
expire(key, ttl) {
|
|
81
239
|
return notImplemented();
|
|
82
240
|
}
|
|
83
|
-
/**
|
|
241
|
+
/**
|
|
242
|
+
* Gets the expiration time of a key.
|
|
243
|
+
*
|
|
244
|
+
* @param key - The key to check.
|
|
245
|
+
* @returns A promise that resolves to:
|
|
246
|
+
* - `Date` - The expiration date if TTL is set
|
|
247
|
+
* - `null` - If the key exists but has no expiration
|
|
248
|
+
* - `false` - If the key doesn't exist or has expired
|
|
249
|
+
* Note: Deno KV always returns `null` (TTL query not supported).
|
|
250
|
+
*
|
|
251
|
+
* @example
|
|
252
|
+
* ```typescript
|
|
253
|
+
* const expiry = await client.ttl("session:abc");
|
|
254
|
+
* if (expiry instanceof Date) {
|
|
255
|
+
* console.log(`Expires at: ${expiry.toISOString()}`);
|
|
256
|
+
* } else if (expiry === null) {
|
|
257
|
+
* console.log("No expiration set");
|
|
258
|
+
* } else {
|
|
259
|
+
* console.log("Key does not exist");
|
|
260
|
+
* }
|
|
261
|
+
* ```
|
|
262
|
+
*/
|
|
84
263
|
ttl(key) {
|
|
85
264
|
return notImplemented();
|
|
86
265
|
}
|
|
87
|
-
/**
|
|
266
|
+
/**
|
|
267
|
+
* Returns information about the current adapter instance.
|
|
268
|
+
*
|
|
269
|
+
* @returns An object containing adapter metadata.
|
|
270
|
+
*
|
|
271
|
+
* @example
|
|
272
|
+
* ```typescript
|
|
273
|
+
* const info = client.info();
|
|
274
|
+
* console.log(info.type); // "redis", "postgres", "memory", or "deno-kv"
|
|
275
|
+
* ```
|
|
276
|
+
*/
|
|
88
277
|
info() {
|
|
89
278
|
return {
|
|
90
279
|
type: this._type,
|
|
91
|
-
// ... todo: list features
|
|
92
280
|
};
|
|
93
281
|
}
|
|
94
|
-
/**
|
|
95
|
-
*
|
|
282
|
+
/**
|
|
283
|
+
* Dumps all stored data for debugging purposes.
|
|
284
|
+
*
|
|
285
|
+
* **Warning**: This method is intended for testing only. Do not use in production
|
|
286
|
+
* as it may be slow and resource-intensive for large datasets.
|
|
287
|
+
*
|
|
288
|
+
* @returns A promise that resolves to an object mapping keys to their values and TTL info.
|
|
289
|
+
* @internal
|
|
290
|
+
*/
|
|
96
291
|
__debug_dump() {
|
|
97
292
|
return notImplemented();
|
|
98
293
|
}
|