@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.
Files changed (3) hide show
  1. package/AGENTS.md +45 -46
  2. package/README.md +4 -0
  3. package/package.json +3 -3
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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "1.3.1",
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.17.1",
19
+ "pg": "^8.18.0",
20
20
  "redis": "^5.10.0"
21
21
  },
22
22
  "repository": {