@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/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, } from "./adapter/postgres.js";
10
+ import { AdapterPostgres } from "./adapter/postgres.js";
12
11
  import { AdapterRedis } from "./adapter/redis.js";
13
- export { AdapterAbstract, KvRaceError } from "./adapter/abstract.js";
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 { AdapterDenoKv } from "./adapter/deno-kv.js";
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
  }
@@ -22,7 +22,7 @@
22
22
  */
23
23
  export declare function sleep(timeout: number,
24
24
  /**
25
- * Deno.test is quite strict and reports every non-cleared timeout... so we have to
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
  *
@@ -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
- * Deno.test is quite strict and reports every non-cleared timeout... so we have to
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
- "name": "@marianmeres/kv",
3
- "version": "2.4.0",
4
- "type": "module",
5
- "main": "dist/mod.js",
6
- "types": "dist/mod.d.ts",
7
- "exports": {
8
- ".": {
9
- "types": "./dist/mod.d.ts",
10
- "import": "./dist/mod.js"
11
- }
12
- },
13
- "files": [
14
- "dist",
15
- "LICENSE",
16
- "README.md",
17
- "API.md",
18
- "AGENTS.md",
19
- "CLAUDE.md",
20
- "docs"
21
- ],
22
- "author": "Marian Meres",
23
- "license": "MIT",
24
- "dependencies": {
25
- "@marianmeres/clog": "^3.21.0",
26
- "@types/pg": "^8.20.0",
27
- "@types/redis": "^4.0.10",
28
- "pg": "^8.21.0",
29
- "redis": "^6.0.0"
30
- },
31
- "repository": {
32
- "type": "git",
33
- "url": "git+https://github.com/marianmeres/kv.git"
34
- },
35
- "bugs": {
36
- "url": "https://github.com/marianmeres/kv/issues"
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,3 +0,0 @@
1
- # Project Instructions
2
-
3
- See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.
@@ -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
- }