@marianmeres/kv 1.3.1 → 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/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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@marianmeres/kv",
|
|
3
|
-
"version": "1.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.
|
|
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": {
|