@marianmeres/kv 1.1.1 → 1.1.3

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
@@ -27,14 +27,12 @@ export declare class AdapterDenoKv extends AdapterAbstract {
27
27
  clear(pattern: string): Promise<number>;
28
28
  /** Will set multiple kv pairs in one batch */
29
29
  setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
30
- /** Will get multiple keys in one batch.
31
- * NOTE: Deno.Kv supports list, so that should be probably used
32
- */
30
+ /** Will get multiple keys in one batch. */
33
31
  getMultiple(keys: string[]): Promise<Record<string, any>>;
34
32
  /** */
35
33
  transaction(operations: Operation[]): Promise<any[]>;
36
34
  /** Not supported in Deno.Kv */
37
35
  expire(key: string, ttl: number): Promise<boolean>;
38
- /** NOT SUPPORTED IN DENO KV... Will get the expiration Date for given key */
36
+ /** Not supported in Deno.Kv */
39
37
  ttl(key: string): Promise<Date | null | false>;
40
38
  }
@@ -44,18 +44,16 @@ export class AdapterDenoKv extends AdapterAbstract {
44
44
  if (value === undefined)
45
45
  value = null;
46
46
  // Deno.Kv does not require this, but for the consistency with other adapters
47
- // let's just stringify (the toJSON may do magic)
47
+ // let's just stringify (the toJSON may do magic, so we want consistent behavior
48
+ // across adapters)
48
49
  value = JSON.stringify(value);
49
50
  await db.set(this.#denoKvKey(key), value, {
50
51
  expireIn: ttl ? ttl * 1000 : undefined,
51
52
  });
52
53
  return true;
53
54
  }
54
- /** Will get the key from the underlying store */
55
- async get(key) {
56
- this._assertInitialized();
57
- const { db } = this.options;
58
- const row = await db.get(this.#denoKvKey(key));
55
+ /** Will return the internal value */
56
+ #parseValue(row) {
59
57
  try {
60
58
  return JSON.parse(`${row?.value ?? null}`);
61
59
  }
@@ -63,6 +61,13 @@ export class AdapterDenoKv extends AdapterAbstract {
63
61
  return row?.value;
64
62
  }
65
63
  }
64
+ /** Will get the key from the underlying store */
65
+ async get(key) {
66
+ this._assertInitialized();
67
+ const { db } = this.options;
68
+ const row = await db.get(this.#denoKvKey(key));
69
+ return this.#parseValue(row);
70
+ }
66
71
  /** Will check if the key exists in the underlying store */
67
72
  async exists(key) {
68
73
  this._assertInitialized();
@@ -118,14 +123,15 @@ export class AdapterDenoKv extends AdapterAbstract {
118
123
  }
119
124
  return results;
120
125
  }
121
- /** Will get multiple keys in one batch.
122
- * NOTE: Deno.Kv supports list, so that should be probably used
123
- */
126
+ /** Will get multiple keys in one batch. */
124
127
  async getMultiple(keys) {
125
128
  this._assertInitialized();
129
+ const { db } = this.options;
126
130
  const result = {};
127
- for (const key of keys) {
128
- result[key] = await this.get(key);
131
+ const denoKvKeys = keys.map((k) => this.#denoKvKey(k));
132
+ const results = await db.getMany(denoKvKeys);
133
+ for (const [index, row] of results.entries()) {
134
+ result[keys[index]] = this.#parseValue(row);
129
135
  }
130
136
  return result;
131
137
  }
@@ -133,9 +139,9 @@ export class AdapterDenoKv extends AdapterAbstract {
133
139
  async transaction(operations) {
134
140
  this._assertInitialized();
135
141
  const { db } = this.options;
136
- this._assertInitialized();
137
142
  // note: memory operations are atomic by nature
138
143
  const results = [];
144
+ // ignoring Deno.Kv's atomic feature...
139
145
  try {
140
146
  for (const op of operations) {
141
147
  switch (op.type) {
@@ -162,10 +168,9 @@ export class AdapterDenoKv extends AdapterAbstract {
162
168
  this._assertInitialized();
163
169
  return Promise.resolve(false);
164
170
  }
165
- /** NOT SUPPORTED IN DENO KV... Will get the expiration Date for given key */
166
- async ttl(key) {
171
+ /** Not supported in Deno.Kv */
172
+ ttl(key) {
167
173
  this._assertInitialized();
168
- //
169
174
  return Promise.resolve(null);
170
175
  }
171
176
  }
package/dist/kv.js CHANGED
@@ -18,5 +18,5 @@ export function createKVClient(namespace = "", type = "redis", options = {}) {
18
18
  return new AdapterDenoKv(namespace, options);
19
19
  }
20
20
  //
21
- throw new TypeError(`Unsupported KV client type "${options.type}"`);
21
+ throw new TypeError(`Unsupported KV client type "${type}"`);
22
22
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "1.1.1",
3
+ "version": "1.1.3",
4
4
  "type": "module",
5
5
  "main": "dist/mod.js",
6
6
  "types": "dist/mod.d.ts",
@@ -16,7 +16,7 @@
16
16
  "dependencies": {
17
17
  "@marianmeres/clog": "^2.3.3",
18
18
  "pg": "^8.16.3",
19
- "redis": "^5.9.0"
19
+ "redis": "^5.10.0"
20
20
  },
21
21
  "devDependencies": {
22
22
  "@types/node": "latest",