@marianmeres/kv 1.2.3 → 1.3.2

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 CHANGED
@@ -1,50 +1,61 @@
1
- # @marianmeres/kv - Agent Reference
1
+ # @marianmeres/kv — Agent Guide
2
2
 
3
3
  Machine-friendly reference for AI agents working with this codebase.
4
4
 
5
- ## Package Identity
5
+ ## Quick Reference
6
6
 
7
- - **Name**: `@marianmeres/kv`
8
- - **Version**: 1.2.2
9
- - **License**: MIT
10
- - **Runtime**: Deno (primary), Node.js (via npm build)
11
- - **Language**: TypeScript
7
+ - **Stack**: TypeScript, Deno (primary), Node.js (via npm build)
8
+ - **Run**: `deno task test` | **Build**: `deno task npm:build`
9
+ - **Version**: 1.3.1
12
10
 
13
11
  ## Purpose
14
12
 
15
13
  Key-value storage abstraction layer providing a unified Redis-inspired API across multiple storage backends.
16
14
 
17
- ## Supported Adapters
18
-
19
- | Adapter | Type String | Required Options | Limitations |
20
- |---------|-------------|------------------|-------------|
21
- | Memory | `"memory"` | None | Not persisted |
22
- | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
23
- | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | None |
24
- | Deno KV | `"deno-kv"` | `db` (Deno.Kv) | Deno runtime only; `delete()` always true; `expire()`/`ttl()` not supported |
25
-
26
- ## File Structure
15
+ ## Project Structure
27
16
 
28
17
  ```
29
18
  src/
30
- ├── mod.ts # Main entry point, re-exports kv.ts
31
- ├── kv.ts # Factory function and all exports
19
+ ├── mod.ts — Main entry point (re-exports kv.ts)
20
+ ├── kv.ts — Factory function and all exports
32
21
  ├── adapter/
33
- │ ├── abstract.ts # Base class + shared types
34
- │ ├── memory.ts # In-memory adapter
35
- │ ├── redis.ts # Redis adapter
36
- │ ├── postgres.ts # PostgreSQL adapter
37
- │ └── deno-kv.ts # Deno KV adapter
22
+ │ ├── abstract.ts — Base class + shared types
23
+ │ ├── memory.ts — In-memory adapter
24
+ │ ├── redis.ts — Redis adapter
25
+ │ ├── postgres.ts — PostgreSQL adapter
26
+ │ └── deno-kv.ts — Deno KV adapter
38
27
  └── utils/
39
- └── sleep.ts # Sleep utility function
28
+ └── sleep.ts — Sleep utility function
40
29
 
41
30
  tests/
42
- ├── kv.test.ts # Main test file
43
- ├── _tests-runner.ts # Test harness
44
- ├── _redis.ts # Redis test helper
45
- └── _pg.ts # PostgreSQL test helper
31
+ ├── kv.test.ts — Main test file
32
+ ├── _tests-runner.ts — Test harness
33
+ ├── _redis.ts — Redis test helper
34
+ └── _pg.ts — PostgreSQL test helper
46
35
  ```
47
36
 
37
+ ## Critical Conventions
38
+
39
+ 1. Namespace must end with `:` or be empty string
40
+ 2. Values are JSON-stringified internally
41
+ 3. TTL is in seconds; stored as absolute Date internally
42
+ 4. Pattern matching: Redis-style (`*` = any chars, `?` = single char)
43
+
44
+ ## Before Making Changes
45
+
46
+ - [ ] Check existing patterns in adapter implementations
47
+ - [ ] Run tests: `deno test --unstable-kv -A --env-file`
48
+ - [ ] Verify adapter limitations are documented
49
+
50
+ ## Supported Adapters
51
+
52
+ | Adapter | Type String | Required Options | Limitations |
53
+ |---------|-------------|------------------|-------------|
54
+ | Memory | `"memory"` | None | Not persisted |
55
+ | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
56
+ | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | None |
57
+ | Deno KV | `"deno-kv"` | `db` (Deno.Kv) | Deno runtime only; `delete()` always true; `expire()`/`ttl()` not supported |
58
+
48
59
  ## Core API
49
60
 
50
61
  ### Factory
@@ -92,9 +103,6 @@ deno test --unstable-kv -A --env-file --watch
92
103
 
93
104
  # Build npm package
94
105
  deno run -A scripts/build-npm.ts
95
-
96
- # Publish to npm
97
- deno run -A scripts/build-npm.ts && cd ./.npm-dist && npm publish --access=public
98
106
  ```
99
107
 
100
108
  ## Test Environment Variables
@@ -108,20 +116,6 @@ TEST_PG_PASSWORD=<required>
108
116
  TEST_REDIS_URL=redis://localhost:6379
109
117
  ```
110
118
 
111
- ## Implementation Notes
112
-
113
- 1. **Namespace**: Must end with `:` or be empty string
114
- 2. **Value Serialization**: All values JSON-stringified internally
115
- 3. **TTL**: In seconds; stored as absolute Date internally
116
- 4. **Pattern Matching**: Redis-style (`*` = any chars, `?` = single char)
117
- 5. **Transactions**: Atomic for Redis/PostgreSQL; sequential for memory/Deno KV
118
-
119
- ## Dependencies
120
-
121
- - `@marianmeres/clog` - Logging
122
- - `pg` - PostgreSQL driver
123
- - `redis` - Redis client
124
-
125
119
  ## Extending
126
120
 
127
121
  To add a new adapter:
@@ -131,3 +125,8 @@ To add a new adapter:
131
125
  4. Add to `KnownTypes` in `src/kv.ts`
132
126
  5. Add case in `createKVClient` factory
133
127
  6. Export from `src/kv.ts`
128
+
129
+ ## Documentation Index
130
+
131
+ - [API Reference](./API.md) — Complete API documentation
132
+ - [README](./README.md) — Quick start and installation
package/README.md CHANGED
@@ -84,3 +84,7 @@ client.ttl(key: string): Promise<Date | null | false>
84
84
  ## Full API Reference
85
85
 
86
86
  For complete API documentation including all methods, types, and adapter-specific options, see [API.md](API.md).
87
+
88
+ ## License
89
+
90
+ [MIT](LICENSE)
@@ -32,7 +32,7 @@ export class AdapterDenoKv extends AdapterAbstract {
32
32
  _type = "deno-kv";
33
33
  options = {
34
34
  defaultTtl: 0, // no ttl by default
35
- db: null,
35
+ db: null, // will be set in constructor via options merge
36
36
  logger: createClog("KV/deno-kv"),
37
37
  };
38
38
  constructor(namespace = "", options = {}) {
@@ -70,7 +70,7 @@ export declare class AdapterMemory extends AdapterAbstract {
70
70
  /** @inheritdoc */
71
71
  transaction(operations: Operation[]): Promise<any[]>;
72
72
  __debug_dump(): Promise<Record<string, {
73
- value: any;
73
+ value: unknown;
74
74
  ttl: Date | null | false;
75
75
  }>>;
76
76
  }
@@ -38,7 +38,7 @@ export class AdapterPostgres extends AdapterAbstract {
38
38
  options = {
39
39
  defaultTtl: 0, // no ttl by default
40
40
  logger: createClog("KV/postgres"),
41
- db: null,
41
+ db: null, // will be set in constructor via options merge
42
42
  tableName: "__kv",
43
43
  ttlCleanupIntervalSec: 0,
44
44
  };
@@ -71,6 +71,11 @@ export class AdapterPostgres extends AdapterAbstract {
71
71
  ON ${tableName} (expires_at)
72
72
  WHERE expires_at IS NOT NULL
73
73
  `);
74
+ // Index for efficient prefix lookups with LIKE 'prefix%' queries
75
+ await db.query(`
76
+ CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_key_prefix
77
+ ON ${tableName} (key text_pattern_ops)
78
+ `);
74
79
  this._initialized = true;
75
80
  this.#maybeTTLCleanup();
76
81
  }
@@ -180,16 +185,21 @@ export class AdapterPostgres extends AdapterAbstract {
180
185
  async clear(pattern) {
181
186
  this._assertInitialized();
182
187
  const { db, tableName } = this.options;
183
- let params = [];
184
- const query = `DELETE FROM ${tableName} WHERE key LIKE $1`;
185
- if (pattern === "*") {
186
- params = [this.namespace + "%"];
187
- }
188
- else {
189
- params = [this.namespace + this.#likePattern(pattern)];
190
- }
191
- const { rowCount } = await db.query(query, params);
192
- return rowCount;
188
+ const likePattern = pattern === "*"
189
+ ? this.namespace + "%"
190
+ : this.namespace + this.#likePattern(pattern);
191
+ // Batch large deletions to prevent long-running transactions
192
+ const batchSize = 10000;
193
+ let totalDeleted = 0;
194
+ let deleted;
195
+ do {
196
+ const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE key IN (
197
+ SELECT key FROM ${tableName} WHERE key LIKE $1 LIMIT $2
198
+ )`, [likePattern, batchSize]);
199
+ deleted = rowCount ?? 0;
200
+ totalDeleted += deleted;
201
+ } while (deleted === batchSize);
202
+ return totalDeleted;
193
203
  }
194
204
  /** @inheritdoc */
195
205
  async setMultiple(keyValuePairs, options = {}) {
@@ -36,7 +36,7 @@ export class AdapterRedis extends AdapterAbstract {
36
36
  options = {
37
37
  defaultTtl: 0, // no ttl by default
38
38
  logger: createClog("KV/redis"),
39
- db: null,
39
+ db: null, // will be set in constructor via options merge
40
40
  isCluster: false,
41
41
  };
42
42
  constructor(namespace = "", options = {}) {
@@ -97,7 +97,7 @@ export class AdapterRedis extends AdapterAbstract {
97
97
  this._assertInitialized();
98
98
  key = this._withNs(key);
99
99
  const { db } = this.options;
100
- return parseInt((await db.del(key))) > 0;
100
+ return Number(await db.del(key)) > 0;
101
101
  }
102
102
  /** @inheritdoc */
103
103
  async exists(key) {
@@ -111,9 +111,20 @@ export class AdapterRedis extends AdapterAbstract {
111
111
  this._assertInitialized();
112
112
  const { db, isCluster } = this.options;
113
113
  if (isCluster) {
114
- throw new Error("KEYS command not supported in Redis Cluster mode");
114
+ throw new Error("keys() is not supported in Redis Cluster mode");
115
115
  }
116
- const keys = (await db.keys(this.namespace + pattern));
116
+ // Use SCAN instead of KEYS for non-blocking iteration
117
+ const fullPattern = this.namespace + pattern;
118
+ const keys = [];
119
+ let cursor = "0";
120
+ do {
121
+ const result = await db.scan(cursor, {
122
+ MATCH: fullPattern,
123
+ COUNT: 100,
124
+ });
125
+ cursor = `${result.cursor}`;
126
+ keys.push(...result.keys.map((k) => String(k)));
127
+ } while (cursor !== "0");
117
128
  return keys
118
129
  .map((k) => {
119
130
  // strip namespace if exists
@@ -133,7 +144,8 @@ export class AdapterRedis extends AdapterAbstract {
133
144
  const keys = await this.keys(pattern);
134
145
  if (keys.length === 0)
135
146
  return 0;
136
- return parseInt((await db.del(keys.map((k) => this._withNs(k)))));
147
+ // Use UNLINK instead of DEL for non-blocking memory reclamation
148
+ return Number(await db.unlink(keys.map((k) => this._withNs(k))));
137
149
  }
138
150
  /** @inheritdoc */
139
151
  async setMultiple(keyValuePairs, options = {}) {
@@ -146,7 +158,7 @@ export class AdapterRedis extends AdapterAbstract {
146
158
  pipeline.set(key, JSON.stringify(value), { EX: ttl });
147
159
  }
148
160
  const res = await pipeline.exec();
149
- return res.map((v) => v === "OK");
161
+ return res.map((v) => String(v) === "OK");
150
162
  }
151
163
  /** @inheritdoc */
152
164
  async getMultiple(keys) {
@@ -176,7 +188,7 @@ export class AdapterRedis extends AdapterAbstract {
176
188
  async expire(key, ttl) {
177
189
  this._assertInitialized();
178
190
  key = this._withNs(key);
179
- return parseInt((await this.options.db.expire(key, ttl))) > 0;
191
+ return Number(await this.options.db.expire(key, ttl)) > 0;
180
192
  }
181
193
  /** @inheritdoc */
182
194
  async ttl(key) {
@@ -216,18 +228,18 @@ export class AdapterRedis extends AdapterAbstract {
216
228
  for (const [i, op] of operations.entries()) {
217
229
  switch (op.type) {
218
230
  case "set":
219
- res[i] = res[i] === "OK";
231
+ res[i] = String(res[i]) === "OK";
220
232
  break;
221
233
  case "get":
222
234
  try {
223
- res[i] = JSON.parse(res[i]);
235
+ res[i] = JSON.parse(String(res[i]));
224
236
  }
225
237
  catch (_e) {
226
238
  /**/
227
239
  }
228
240
  break;
229
241
  case "delete":
230
- res[i] = res[i] > 0;
242
+ res[i] = Number(res[i]) > 0;
231
243
  break;
232
244
  }
233
245
  }
@@ -241,7 +253,7 @@ export class AdapterRedis extends AdapterAbstract {
241
253
  const keys = (await db.keys("*")).toSorted();
242
254
  const out = {};
243
255
  for (const _key of keys) {
244
- const key = this._withoutNs(_key);
256
+ const key = this._withoutNs(String(_key));
245
257
  out[key] = {
246
258
  value: await this.get(key),
247
259
  ttl: await this.ttl(key),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "1.2.3",
3
+ "version": "1.3.2",
4
4
  "type": "module",
5
5
  "main": "dist/mod.js",
6
6
  "types": "dist/mod.d.ts",
@@ -13,10 +13,10 @@
13
13
  "author": "Marian Meres",
14
14
  "license": "MIT",
15
15
  "dependencies": {
16
- "@marianmeres/clog": "^3.15.0",
16
+ "@marianmeres/clog": "^3.15.2",
17
17
  "@types/pg": "^8.16.0",
18
18
  "@types/redis": "^4.0.10",
19
- "pg": "^8.16.3",
19
+ "pg": "^8.18.0",
20
20
  "redis": "^5.10.0"
21
21
  },
22
22
  "repository": {