@marianmeres/kv 2.4.0 → 3.0.0
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 +85 -54
- package/API.md +151 -209
- package/README.md +69 -42
- package/dist/adapter/abstract.d.ts +6 -17
- package/dist/adapter/abstract.js +10 -24
- package/dist/adapter/memory.d.ts +2 -3
- package/dist/adapter/memory.js +2 -5
- package/dist/adapter/postgres.d.ts +1 -2
- package/dist/adapter/postgres.js +5 -6
- package/dist/adapter/redis.d.ts +1 -2
- package/dist/adapter/redis.js +4 -7
- package/dist/{mod.d.ts → index.d.ts} +1 -2
- package/dist/{mod.js → index.js} +0 -1
- package/dist/kv.d.ts +9 -22
- package/dist/kv.js +3 -18
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +70 -37
- package/CLAUDE.md +0 -3
- package/dist/adapter/deno-kv.d.ts +0 -107
- package/dist/adapter/deno-kv.js +0 -396
package/dist/kv.js
CHANGED
|
@@ -6,15 +6,13 @@
|
|
|
6
6
|
* Exports the main {@link createKVClient} factory function and re-exports
|
|
7
7
|
* all adapter classes, types, and interfaces.
|
|
8
8
|
*/
|
|
9
|
-
import { AdapterDenoKv } from "./adapter/deno-kv.js";
|
|
10
9
|
import { AdapterMemory } from "./adapter/memory.js";
|
|
11
|
-
import { AdapterPostgres
|
|
10
|
+
import { AdapterPostgres } from "./adapter/postgres.js";
|
|
12
11
|
import { AdapterRedis } from "./adapter/redis.js";
|
|
13
|
-
export { AdapterAbstract
|
|
12
|
+
export { AdapterAbstract } from "./adapter/abstract.js";
|
|
14
13
|
export { AdapterMemory } from "./adapter/memory.js";
|
|
15
|
-
export { AdapterRedis } from "./adapter/redis.js";
|
|
16
14
|
export { AdapterPostgres } from "./adapter/postgres.js";
|
|
17
|
-
export {
|
|
15
|
+
export { AdapterRedis } from "./adapter/redis.js";
|
|
18
16
|
export { sleep } from "./utils/sleep.js";
|
|
19
17
|
/**
|
|
20
18
|
* Factory function to create a KV client with the specified adapter type.
|
|
@@ -30,14 +28,12 @@ export { sleep } from "./utils/sleep.js";
|
|
|
30
28
|
* - `"memory"` - In-memory storage (default, not persisted)
|
|
31
29
|
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
32
30
|
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
33
|
-
* - `"deno-kv"` - Deno KV (Deno runtime only, requires `db` option with Deno.Kv)
|
|
34
31
|
* @param options - Adapter-specific configuration options.
|
|
35
32
|
*
|
|
36
33
|
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
37
34
|
*
|
|
38
35
|
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
39
36
|
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
40
|
-
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
41
37
|
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
42
38
|
*
|
|
43
39
|
* @example
|
|
@@ -57,11 +53,6 @@ export { sleep } from "./utils/sleep.js";
|
|
|
57
53
|
* const pool = new pg.Pool({ connectionString: '...' });
|
|
58
54
|
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
59
55
|
* await postgres.initialize();
|
|
60
|
-
*
|
|
61
|
-
* // Deno KV (Deno runtime only)
|
|
62
|
-
* const kv = await Deno.openKv();
|
|
63
|
-
* const denoKv = createKVClient("myapp:", "deno-kv", { db: kv });
|
|
64
|
-
* await denoKv.initialize();
|
|
65
56
|
* ```
|
|
66
57
|
*/
|
|
67
58
|
export function createKVClient(namespace = "", type = "memory", options = {}) {
|
|
@@ -72,12 +63,6 @@ export function createKVClient(namespace = "", type = "memory", options = {}) {
|
|
|
72
63
|
return new AdapterPostgres(namespace, options);
|
|
73
64
|
if (type === "redis")
|
|
74
65
|
return new AdapterRedis(namespace, options);
|
|
75
|
-
if (type === "deno-kv") {
|
|
76
|
-
if (typeof globalThis.Deno === "undefined") {
|
|
77
|
-
throw new Error(`Type "${type}" is only supported under Deno runtime`);
|
|
78
|
-
}
|
|
79
|
-
return new AdapterDenoKv(namespace, options);
|
|
80
|
-
}
|
|
81
66
|
//
|
|
82
67
|
throw new TypeError(`Unsupported KV client type "${type}"`);
|
|
83
68
|
}
|
package/dist/utils/sleep.d.ts
CHANGED
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
*/
|
|
23
23
|
export declare function sleep(timeout: number,
|
|
24
24
|
/**
|
|
25
|
-
*
|
|
25
|
+
* A pending timeout keeps the process (and a test run) alive... so we have to
|
|
26
26
|
* be able to pass in some object ref if needed (eg when sleep is not resolved via Promise.race)
|
|
27
27
|
* to be able to do the clearing eventually.
|
|
28
28
|
*
|
package/dist/utils/sleep.js
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
// deno-lint-ignore-file no-explicit-any
|
|
2
1
|
/**
|
|
3
2
|
* @module
|
|
4
3
|
*
|
|
@@ -23,7 +22,7 @@
|
|
|
23
22
|
*/
|
|
24
23
|
export function sleep(timeout,
|
|
25
24
|
/**
|
|
26
|
-
*
|
|
25
|
+
* A pending timeout keeps the process (and a test run) alive... so we have to
|
|
27
26
|
* be able to pass in some object ref if needed (eg when sleep is not resolved via Promise.race)
|
|
28
27
|
* to be able to do the clearing eventually.
|
|
29
28
|
*
|
|
@@ -31,6 +30,7 @@ export function sleep(timeout,
|
|
|
31
30
|
*/
|
|
32
31
|
__timeout_ref__ = { id: -1 }) {
|
|
33
32
|
return new Promise((resolve) => {
|
|
33
|
+
// Node returns a Timeout object, not a number; clearTimeout accepts either
|
|
34
34
|
__timeout_ref__.id = setTimeout(() => {
|
|
35
35
|
clearTimeout(__timeout_ref__.id);
|
|
36
36
|
resolve(undefined);
|
package/package.json
CHANGED
|
@@ -1,38 +1,71 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
2
|
+
"name": "@marianmeres/kv",
|
|
3
|
+
"version": "3.0.0",
|
|
4
|
+
"description": "Key-value storage abstraction with a unified, Redis-inspired API over memory, Redis and PostgreSQL backends.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Marian Meres",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"engines": {
|
|
9
|
+
"node": ">=24.12"
|
|
10
|
+
},
|
|
11
|
+
"publishConfig": {
|
|
12
|
+
"access": "public"
|
|
13
|
+
},
|
|
14
|
+
"sideEffects": false,
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"types": "./dist/index.d.ts",
|
|
18
|
+
"default": "./dist/index.js"
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"dist",
|
|
23
|
+
"API.md",
|
|
24
|
+
"AGENTS.md"
|
|
25
|
+
],
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/marianmeres/kv.git"
|
|
29
|
+
},
|
|
30
|
+
"bugs": {
|
|
31
|
+
"url": "https://github.com/marianmeres/kv/issues"
|
|
32
|
+
},
|
|
33
|
+
"homepage": "https://github.com/marianmeres/kv#readme",
|
|
34
|
+
"keywords": [
|
|
35
|
+
"kv",
|
|
36
|
+
"key-value",
|
|
37
|
+
"redis",
|
|
38
|
+
"postgres",
|
|
39
|
+
"postgresql",
|
|
40
|
+
"cache",
|
|
41
|
+
"ttl",
|
|
42
|
+
"storage"
|
|
43
|
+
],
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@marianmeres/clog": "^3.21.0",
|
|
46
|
+
"@types/pg": "^8.20.0",
|
|
47
|
+
"pg": "^8.21.0",
|
|
48
|
+
"redis": "^6.0.0"
|
|
49
|
+
},
|
|
50
|
+
"devDependencies": {
|
|
51
|
+
"@biomejs/biome": "^2.6.3",
|
|
52
|
+
"@types/node": "^26.6.5",
|
|
53
|
+
"typescript": "^7.0.2"
|
|
54
|
+
},
|
|
55
|
+
"scripts": {
|
|
56
|
+
"build": "pnpm run clean && tsc -p tsconfig.build.json",
|
|
57
|
+
"clean": "rm -rf dist",
|
|
58
|
+
"typecheck": "tsc --noEmit",
|
|
59
|
+
"lint": "biome check .",
|
|
60
|
+
"format": "biome check --write .",
|
|
61
|
+
"test": "node --test --env-file-if-exists=.env \"tests/**/*.test.ts\"",
|
|
62
|
+
"test:watch": "node --test --watch --env-file-if-exists=.env \"tests/**/*.test.ts\"",
|
|
63
|
+
"test:deno": "deno test -A --no-check --env-file tests/",
|
|
64
|
+
"ci": "pnpm run typecheck && pnpm run lint && pnpm test",
|
|
65
|
+
"release": "npx --yes @marianmeres/release@^2.2.0",
|
|
66
|
+
"publish:jsr": "pnpm run test:deno && deno publish --no-check --set-version \"$npm_package_version\"",
|
|
67
|
+
"publish:all": "pnpm publish && pnpm run publish:jsr",
|
|
68
|
+
"rp": "pnpm run release -y && pnpm run publish:all",
|
|
69
|
+
"rpm": "pnpm run release minor -y && pnpm run publish:all"
|
|
70
|
+
}
|
|
71
|
+
}
|
package/CLAUDE.md
DELETED
|
@@ -1,107 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @module
|
|
3
|
-
*
|
|
4
|
-
* Deno KV key-value storage adapter implementation.
|
|
5
|
-
*/
|
|
6
|
-
import { AdapterAbstract, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult, type AdapterAbstractOptions } from "./abstract.js";
|
|
7
|
-
/**
|
|
8
|
-
* Configuration options for the Deno KV adapter.
|
|
9
|
-
*/
|
|
10
|
-
export interface AdapterDenoKvOptions extends AdapterAbstractOptions {
|
|
11
|
-
/**
|
|
12
|
-
* Deno.Kv instance obtained via `Deno.openKv()`.
|
|
13
|
-
* @see https://docs.deno.com/deploy/kv/#testing
|
|
14
|
-
*/
|
|
15
|
-
db: any;
|
|
16
|
-
/**
|
|
17
|
-
* When `true`, `delete()` pre-checks the key's existence and returns
|
|
18
|
-
* the real "did it exist?" flag — at the cost of one extra round-trip.
|
|
19
|
-
* Default `false` preserves the Deno.Kv native "always true" behavior.
|
|
20
|
-
*/
|
|
21
|
-
strictDeleteResult?: boolean;
|
|
22
|
-
/**
|
|
23
|
-
* Max retry attempts for CAS-based primitives (`incr`, `decr`, `getSet`,
|
|
24
|
-
* `cas`) before throwing `KvRaceError`. Each attempt waits a small
|
|
25
|
-
* exponential-backoff delay, so 20 retries covers substantial contention
|
|
26
|
-
* without blocking callers for long.
|
|
27
|
-
* @default 20
|
|
28
|
-
*/
|
|
29
|
-
atomicRetryAttempts?: number;
|
|
30
|
-
}
|
|
31
|
-
/**
|
|
32
|
-
* Deno KV key-value storage adapter.
|
|
33
|
-
*
|
|
34
|
-
* Provides persistent key-value storage using Deno's built-in KV store.
|
|
35
|
-
* Only available when running in the Deno runtime.
|
|
36
|
-
*
|
|
37
|
-
* @remarks
|
|
38
|
-
* - Only works in Deno runtime (will throw error in Node.js)
|
|
39
|
-
* - `delete()` returns `true` by default even for missing keys (Deno.Kv
|
|
40
|
-
* limitation); opt in to strict behavior via `strictDeleteResult: true`
|
|
41
|
-
* - `expire()` is not supported — always returns `false`
|
|
42
|
-
* - `ttl()` returns `{ state: "no-ttl" }` for present keys (TTL cannot be
|
|
43
|
-
* queried) and `{ state: "missing" }` for absent ones
|
|
44
|
-
* - Uses `getMany()` for efficient batch reads
|
|
45
|
-
* - Atomic primitives (`incr`, `decr`, `getSet`, `cas`) use a CAS retry loop
|
|
46
|
-
* backed by Deno.Kv's native `atomic().check()`
|
|
47
|
-
*
|
|
48
|
-
* @example
|
|
49
|
-
* ```typescript
|
|
50
|
-
* const kv = await Deno.openKv();
|
|
51
|
-
* const client = createKVClient("myapp:", "deno-kv", { db: kv });
|
|
52
|
-
* await client.initialize();
|
|
53
|
-
* await client.set("user:123", { name: "John" }, { ttl: 3600 });
|
|
54
|
-
* ```
|
|
55
|
-
*/
|
|
56
|
-
export declare class AdapterDenoKv extends AdapterAbstract {
|
|
57
|
-
#private;
|
|
58
|
-
readonly namespace: string;
|
|
59
|
-
_type: string;
|
|
60
|
-
readonly options: AdapterDenoKvOptions;
|
|
61
|
-
constructor(namespace?: string, options?: Partial<AdapterDenoKvOptions>);
|
|
62
|
-
/** @inheritdoc */
|
|
63
|
-
initialize(): Promise<void>;
|
|
64
|
-
/** @inheritdoc */
|
|
65
|
-
destroy(_hard?: boolean): Promise<void>;
|
|
66
|
-
/** @inheritdoc */
|
|
67
|
-
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
68
|
-
/** @inheritdoc */
|
|
69
|
-
setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
70
|
-
/** @inheritdoc */
|
|
71
|
-
getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>;
|
|
72
|
-
/** @inheritdoc */
|
|
73
|
-
incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
74
|
-
/** @inheritdoc */
|
|
75
|
-
decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
76
|
-
/** @inheritdoc */
|
|
77
|
-
cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
78
|
-
/** @inheritdoc */
|
|
79
|
-
get(key: string): Promise<any>;
|
|
80
|
-
/** @inheritdoc */
|
|
81
|
-
exists(key: string): Promise<boolean>;
|
|
82
|
-
/** @inheritdoc */
|
|
83
|
-
delete(key: string): Promise<boolean>;
|
|
84
|
-
/** @inheritdoc */
|
|
85
|
-
keys(pattern: string): Promise<string[]>;
|
|
86
|
-
/** @inheritdoc */
|
|
87
|
-
keysIter(pattern: string): AsyncIterable<string>;
|
|
88
|
-
/** @inheritdoc */
|
|
89
|
-
clear(pattern: string): Promise<number>;
|
|
90
|
-
/** @inheritdoc */
|
|
91
|
-
setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
92
|
-
/** @inheritdoc */
|
|
93
|
-
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
94
|
-
/** @inheritdoc */
|
|
95
|
-
transaction(operations: Operation[]): Promise<any[]>;
|
|
96
|
-
/**
|
|
97
|
-
* Not supported in Deno.Kv — always returns `false`.
|
|
98
|
-
* @inheritdoc
|
|
99
|
-
*/
|
|
100
|
-
expire(_key: string, _ttl: number): Promise<boolean>;
|
|
101
|
-
/**
|
|
102
|
-
* Deno.Kv cannot report TTL state. Returns `{ state: "no-ttl" }` for
|
|
103
|
-
* existing keys (whether or not they actually have an expireIn set)
|
|
104
|
-
* and `{ state: "missing" }` for absent keys.
|
|
105
|
-
*/
|
|
106
|
-
ttl(key: string): Promise<TtlResult>;
|
|
107
|
-
}
|