@iskra-bun/kv-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @iskra-bun/kv-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- f9654df: New KV features and a leak fix:
+
+    - **Fix:** the in-memory adapter no longer leaks TTL timers — expiry timers are tracked and cleared on overwrite/delete/disconnect, so overwriting a key can't have a stale timer delete the fresh value.
+    - `KVManager` accepts a `namespace` option that transparently prefixes every key, preventing cross-module collisions.
+    - Batch operations `mget`/`mset`/`mdel` on `KVManager`.
+
+### Patch Changes
+
+- f9654df: `KVAdapter.get`/`set` are now generic (`get<T>()` returns `Promise<T | undefined>`, `set<T>(key, value: T)`) — values are typed instead of `any`. Reads of a missing key now resolve to `undefined` (previously `null` on the Redis adapter). Consumers relying on `any` may need an explicit type argument when reading.
+- Fix value corruption in the Redis adapter's `set`/`get` codec. Values are now encoded with a single `JSON.stringify` and decoded with `JSON.parse`, so round-tripping is lossless: strings like `'123'` and `'{}'` stay strings, `undefined` is preserved instead of being stored as the literal text `"undefined"`, and `null` decodes back to `undefined`.
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -4,27 +4,42 @@ interface KVAdapter {
     id: string;
     connect(): Promise<void> | void;
     disconnect(): Promise<void> | void;
-    get(key: string): Promise<any>;
-    set(key: string, value: any, ttl?: number): Promise<void>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
     del(key: string): Promise<void>;
     has(key: string): Promise<boolean>;
+    mget?<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
+    mset?<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void>;
+    mdel?(keys: string[]): Promise<void>;
 }
 
+interface KVManagerOptions {
+    /**
+     * Optional namespace prepended to every key as `"<namespace>:<key>"`.
+     * Defaults to `""` (no prefix) to preserve existing behavior.
+     */
+    namespace?: string;
+}
 declare class KVManager implements Driver, KVAdapter {
     name: string;
     id: string;
     private app;
     private adapter;
-    constructor();
+    private readonly prefix;
+    constructor(options?: KVManagerOptions);
     init(app: App): void;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
-    get(key: string): Promise<any>;
-    set(key: string, value: any, ttl?: number): Promise<void>;
+    private prefixed;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
     del(key: string): Promise<void>;
     has(key: string): Promise<boolean>;
+    mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
+    mset<T = unknown>(entries: Array<[string, T]> | Record<string, T>, ttl?: number): Promise<void>;
+    mdel(keys: string[]): Promise<void>;
 }
 
 export { type KVAdapter, KVManager };

package/dist/index.js

@@ -2,21 +2,41 @@
 var MemoryAdapter = class {
   id = "memory";
   store = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
   connect() {
   }
   disconnect() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
     this.store.clear();
   }
   async get(key) {
     return this.store.get(key);
   }
   async set(key, value, ttl) {
+    const existing = this.timers.get(key);
+    if (existing !== void 0) {
+      clearTimeout(existing);
+      this.timers.delete(key);
+    }
     this.store.set(key, value);
     if (ttl) {
-      setTimeout(() => this.store.delete(key), ttl * 1e3);
+      const timer = setTimeout(() => {
+        this.store.delete(key);
+        this.timers.delete(key);
+      }, ttl * 1e3);
+      timer.unref?.();
+      this.timers.set(key, timer);
     }
   }
   async del(key) {
+    const timer = this.timers.get(key);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
     this.store.delete(key);
   }
   async has(key) {
@@ -26,6 +46,18 @@ var MemoryAdapter = class {
 
 // src/adapters/redis.ts
 import Redis from "ioredis";
+function encode(value) {
+  if (value === void 0) return "null";
+  return JSON.stringify(value);
+}
+function decode(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed === null ? void 0 : parsed;
+  } catch {
+    return raw;
+  }
+}
 var RedisAdapter = class {
   id = "redis";
   client = null;
@@ -41,14 +73,11 @@ var RedisAdapter = class {
   }
   async get(key) {
     const val = await this.client?.get(key);
-    try {
-      return val ? JSON.parse(val) : null;
-    } catch {
-      return val;
-    }
+    if (val === null || val === void 0) return void 0;
+    return decode(val);
   }
   async set(key, value, ttl) {
-    const val = typeof value === "object" ? JSON.stringify(value) : value;
+    const val = encode(value);
     if (ttl) {
       await this.client?.set(key, val, "EX", ttl);
     } else {
@@ -62,6 +91,34 @@ var RedisAdapter = class {
     const exists = await this.client?.exists(key);
     return exists === 1;
   }
+  // Native batch operations. A single MGET / pipelined MSET / variadic DEL
+  // replaces the manager's per-key fan-out (avoids the N+1 round-trips).
+  async mget(keys) {
+    if (keys.length === 0) return [];
+    const raws = await this.client?.mget(...keys) ?? [];
+    return keys.map((_, i) => {
+      const raw = raws[i];
+      return raw === null || raw === void 0 ? void 0 : decode(raw);
+    });
+  }
+  async mset(entries, ttl) {
+    if (entries.length === 0) return;
+    const pipeline = this.client?.pipeline();
+    if (!pipeline) return;
+    for (const [key, value] of entries) {
+      const val = encode(value);
+      if (ttl) {
+        pipeline.set(key, val, "EX", ttl);
+      } else {
+        pipeline.set(key, val);
+      }
+    }
+    await pipeline.exec();
+  }
+  async mdel(keys) {
+    if (keys.length === 0) return;
+    await this.client?.del(...keys);
+  }
 };
 
 // src/manager.ts
@@ -70,8 +127,10 @@ var KVManager = class {
   id = "manager";
   app = null;
   adapter;
-  constructor() {
+  prefix;
+  constructor(options = {}) {
     this.adapter = new MemoryAdapter();
+    this.prefix = options.namespace ? `${options.namespace}:` : "";
   }
   init(app) {
     this.app = app;
@@ -98,18 +157,52 @@ var KVManager = class {
   async stop() {
     await this.disconnect();
   }
-  // Proxy methods
+  prefixed(key) {
+    return `${this.prefix}${key}`;
+  }
+  // Proxy methods (namespace-aware)
   get(key) {
-    return this.adapter.get(key);
+    return this.adapter.get(this.prefixed(key));
   }
   set(key, value, ttl) {
-    return this.adapter.set(key, value, ttl);
+    return this.adapter.set(this.prefixed(key), value, ttl);
   }
   del(key) {
-    return this.adapter.del(key);
+    return this.adapter.del(this.prefixed(key));
   }
   has(key) {
-    return this.adapter.has(key);
+    return this.adapter.has(this.prefixed(key));
+  }
+  // Batch operations. When the underlying adapter exposes a native batch
+  // method, the manager delegates to it (a single round-trip) after applying
+  // the namespace prefix; otherwise it falls back to a per-key loop. This
+  // keeps the optional adapter methods out of the hot path for adapters that
+  // do not implement them while avoiding the N+1 fan-out for those that do.
+  async mget(keys) {
+    const prefixed = keys.map((k) => this.prefixed(k));
+    if (this.adapter.mget) {
+      return this.adapter.mget(prefixed);
+    }
+    return Promise.all(prefixed.map((k) => this.adapter.get(k)));
+  }
+  async mset(entries, ttl) {
+    const pairs = Array.isArray(entries) ? entries : Object.entries(entries);
+    const prefixed = pairs.map(
+      ([k, v]) => [this.prefixed(k), v]
+    );
+    if (this.adapter.mset) {
+      await this.adapter.mset(prefixed, ttl);
+      return;
+    }
+    await Promise.all(prefixed.map(([k, v]) => this.adapter.set(k, v, ttl)));
+  }
+  async mdel(keys) {
+    const prefixed = keys.map((k) => this.prefixed(k));
+    if (this.adapter.mdel) {
+      await this.adapter.mdel(prefixed);
+      return;
+    }
+    await Promise.all(prefixed.map((k) => this.adapter.del(k)));
   }
 };
 export {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/memory.ts","../src/adapters/redis.ts","../src/manager.ts"],"sourcesContent":["import type { KVAdapter } from '../types';\n\nexport class MemoryAdapter implements KVAdapter {\n    id = 'memory';\n    private store = new Map<string, any>();\n\n    connect() {\n        // No-op\n    }\n    disconnect() {\n        this.store.clear();\n    }\n\n    async get(key: string) {\n        return this.store.get(key);\n    }\n\n    async set(key: string, value: any, ttl?: number) {\n        this.store.set(key, value);\n        if (ttl) {\n            setTimeout(() => this.store.delete(key), ttl * 1000);\n        }\n    }\n\n    async del(key: string) {\n        this.store.delete(key);\n    }\n\n    async has(key: string) {\n        return this.store.has(key);\n    }\n}\n","import type { KVAdapter } from '../types';\nimport Redis from 'ioredis';\n\nexport class RedisAdapter implements KVAdapter {\n    id = 'redis';\n    private client: Redis | null = null;\n    private options: any;\n\n    constructor(options: any) {\n        this.options = options;\n    }\n\n    connect() {\n        this.client = new Redis(this.options);\n    }\n\n    disconnect() {\n        this.client?.disconnect();\n    }\n\n    async get(key: string) {\n        const val = await this.client?.get(key);\n        try {\n            return val ? JSON.parse(val) : null;\n        } catch {\n            return val;\n        }\n    }\n\n    async set(key: string, value: any, ttl?: number) {\n        const val = typeof value === 'object' ? JSON.stringify(value) : value;\n        if (ttl) {\n            await this.client?.set(key, val, 'EX', ttl);\n        } else {\n            await this.client?.set(key, val);\n        }\n    }\n\n    async del(key: string) {\n        await this.client?.del(key);\n    }\n\n    async has(key: string) {\n        const exists = await this.client?.exists(key);\n        return exists === 1;\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport type { KVAdapter } from './types';\nimport { MemoryAdapter } from './adapters/memory';\nimport { RedisAdapter } from './adapters/redis';\n\nexport class KVManager implements Driver, KVAdapter {\n    name = 'KVManager';\n    id = 'manager';\n    private app: App | null = null;\n    private adapter: KVAdapter;\n\n    constructor() {\n        // Default to memory until configured\n        this.adapter = new MemoryAdapter();\n    }\n\n    init(app: App) {\n        this.app = app;\n        const config = app.config.kv;\n\n        if (config?.driver === 'redis') {\n            app.logger.info('Initializing KV with Redis');\n            this.adapter = new RedisAdapter(config.connection);\n        } else {\n            app.logger.info('Initializing KV with Memory');\n            this.adapter = new MemoryAdapter();\n        }\n    }\n\n    async connect() {\n        await this.adapter.connect();\n        this.app?.logger.info('KV Store connected');\n    }\n\n    async disconnect() {\n        await this.adapter.disconnect();\n    }\n\n    // Driver Interface\n    async start() {\n        await this.connect();\n    }\n\n    async stop() {\n        await this.disconnect();\n    }\n\n    // Proxy methods\n    get(key: string) { return this.adapter.get(key); }\n    set(key: string, value: any, ttl?: number) { return this.adapter.set(key, value, ttl); }\n    del(key: string) { return this.adapter.del(key); }\n    has(key: string) { return this.adapter.has(key); }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/adapters/memory.ts","../src/adapters/redis.ts","../src/manager.ts"],"sourcesContent":["import type { KVAdapter } from '../types';\n\nexport class MemoryAdapter implements KVAdapter {\n    id = 'memory';\n    private store = new Map<string, unknown>();\n    private timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n    connect() {\n        // No-op\n    }\n\n    disconnect() {\n        for (const timer of this.timers.values()) {\n            clearTimeout(timer);\n        }\n        this.timers.clear();\n        this.store.clear();\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.store.get(key) as T | undefined;\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        // Note: storing `null`/`undefined` is undefined behavior across adapters.\n        // This in-memory adapter stores the value verbatim (so `get` returns it\n        // as-is), whereas the RedisAdapter normalizes both to \"absent\" because\n        // they have no faithful JSON round-trip. Callers should not depend on\n        // either form being preserved.\n        //\n        // Clear any existing expiry timer for this key before setting a new one\n        const existing = this.timers.get(key);\n        if (existing !== undefined) {\n            clearTimeout(existing);\n            this.timers.delete(key);\n        }\n\n        this.store.set(key, value);\n\n        if (ttl) {\n            const timer = setTimeout(() => {\n                this.store.delete(key);\n                this.timers.delete(key);\n            }, ttl * 1000);\n\n            // Avoid keeping the process alive just for expiry timers\n            timer.unref?.();\n\n            this.timers.set(key, timer);\n        }\n    }\n\n    async del(key: string): Promise<void> {\n        const timer = this.timers.get(key);\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            this.timers.delete(key);\n        }\n        this.store.delete(key);\n    }\n\n    async has(key: string): Promise<boolean> {\n        return this.store.has(key);\n    }\n}\n","import type { KVAdapter } from '../types';\nimport Redis from 'ioredis';\nimport type { RedisOptions } from 'ioredis';\n\n/**\n * Single consistent codec shared by every write/read path.\n *\n * `undefined` is guarded explicitly: there is no JSON representation for it,\n * so it is stored as the JSON `null` literal and decoded back to `undefined`\n * on read. Every other value is `JSON.stringify`'d on write and `JSON.parse`'d\n * on read, so the string \"123\" round-trips as the string \"123\" (not the number\n * 123) and \"{}\" round-trips as the string \"{}\" (not an empty object).\n */\nfunction encode<T>(value: T): string {\n    if (value === undefined) return 'null';\n    return JSON.stringify(value);\n}\n\nfunction decode<T>(raw: string): T | undefined {\n    try {\n        const parsed = JSON.parse(raw) as T | null;\n        return parsed === null ? undefined : (parsed as T);\n    } catch {\n        // Tolerate values written outside the adapter that are not valid JSON.\n        return raw as unknown as T;\n    }\n}\n\nexport class RedisAdapter implements KVAdapter {\n    id = 'redis';\n    private client: Redis | null = null;\n    private readonly options: RedisOptions | string;\n\n    constructor(options: RedisOptions | string) {\n        this.options = options;\n    }\n\n    connect() {\n        this.client = new Redis(this.options as RedisOptions);\n    }\n\n    disconnect() {\n        this.client?.disconnect();\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        const val = await this.client?.get(key);\n        if (val === null || val === undefined) return undefined;\n        return decode<T>(val);\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        const val = encode(value);\n        if (ttl) {\n            await this.client?.set(key, val, 'EX', ttl);\n        } else {\n            await this.client?.set(key, val);\n        }\n    }\n\n    async del(key: string) {\n        await this.client?.del(key);\n    }\n\n    async has(key: string) {\n        const exists = await this.client?.exists(key);\n        return exists === 1;\n    }\n\n    // Native batch operations. A single MGET / pipelined MSET / variadic DEL\n    // replaces the manager's per-key fan-out (avoids the N+1 round-trips).\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        if (keys.length === 0) return [];\n        const raws = (await this.client?.mget(...keys)) ?? [];\n        return keys.map((_, i) => {\n            const raw = raws[i];\n            return raw === null || raw === undefined ? undefined : decode<T>(raw);\n        });\n    }\n\n    async mset<T = unknown>(\n        entries: Array<[string, T]>,\n        ttl?: number\n    ): Promise<void> {\n        if (entries.length === 0) return;\n        const pipeline = this.client?.pipeline();\n        if (!pipeline) return;\n\n        for (const [key, value] of entries) {\n            const val = encode(value);\n            if (ttl) {\n                pipeline.set(key, val, 'EX', ttl);\n            } else {\n                pipeline.set(key, val);\n            }\n        }\n\n        await pipeline.exec();\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        if (keys.length === 0) return;\n        await this.client?.del(...keys);\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport type { KVAdapter } from './types';\nimport { MemoryAdapter } from './adapters/memory';\nimport { RedisAdapter } from './adapters/redis';\n\nexport interface KVManagerOptions {\n    /**\n     * Optional namespace prepended to every key as `\"<namespace>:<key>\"`.\n     * Defaults to `\"\"` (no prefix) to preserve existing behavior.\n     */\n    namespace?: string;\n}\n\nexport class KVManager implements Driver, KVAdapter {\n    name = 'KVManager';\n    id = 'manager';\n    private app: App | null = null;\n    private adapter: KVAdapter;\n    private readonly prefix: string;\n\n    constructor(options: KVManagerOptions = {}) {\n        // Default to memory until configured\n        this.adapter = new MemoryAdapter();\n        this.prefix = options.namespace ? `${options.namespace}:` : '';\n    }\n\n    init(app: App) {\n        this.app = app;\n        const config = app.config.kv;\n\n        if (config?.driver === 'redis') {\n            app.logger.info('Initializing KV with Redis');\n            this.adapter = new RedisAdapter(config.connection);\n        } else {\n            app.logger.info('Initializing KV with Memory');\n            this.adapter = new MemoryAdapter();\n        }\n    }\n\n    async connect() {\n        await this.adapter.connect();\n        this.app?.logger.info('KV Store connected');\n    }\n\n    async disconnect() {\n        await this.adapter.disconnect();\n    }\n\n    // Driver Interface\n    async start() {\n        await this.connect();\n    }\n\n    async stop() {\n        await this.disconnect();\n    }\n\n    private prefixed(key: string): string {\n        return `${this.prefix}${key}`;\n    }\n\n    // Proxy methods (namespace-aware)\n    get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.adapter.get<T>(this.prefixed(key));\n    }\n\n    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        return this.adapter.set<T>(this.prefixed(key), value, ttl);\n    }\n\n    del(key: string): Promise<void> {\n        return this.adapter.del(this.prefixed(key));\n    }\n\n    has(key: string): Promise<boolean> {\n        return this.adapter.has(this.prefixed(key));\n    }\n\n    // Batch operations. When the underlying adapter exposes a native batch\n    // method, the manager delegates to it (a single round-trip) after applying\n    // the namespace prefix; otherwise it falls back to a per-key loop. This\n    // keeps the optional adapter methods out of the hot path for adapters that\n    // do not implement them while avoiding the N+1 fan-out for those that do.\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        const prefixed = keys.map(k => this.prefixed(k));\n\n        if (this.adapter.mget) {\n            return this.adapter.mget<T>(prefixed);\n        }\n\n        return Promise.all(prefixed.map(k => this.adapter.get<T>(k)));\n    }\n\n    async mset<T = unknown>(\n        entries: Array<[string, T]> | Record<string, T>,\n        ttl?: number\n    ): Promise<void> {\n        const pairs: Array<[string, T]> = Array.isArray(entries)\n            ? entries\n            : (Object.entries(entries) as Array<[string, T]>);\n\n        const prefixed: Array<[string, T]> = pairs.map(\n            ([k, v]) => [this.prefixed(k), v] as [string, T]\n        );\n\n        if (this.adapter.mset) {\n            await this.adapter.mset<T>(prefixed, ttl);\n            return;\n        }\n\n        await Promise.all(prefixed.map(([k, v]) => this.adapter.set<T>(k, v, ttl)));\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        const prefixed = keys.map(k => this.prefixed(k));\n\n        if (this.adapter.mdel) {\n            await this.adapter.mdel(prefixed);\n            return;\n        }\n\n        await Promise.all(prefixed.map(k => this.adapter.del(k)));\n    }\n}\n"],"mappings":";AAEO,IAAM,gBAAN,MAAyC;AAAA,EAC5C,KAAK;AAAA,EACG,QAAQ,oBAAI,IAAqB;AAAA,EACjC,SAAS,oBAAI,IAA2C;AAAA,EAEhE,UAAU;AAAA,EAEV;AAAA,EAEA,aAAa;AACT,eAAW,SAAS,KAAK,OAAO,OAAO,GAAG;AACtC,mBAAa,KAAK;AAAA,IACtB;AACA,SAAK,OAAO,MAAM;AAClB,SAAK,MAAM,MAAM;AAAA,EACrB;AAAA,EAEA,MAAM,IAAiB,KAAqC;AACxD,WAAO,KAAK,MAAM,IAAI,GAAG;AAAA,EAC7B;AAAA,EAEA,MAAM,IAAiB,KAAa,OAAU,KAA6B;AAQvE,UAAM,WAAW,KAAK,OAAO,IAAI,GAAG;AACpC,QAAI,aAAa,QAAW;AACxB,mBAAa,QAAQ;AACrB,WAAK,OAAO,OAAO,GAAG;AAAA,IAC1B;AAEA,SAAK,MAAM,IAAI,KAAK,KAAK;AAEzB,QAAI,KAAK;AACL,YAAM,QAAQ,WAAW,MAAM;AAC3B,aAAK,MAAM,OAAO,GAAG;AACrB,aAAK,OAAO,OAAO,GAAG;AAAA,MAC1B,GAAG,MAAM,GAAI;AAGb,YAAM,QAAQ;AAEd,WAAK,OAAO,IAAI,KAAK,KAAK;AAAA,IAC9B;AAAA,EACJ;AAAA,EAEA,MAAM,IAAI,KAA4B;AAClC,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG;AACjC,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,WAAK,OAAO,OAAO,GAAG;AAAA,IAC1B;AACA,SAAK,MAAM,OAAO,GAAG;AAAA,EACzB;AAAA,EAEA,MAAM,IAAI,KAA+B;AACrC,WAAO,KAAK,MAAM,IAAI,GAAG;AAAA,EAC7B;AACJ;;;AC/DA,OAAO,WAAW;AAYlB,SAAS,OAAU,OAAkB;AACjC,MAAI,UAAU,OAAW,QAAO;AAChC,SAAO,KAAK,UAAU,KAAK;AAC/B;AAEA,SAAS,OAAU,KAA4B;AAC3C,MAAI;AACA,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,WAAO,WAAW,OAAO,SAAa;AAAA,EAC1C,QAAQ;AAEJ,WAAO;AAAA,EACX;AACJ;AAEO,IAAM,eAAN,MAAwC;AAAA,EAC3C,KAAK;AAAA,EACG,SAAuB;AAAA,EACd;AAAA,EAEjB,YAAY,SAAgC;AACxC,SAAK,UAAU;AAAA,EACnB;AAAA,EAEA,UAAU;AACN,SAAK,SAAS,IAAI,MAAM,KAAK,OAAuB;AAAA,EACxD;AAAA,EAEA,aAAa;AACT,SAAK,QAAQ,WAAW;AAAA,EAC5B;AAAA,EAEA,MAAM,IAAiB,KAAqC;AACxD,UAAM,MAAM,MAAM,KAAK,QAAQ,IAAI,GAAG;AACtC,QAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;AAC9C,WAAO,OAAU,GAAG;AAAA,EACxB;AAAA,EAEA,MAAM,IAAiB,KAAa,OAAU,KAA6B;AACvE,UAAM,MAAM,OAAO,KAAK;AACxB,QAAI,KAAK;AACL,YAAM,KAAK,QAAQ,IAAI,KAAK,KAAK,MAAM,GAAG;AAAA,IAC9C,OAAO;AACH,YAAM,KAAK,QAAQ,IAAI,KAAK,GAAG;AAAA,IACnC;AAAA,EACJ;AAAA,EAEA,MAAM,IAAI,KAAa;AACnB,UAAM,KAAK,QAAQ,IAAI,GAAG;AAAA,EAC9B;AAAA,EAEA,MAAM,IAAI,KAAa;AACnB,UAAM,SAAS,MAAM,KAAK,QAAQ,OAAO,GAAG;AAC5C,WAAO,WAAW;AAAA,EACtB;AAAA;AAAA;AAAA,EAKA,MAAM,KAAkB,MAA4C;AAChE,QAAI,KAAK,WAAW,EAAG,QAAO,CAAC;AAC/B,UAAM,OAAQ,MAAM,KAAK,QAAQ,KAAK,GAAG,IAAI,KAAM,CAAC;AACpD,WAAO,KAAK,IAAI,CAAC,GAAG,MAAM;AACtB,YAAM,MAAM,KAAK,CAAC;AAClB,aAAO,QAAQ,QAAQ,QAAQ,SAAY,SAAY,OAAU,GAAG;AAAA,IACxE,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,KACF,SACA,KACa;AACb,QAAI,QAAQ,WAAW,EAAG;AAC1B,UAAM,WAAW,KAAK,QAAQ,SAAS;AACvC,QAAI,CAAC,SAAU;AAEf,eAAW,CAAC,KAAK,KAAK,KAAK,SAAS;AAChC,YAAM,MAAM,OAAO,KAAK;AACxB,UAAI,KAAK;AACL,iBAAS,IAAI,KAAK,KAAK,MAAM,GAAG;AAAA,MACpC,OAAO;AACH,iBAAS,IAAI,KAAK,GAAG;AAAA,MACzB;AAAA,IACJ;AAEA,UAAM,SAAS,KAAK;AAAA,EACxB;AAAA,EAEA,MAAM,KAAK,MAA+B;AACtC,QAAI,KAAK,WAAW,EAAG;AACvB,UAAM,KAAK,QAAQ,IAAI,GAAG,IAAI;AAAA,EAClC;AACJ;;;AC5FO,IAAM,YAAN,MAA6C;AAAA,EAChD,OAAO;AAAA,EACP,KAAK;AAAA,EACG,MAAkB;AAAA,EAClB;AAAA,EACS;AAAA,EAEjB,YAAY,UAA4B,CAAC,GAAG;AAExC,SAAK,UAAU,IAAI,cAAc;AACjC,SAAK,SAAS,QAAQ,YAAY,GAAG,QAAQ,SAAS,MAAM;AAAA,EAChE;AAAA,EAEA,KAAK,KAAU;AACX,SAAK,MAAM;AACX,UAAM,SAAS,IAAI,OAAO;AAE1B,QAAI,QAAQ,WAAW,SAAS;AAC5B,UAAI,OAAO,KAAK,4BAA4B;AAC5C,WAAK,UAAU,IAAI,aAAa,OAAO,UAAU;AAAA,IACrD,OAAO;AACH,UAAI,OAAO,KAAK,6BAA6B;AAC7C,WAAK,UAAU,IAAI,cAAc;AAAA,IACrC;AAAA,EACJ;AAAA,EAEA,MAAM,UAAU;AACZ,UAAM,KAAK,QAAQ,QAAQ;AAC3B,SAAK,KAAK,OAAO,KAAK,oBAAoB;AAAA,EAC9C;AAAA,EAEA,MAAM,aAAa;AACf,UAAM,KAAK,QAAQ,WAAW;AAAA,EAClC;AAAA;AAAA,EAGA,MAAM,QAAQ;AACV,UAAM,KAAK,QAAQ;AAAA,EACvB;AAAA,EAEA,MAAM,OAAO;AACT,UAAM,KAAK,WAAW;AAAA,EAC1B;AAAA,EAEQ,SAAS,KAAqB;AAClC,WAAO,GAAG,KAAK,MAAM,GAAG,GAAG;AAAA,EAC/B;AAAA;AAAA,EAGA,IAAiB,KAAqC;AAClD,WAAO,KAAK,QAAQ,IAAO,KAAK,SAAS,GAAG,CAAC;AAAA,EACjD;AAAA,EAEA,IAAiB,KAAa,OAAU,KAA6B;AACjE,WAAO,KAAK,QAAQ,IAAO,KAAK,SAAS,GAAG,GAAG,OAAO,GAAG;AAAA,EAC7D;AAAA,EAEA,IAAI,KAA4B;AAC5B,WAAO,KAAK,QAAQ,IAAI,KAAK,SAAS,GAAG,CAAC;AAAA,EAC9C;AAAA,EAEA,IAAI,KAA+B;AAC/B,WAAO,KAAK,QAAQ,IAAI,KAAK,SAAS,GAAG,CAAC;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,KAAkB,MAA4C;AAChE,UAAM,WAAW,KAAK,IAAI,OAAK,KAAK,SAAS,CAAC,CAAC;AAE/C,QAAI,KAAK,QAAQ,MAAM;AACnB,aAAO,KAAK,QAAQ,KAAQ,QAAQ;AAAA,IACxC;AAEA,WAAO,QAAQ,IAAI,SAAS,IAAI,OAAK,KAAK,QAAQ,IAAO,CAAC,CAAC,CAAC;AAAA,EAChE;AAAA,EAEA,MAAM,KACF,SACA,KACa;AACb,UAAM,QAA4B,MAAM,QAAQ,OAAO,IACjD,UACC,OAAO,QAAQ,OAAO;AAE7B,UAAM,WAA+B,MAAM;AAAA,MACvC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC;AAAA,IACpC;AAEA,QAAI,KAAK,QAAQ,MAAM;AACnB,YAAM,KAAK,QAAQ,KAAQ,UAAU,GAAG;AACxC;AAAA,IACJ;AAEA,UAAM,QAAQ,IAAI,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAO,GAAG,GAAG,GAAG,CAAC,CAAC;AAAA,EAC9E;AAAA,EAEA,MAAM,KAAK,MAA+B;AACtC,UAAM,WAAW,KAAK,IAAI,OAAK,KAAK,SAAS,CAAC,CAAC;AAE/C,QAAI,KAAK,QAAQ,MAAM;AACnB,YAAM,KAAK,QAAQ,KAAK,QAAQ;AAChC;AAAA,IACJ;AAEA,UAAM,QAAQ,IAAI,SAAS,IAAI,OAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC;AAAA,EAC5D;AACJ;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/kv-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Key-Value store de Iskra con adaptadores de Redis y memoria.",
     "keywords": [
         "iskra",
@@ -47,7 +47,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.0",
+        "@iskra-bun/core": "0.1.1",
         "ioredis": "^5.4.1"
     },
     "devDependencies": {

package/src/adapters/memory.ts

@@ -2,31 +2,64 @@ import type { KVAdapter } from '../types';
 
 export class MemoryAdapter implements KVAdapter {
     id = 'memory';
-    private store = new Map<string, any>();
+    private store = new Map<string, unknown>();
+    private timers = new Map<string, ReturnType<typeof setTimeout>>();
 
     connect() {
         // No-op
     }
+
     disconnect() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
         this.store.clear();
     }
 
-    async get(key: string) {
-        return this.store.get(key);
+    async get<T = unknown>(key: string): Promise<T | undefined> {
+        return this.store.get(key) as T | undefined;
     }
 
-    async set(key: string, value: any, ttl?: number) {
+    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        // Note: storing `null`/`undefined` is undefined behavior across adapters.
+        // This in-memory adapter stores the value verbatim (so `get` returns it
+        // as-is), whereas the RedisAdapter normalizes both to "absent" because
+        // they have no faithful JSON round-trip. Callers should not depend on
+        // either form being preserved.
+        //
+        // Clear any existing expiry timer for this key before setting a new one
+        const existing = this.timers.get(key);
+        if (existing !== undefined) {
+            clearTimeout(existing);
+            this.timers.delete(key);
+        }
+
         this.store.set(key, value);
+
         if (ttl) {
-            setTimeout(() => this.store.delete(key), ttl * 1000);
+            const timer = setTimeout(() => {
+                this.store.delete(key);
+                this.timers.delete(key);
+            }, ttl * 1000);
+
+            // Avoid keeping the process alive just for expiry timers
+            timer.unref?.();
+
+            this.timers.set(key, timer);
         }
     }
 
-    async del(key: string) {
+    async del(key: string): Promise<void> {
+        const timer = this.timers.get(key);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.timers.delete(key);
+        }
         this.store.delete(key);
     }
 
-    async has(key: string) {
+    async has(key: string): Promise<boolean> {
         return this.store.has(key);
     }
 }

package/src/adapters/redis.ts

@@ -1,34 +1,56 @@
 import type { KVAdapter } from '../types';
 import Redis from 'ioredis';
+import type { RedisOptions } from 'ioredis';
+
+/**
+ * Single consistent codec shared by every write/read path.
+ *
+ * `undefined` is guarded explicitly: there is no JSON representation for it,
+ * so it is stored as the JSON `null` literal and decoded back to `undefined`
+ * on read. Every other value is `JSON.stringify`'d on write and `JSON.parse`'d
+ * on read, so the string "123" round-trips as the string "123" (not the number
+ * 123) and "{}" round-trips as the string "{}" (not an empty object).
+ */
+function encode<T>(value: T): string {
+    if (value === undefined) return 'null';
+    return JSON.stringify(value);
+}
+
+function decode<T>(raw: string): T | undefined {
+    try {
+        const parsed = JSON.parse(raw) as T | null;
+        return parsed === null ? undefined : (parsed as T);
+    } catch {
+        // Tolerate values written outside the adapter that are not valid JSON.
+        return raw as unknown as T;
+    }
+}
 
 export class RedisAdapter implements KVAdapter {
     id = 'redis';
     private client: Redis | null = null;
-    private options: any;
+    private readonly options: RedisOptions | string;
 
-    constructor(options: any) {
+    constructor(options: RedisOptions | string) {
         this.options = options;
     }
 
     connect() {
-        this.client = new Redis(this.options);
+        this.client = new Redis(this.options as RedisOptions);
     }
 
     disconnect() {
         this.client?.disconnect();
     }
 
-    async get(key: string) {
+    async get<T = unknown>(key: string): Promise<T | undefined> {
         const val = await this.client?.get(key);
-        try {
-            return val ? JSON.parse(val) : null;
-        } catch {
-            return val;
-        }
+        if (val === null || val === undefined) return undefined;
+        return decode<T>(val);
     }
 
-    async set(key: string, value: any, ttl?: number) {
-        const val = typeof value === 'object' ? JSON.stringify(value) : value;
+    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        const val = encode(value);
         if (ttl) {
             await this.client?.set(key, val, 'EX', ttl);
         } else {
@@ -44,4 +66,41 @@ export class RedisAdapter implements KVAdapter {
         const exists = await this.client?.exists(key);
         return exists === 1;
     }
+
+    // Native batch operations. A single MGET / pipelined MSET / variadic DEL
+    // replaces the manager's per-key fan-out (avoids the N+1 round-trips).
+
+    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {
+        if (keys.length === 0) return [];
+        const raws = (await this.client?.mget(...keys)) ?? [];
+        return keys.map((_, i) => {
+            const raw = raws[i];
+            return raw === null || raw === undefined ? undefined : decode<T>(raw);
+        });
+    }
+
+    async mset<T = unknown>(
+        entries: Array<[string, T]>,
+        ttl?: number
+    ): Promise<void> {
+        if (entries.length === 0) return;
+        const pipeline = this.client?.pipeline();
+        if (!pipeline) return;
+
+        for (const [key, value] of entries) {
+            const val = encode(value);
+            if (ttl) {
+                pipeline.set(key, val, 'EX', ttl);
+            } else {
+                pipeline.set(key, val);
+            }
+        }
+
+        await pipeline.exec();
+    }
+
+    async mdel(keys: string[]): Promise<void> {
+        if (keys.length === 0) return;
+        await this.client?.del(...keys);
+    }
 }

package/src/manager.ts

@@ -3,15 +3,25 @@ import type { KVAdapter } from './types';
 import { MemoryAdapter } from './adapters/memory';
 import { RedisAdapter } from './adapters/redis';
 
+export interface KVManagerOptions {
+    /**
+     * Optional namespace prepended to every key as `"<namespace>:<key>"`.
+     * Defaults to `""` (no prefix) to preserve existing behavior.
+     */
+    namespace?: string;
+}
+
 export class KVManager implements Driver, KVAdapter {
     name = 'KVManager';
     id = 'manager';
     private app: App | null = null;
     private adapter: KVAdapter;
+    private readonly prefix: string;
 
-    constructor() {
+    constructor(options: KVManagerOptions = {}) {
         // Default to memory until configured
         this.adapter = new MemoryAdapter();
+        this.prefix = options.namespace ? `${options.namespace}:` : '';
     }
 
     init(app: App) {
@@ -45,9 +55,71 @@ export class KVManager implements Driver, KVAdapter {
         await this.disconnect();
     }
 
-    // Proxy methods
-    get(key: string) { return this.adapter.get(key); }
-    set(key: string, value: any, ttl?: number) { return this.adapter.set(key, value, ttl); }
-    del(key: string) { return this.adapter.del(key); }
-    has(key: string) { return this.adapter.has(key); }
+    private prefixed(key: string): string {
+        return `${this.prefix}${key}`;
+    }
+
+    // Proxy methods (namespace-aware)
+    get<T = unknown>(key: string): Promise<T | undefined> {
+        return this.adapter.get<T>(this.prefixed(key));
+    }
+
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        return this.adapter.set<T>(this.prefixed(key), value, ttl);
+    }
+
+    del(key: string): Promise<void> {
+        return this.adapter.del(this.prefixed(key));
+    }
+
+    has(key: string): Promise<boolean> {
+        return this.adapter.has(this.prefixed(key));
+    }
+
+    // Batch operations. When the underlying adapter exposes a native batch
+    // method, the manager delegates to it (a single round-trip) after applying
+    // the namespace prefix; otherwise it falls back to a per-key loop. This
+    // keeps the optional adapter methods out of the hot path for adapters that
+    // do not implement them while avoiding the N+1 fan-out for those that do.
+
+    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {
+        const prefixed = keys.map(k => this.prefixed(k));
+
+        if (this.adapter.mget) {
+            return this.adapter.mget<T>(prefixed);
+        }
+
+        return Promise.all(prefixed.map(k => this.adapter.get<T>(k)));
+    }
+
+    async mset<T = unknown>(
+        entries: Array<[string, T]> | Record<string, T>,
+        ttl?: number
+    ): Promise<void> {
+        const pairs: Array<[string, T]> = Array.isArray(entries)
+            ? entries
+            : (Object.entries(entries) as Array<[string, T]>);
+
+        const prefixed: Array<[string, T]> = pairs.map(
+            ([k, v]) => [this.prefixed(k), v] as [string, T]
+        );
+
+        if (this.adapter.mset) {
+            await this.adapter.mset<T>(prefixed, ttl);
+            return;
+        }
+
+        await Promise.all(prefixed.map(([k, v]) => this.adapter.set<T>(k, v, ttl)));
+    }
+
+    async mdel(keys: string[]): Promise<void> {
+        const prefixed = keys.map(k => this.prefixed(k));
+
+        if (this.adapter.mdel) {
+            await this.adapter.mdel(prefixed);
+            return;
+        }
+
+        await Promise.all(prefixed.map(k => this.adapter.del(k)));
+    }
 }

package/src/types.ts

@@ -3,8 +3,20 @@ export interface KVAdapter {
     connect(): Promise<void> | void;
     disconnect(): Promise<void> | void;
 
-    get(key: string): Promise<any>;
-    set(key: string, value: any, ttl?: number): Promise<void>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
     del(key: string): Promise<void>;
     has(key: string): Promise<boolean>;
+
+    // Optional native batch operations. When an adapter implements these, the
+    // KVManager prefers them over a per-key loop to avoid N+1 round-trips.
+    // Adapters that omit them remain fully compatible.
+    //
+    // Storing `null`/`undefined` is normalized to "absent" by the adapters that
+    // round-trip through JSON (see RedisAdapter); the in-memory adapter stores
+    // them verbatim. Callers should treat `null`/`undefined` values as
+    // undefined behavior and avoid relying on either form being preserved.
+    mget?<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
+    mset?<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void>;
+    mdel?(keys: string[]): Promise<void>;
 }