@iskra-bun/kv-kit 0.2.0 → 0.3.1

package/src/manager.ts

@@ -1,4 +1,5 @@
-import type { App, Driver } from '@iskra-bun/core';
+import { isProductionEnv, type App, type Driver } from '@iskra-bun/core';
+import type { Redis } from 'ioredis';
 import type { KVAdapter } from './types';
 import { MemoryAdapter } from './adapters/memory';
 import { RedisAdapter } from './adapters/redis';
@@ -9,6 +10,11 @@ export interface KVManagerOptions {
      * Defaults to `""` (no prefix) to preserve existing behavior.
      */
     namespace?: string;
+    /**
+     * Lets `clear()` without a `namespace` empty the whole Redis database
+     * (FLUSHDB). Only for a database no other app or service writes to.
+     */
+    flushDb?: boolean;
 }
 
 export class KVManager implements Driver, KVAdapter {
@@ -17,23 +23,51 @@ export class KVManager implements Driver, KVAdapter {
     private app: App | null = null;
     private adapter: KVAdapter;
     private readonly prefix: string;
+    private readonly flushDb: boolean;
 
     constructor(options: KVManagerOptions = {}) {
+        // The store is chosen by the App's config (`kv.driver`), not here: an
+        // `adapter: 'redis'` copied from an old README was ignored, and the app
+        // silently ran on per-process memory.
+        const misplaced = ['adapter', 'driver', 'connection'].filter((key) => key in options);
+        if (misplaced.length > 0) {
+            throw new Error(
+                `KVManager does not take ${misplaced.map((k) => `"${k}"`).join(', ')}: choose the store in the App config, ` +
+                    "e.g. new App({ name, kv: { driver: 'redis', connection: process.env.REDIS_URL } })",
+            );
+        }
         // Default to memory until configured
         this.adapter = new MemoryAdapter();
         this.prefix = options.namespace ? `${options.namespace}:` : '';
+        this.flushDb = options.flushDb ?? false;
     }
 
     init(app: App) {
         this.app = app;
+        // Like db-kit's 'db': services look the store up as app.context.get('kv').
+        app.context.set('kv', this);
         const config = app.config.kv;
 
         if (config?.driver === 'redis') {
             app.logger.info('Initializing KV with Redis');
-            this.adapter = new RedisAdapter(config.connection);
-        } else {
+            this.adapter = new RedisAdapter(config.connection ?? {}, {
+                onError: (err) => app.logger.warn({ err }, 'KV Redis connection error'),
+                flushDb: this.flushDb,
+            });
+        } else if (!config?.driver || config.driver === 'memory') {
+            if (!config?.driver && isProductionEnv()) {
+                app.logger.warn(
+                    'KV has no driver configured: using the in-memory store, which each process keeps on its own ' +
+                        "and loses on restart. Set kv: { driver: 'redis', connection } in the App config, or " +
+                        "kv: { driver: 'memory' } to keep it.",
+                );
+            }
             app.logger.info('Initializing KV with Memory');
             this.adapter = new MemoryAdapter();
+        } else {
+            // Unknown drivers (e.g. 'libsql') used to fall back to memory
+            // silently, losing every value on restart.
+            throw new Error(`Unsupported KV driver "${config.driver}" (supported: "memory", "redis")`);
         }
     }
 
@@ -55,6 +89,16 @@ export class KVManager implements Driver, KVAdapter {
         await this.disconnect();
     }
 
+    /**
+     * The underlying ioredis client with the "redis" driver, once started: for
+     * commands the KV API does not cover (sets, sorted sets, pipelines). It
+     * bypasses `namespace` and the JSON codec. `undefined` with the memory
+     * driver or before start().
+     */
+    get client(): Redis | undefined {
+        return this.adapter instanceof RedisAdapter ? (this.adapter.nativeClient ?? undefined) : undefined;
+    }
+
     private prefixed(key: string): string {
         return `${this.prefix}${key}`;
     }
@@ -83,26 +127,21 @@ export class KVManager implements Driver, KVAdapter {
     // 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));
+        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)));
+        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> {
+    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]
-        );
+        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);
@@ -113,13 +152,46 @@ export class KVManager implements Driver, KVAdapter {
     }
 
     async mdel(keys: string[]): Promise<void> {
-        const prefixed = keys.map(k => this.prefixed(k));
+        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)));
+        await Promise.all(prefixed.map((k) => this.adapter.del(k)));
+    }
+
+    /**
+     * Deletes every key under `prefix` in this manager's namespace (the whole
+     * namespace without one). With the redis driver and no namespace, only
+     * `flushDb: true` lets it empty the database.
+     */
+    async clear(prefix = ''): Promise<void> {
+        if (!this.adapter.clear) throw unsupported(this.adapter, 'clear');
+        await this.adapter.clear(this.prefixed(prefix));
+    }
+
+    /** See {@link KVAdapter.sadd}: the member is kept as is, only `key` is namespaced. */
+    async sadd(key: string, member: string, ttl?: number): Promise<void> {
+        if (!this.adapter.sadd) throw unsupported(this.adapter, 'sadd');
+        await this.adapter.sadd(this.prefixed(key), member, ttl);
+    }
+
+    async sdrain(key: string): Promise<string[]> {
+        if (!this.adapter.sdrain) throw unsupported(this.adapter, 'sdrain');
+        return this.adapter.sdrain(this.prefixed(key));
+    }
+}
+
+/** Both built-in adapters have the optional methods; an injected one may not. */
+function unsupported(adapter: KVAdapter, method: string): Error {
+    return new Error(`The "${adapter.id}" KV adapter does not support ${method}()`);
+}
+
+// `app.context.get('kv')` is the KVManager registered on the app.
+declare module '@iskra-bun/core' {
+    interface AppContextRegistry {
+        kv: KVManager;
     }
 }

package/src/ttl.ts

@@ -0,0 +1,12 @@
+/**
+ * A TTL in seconds: `undefined`, `null` or `0` mean "no expiry". Anything else
+ * must be a positive finite number: a negative TTL used to delete the key at
+ * once with the memory adapter and fail with Redis.
+ */
+export function checkTtl(ttl: number | null | undefined): number | undefined {
+    if (ttl === undefined || ttl === null || ttl === 0) return undefined;
+    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || ttl < 0) {
+        throw new RangeError(`Invalid TTL ${String(ttl)}: expected a positive number of seconds`);
+    }
+    return ttl;
+}

package/src/types.ts

@@ -19,4 +19,20 @@ export interface KVAdapter {
     mget?<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
     mset?<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void>;
     mdel?(keys: string[]): Promise<void>;
+
+    /**
+     * Deletes every key that starts with `prefix` (every key the adapter holds
+     * without one), without touching the connection. An adapter that cannot
+     * leaves it out, and callers such as cache-kit's `clear()` then fail.
+     */
+    clear?(prefix?: string): Promise<void>;
+
+    /**
+     * Expiring sets, for cache-kit's tag index: `sadd` adds `member` to the set
+     * at `key` for `ttl` seconds (for good without one), and the set lives as
+     * long as its longest-lived member. `sdrain` deletes the set and returns
+     * its unexpired members in one step, so a member added meanwhile is never lost.
+     */
+    sadd?(key: string, member: string, ttl?: number): Promise<void>;
+    sdrain?(key: string): Promise<string[]>;
 }