@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 CHANGED
@@ -23,19 +23,25 @@ npm i @marianmeres/kv
23
23
  ```typescript
24
24
  import { createKVClient } from '@marianmeres/kv';
25
25
 
26
- const client = createKVClient(
27
- "my-app-namespace",
28
- type: 'redis' | 'postgres' | 'deno-kv' | 'memory' = 'memory',
29
- options, // options... redisClient (for redis) or pg.Pool/pg.Client (for postgres)...
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
- ## Api
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
- /** Abstract adapter definition */
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
- * "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
32
- * level namespace (similar to db schema), not something you consider when working
33
- * with kv pairs
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
- /** Will connect the client instance to underlying store (if applicable) */
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
- /** Will disconnect the client instance from underlying store (if applicable) */
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
- /** Will set key-value pair to the underlying store with given options */
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
- /** Will get the key from the underlying store */
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
- /** Will delete the key from the underlying store */
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
- /** Will check if the key exists in the underlying store */
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
- /** Will list all existing keys in the underlying store matching given pattern.
53
- * Recognizes redis-like star wildcard format. */
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
- /** Will clear all existing keys in the underlying store matching given pattern.
56
- * Recognizes redis-like star wildcard format. */
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
- /** Will set multiple kv pairs in one batch */
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
- /** Will get multiple keys in one batch */
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
- /** Will do multiple operations within one transaction (where applicable) */
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
- /** Will set the expiration ttl on the given key to given ttl value */
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
- /** Will get the expiration Date for given key */
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
- /** Will get info about the current adapter instance */
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
- /** Will dump all data for debugging purposes only. Use with caution. Intended for
71
- * tests only */
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;
@@ -1,21 +1,37 @@
1
1
  function notImplemented() {
2
2
  throw new Error("Not implemented");
3
3
  }
4
- /** Abstract adapter definition */
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, // no ttl by default
23
+ defaultTtl: 0,
10
24
  };
11
25
  _initialized = false;
12
- constructor(
13
26
  /**
14
- * "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
15
- * level namespace (similar to db schema), not something you consider when working
16
- * with kv pairs
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
- /** Will set key-value pair to the underlying store with given options */
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
- /** Will get the key from the underlying store */
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
- /** Will delete the key from the underlying store */
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
- /** Will check if the key exists in the underlying store */
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
- /** Will list all existing keys in the underlying store matching given pattern.
58
- * Recognizes redis-like star wildcard format. */
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
- /** Will clear all existing keys in the underlying store matching given pattern.
63
- * Recognizes redis-like star wildcard format. */
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
- /** Will set multiple kv pairs in one batch */
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
- /** Will get multiple keys in one batch */
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
- /** Will do multiple operations within one transaction (where applicable) */
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
- /** Will set the expiration ttl on the given key to given ttl value */
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
- /** Will get the expiration Date for given key */
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
- /** Will get info about the current adapter instance */
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
- /** Will dump all data for debugging purposes only. Use with caution. Intended for
95
- * tests only */
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
  }