@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 +45 -46
- package/README.md +4 -0
- package/dist/adapter/deno-kv.js +1 -1
- package/dist/adapter/memory.d.ts +1 -1
- package/dist/adapter/postgres.js +21 -11
- package/dist/adapter/redis.js +23 -11
- package/package.json +3 -3
package/AGENTS.md
CHANGED
|
@@ -1,50 +1,61 @@
|
|
|
1
|
-
# @marianmeres/kv
|
|
1
|
+
# @marianmeres/kv — Agent Guide
|
|
2
2
|
|
|
3
3
|
Machine-friendly reference for AI agents working with this codebase.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Quick Reference
|
|
6
6
|
|
|
7
|
-
- **
|
|
8
|
-
- **
|
|
9
|
-
- **
|
|
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
|
-
##
|
|
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
|
|
31
|
-
├── kv.ts
|
|
19
|
+
├── mod.ts — Main entry point (re-exports kv.ts)
|
|
20
|
+
├── kv.ts — Factory function and all exports
|
|
32
21
|
├── adapter/
|
|
33
|
-
│ ├── abstract.ts
|
|
34
|
-
│ ├── memory.ts
|
|
35
|
-
│ ├── redis.ts
|
|
36
|
-
│ ├── postgres.ts
|
|
37
|
-
│ └── deno-kv.ts
|
|
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
|
|
28
|
+
└── sleep.ts — Sleep utility function
|
|
40
29
|
|
|
41
30
|
tests/
|
|
42
|
-
├── kv.test.ts
|
|
43
|
-
├── _tests-runner.ts
|
|
44
|
-
├── _redis.ts
|
|
45
|
-
└── _pg.ts
|
|
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
package/dist/adapter/deno-kv.js
CHANGED
|
@@ -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 = {}) {
|
package/dist/adapter/memory.d.ts
CHANGED
package/dist/adapter/postgres.js
CHANGED
|
@@ -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
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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 = {}) {
|
package/dist/adapter/redis.js
CHANGED
|
@@ -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
|
|
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("
|
|
114
|
+
throw new Error("keys() is not supported in Redis Cluster mode");
|
|
115
115
|
}
|
|
116
|
-
|
|
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
|
-
|
|
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
|
|
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
|
+
"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.
|
|
16
|
+
"@marianmeres/clog": "^3.15.2",
|
|
17
17
|
"@types/pg": "^8.16.0",
|
|
18
18
|
"@types/redis": "^4.0.10",
|
|
19
|
-
"pg": "^8.
|
|
19
|
+
"pg": "^8.18.0",
|
|
20
20
|
"redis": "^5.10.0"
|
|
21
21
|
},
|
|
22
22
|
"repository": {
|