@beignet/provider-redis 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-redis
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,186 @@
+# @beignet/provider-redis
+
+Redis-backed `CachePort` provider for Beignet applications.
+
+The provider installs `ctx.ports.cache` using
+[ioredis](https://github.com/redis/ioredis) and exposes the Redis client only
+as an escape hatch for Redis-specific features.
+
+## Install
+
+```bash
+bun add @beignet/provider-redis ioredis
+```
+
+## Setup
+
+```typescript
+import { createNextServer } from "@beignet/next";
+import { definePorts } from "@beignet/core/ports";
+import { redisProvider } from "@beignet/provider-redis";
+import { routes } from "@/server/routes";
+
+// Set environment variables:
+// REDIS_URL=redis://localhost:6379
+// REDIS_DB=0 (optional)
+
+const appPorts = definePorts({});
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [redisProvider],
+  createContext: ({ ports }) => ({
+    ports,
+  }),
+  routes,
+});
+```
+
+## Usage
+
+Once the provider is registered, your ports will include a `cache` property:
+
+```typescript
+// In your use case
+async function getUserProfile(ctx: AppCtx) {
+  const userId = ctx.actor.type === "user" ? ctx.actor.id : undefined;
+  if (!userId) throw new Error("User actor required.");
+
+  const cacheKey = `user:${userId}:profile`;
+  
+  // Try to get from cache
+  const cached = await ctx.ports.cache.get(cacheKey);
+  if (cached) {
+    return JSON.parse(cached);
+  }
+  
+  // Fetch from database
+  const profile = await ctx.ports.db.users.findById(userId);
+  
+  // Store in cache for 1 hour
+  await ctx.ports.cache.set(
+    cacheKey,
+    JSON.stringify(profile),
+    { ttlSeconds: 3600 }
+  );
+  
+  return profile;
+}
+```
+
+## Configuration
+
+The Redis provider reads configuration from environment variables with the `REDIS_` prefix:
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `REDIS_URL` | Yes | Redis connection URL | `redis://localhost:6379` |
+| `REDIS_DB` | No | Redis database number (default: 0) | `0` |
+
+## Cache port API
+
+The provider extends your ports with the following cache interface:
+
+### `get(key: string): Promise<string | null>`
+
+Get a value from the cache.
+
+```typescript
+const value = await ctx.ports.cache.get("my-key");
+```
+
+### `set(key: string, value: string, options?: { ttlSeconds?: number }): Promise<void>`
+
+Set a value in the cache with optional TTL (time-to-live) in seconds.
+
+```typescript
+// Without TTL (persists forever)
+await ctx.ports.cache.set("key", "value");
+
+// With TTL (expires after 1 hour)
+await ctx.ports.cache.set("key", "value", { ttlSeconds: 3600 });
+```
+
+### `delete(key: string): Promise<boolean>`
+
+Delete a key from the cache. Returns `true` when a key was deleted.
+
+```typescript
+const deleted = await ctx.ports.cache.delete("my-key");
+```
+
+### `has(key: string): Promise<boolean>`
+
+Check if a key exists in the cache.
+
+```typescript
+const exists = await ctx.ports.cache.has("my-key");
+```
+
+### `remember(key: string, factory: () => Promise<string>, options?: { ttlSeconds?: number }): Promise<string>`
+
+Return the cached value when present. On a miss, compute, store, and return the
+factory value.
+
+```typescript
+const value = await ctx.ports.cache.remember(
+  "my-key",
+  async () => JSON.stringify(await loadExpensiveData()),
+  { ttlSeconds: 300 },
+);
+```
+
+### `client: Redis`
+
+Access the underlying ioredis client for advanced operations.
+
+```typescript
+// Use ioredis methods directly
+await ctx.ports.cache.client.expire("key", 300);
+await ctx.ports.cache.client.incr("counter");
+```
+
+## Devtools
+
+When `@beignet/devtools` is installed before this provider, Redis cache
+operations appear under the dashboard's Cache watcher.
+
+The provider records `cache.get`, `cache.set`, `cache.delete`, `cache.has`, and
+`cache.remember` events with the cache key, hit/miss or deleted status, TTL, and
+duration. Cached values are not recorded.
+
+## TypeScript support
+
+To get proper type inference for the cache port, extend your ports type:
+
+```typescript
+import type { RedisCachePort } from "@beignet/provider-redis";
+
+// Your base ports, if any
+const basePorts = definePorts({});
+
+// After using redisProvider, your ports will have this shape:
+type AppPorts = typeof basePorts & {
+  cache: RedisCachePort;
+};
+```
+
+## Lifecycle
+
+The Redis provider:
+
+1. **During `setup`**: Connects to Redis and returns the `cache` port
+2. **During `stop`**: Gracefully closes the Redis connection
+
+## Error handling
+
+The provider will throw errors in these cases:
+
+- Missing `REDIS_URL` environment variable
+- Failed connection to Redis server
+
+Make sure to handle these during application startup.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @beignet/provider-redis
+ *
+ * Redis provider that extends ports with cache capabilities using ioredis.
+ *
+ * Configuration:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional, default: 0)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { redisProvider } from "@beignet/provider-redis";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * async function myUseCase(ctx: AppCtx) {
+ *   const cached = await ctx.ports.cache.get("key");
+ *   if (!cached) {
+ *     const value = await fetchData();
+ *     await ctx.ports.cache.set("key", value, { ttlSeconds: 3600 });
+ *   }
+ * }
+ * ```
+ */
+import type { CachePort } from "@beignet/core/ports";
+import Redis from "ioredis";
+import { z } from "zod";
+/**
+ * Configuration schema for the Redis provider.
+ * Validates environment variables with REDIS_ prefix.
+ */
+declare const RedisConfigSchema: z.ZodObject<{
+    URL: z.ZodString;
+    DB: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * Inferred configuration type for Redis provider.
+ */
+export type RedisConfig = z.infer<typeof RedisConfigSchema>;
+/**
+ * Extended cache port interface that includes the Redis client.
+ * The Redis provider adds the underlying client for advanced operations.
+ */
+export interface RedisCachePort extends CachePort {
+    /**
+     * The underlying Redis client instance.
+     * Use this for advanced operations not covered by the cache interface.
+     */
+    client: Redis;
+}
+/**
+ * Redis provider that extends ports with cache capabilities.
+ *
+ * Configuration via environment variables:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export declare const redisProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    URL: z.ZodString;
+    DB: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>, {
+    cache: RedisCachePort;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,QAAA,MAAM,iBAAiB;;;iBAYrB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C;;;OAGG;IACH,MAAM,EAAE,KAAK,CAAC;CACf;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;;;;;EAmPxB,CAAC"}

package/dist/index.js

@@ -0,0 +1,295 @@
+/**
+ * @beignet/provider-redis
+ *
+ * Redis provider that extends ports with cache capabilities using ioredis.
+ *
+ * Configuration:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional, default: 0)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { redisProvider } from "@beignet/provider-redis";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * async function myUseCase(ctx: AppCtx) {
+ *   const cached = await ctx.ports.cache.get("key");
+ *   if (!cached) {
+ *     const value = await fetchData();
+ *     await ctx.ports.cache.set("key", value, { ttlSeconds: 3600 });
+ *   }
+ * }
+ * ```
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import Redis from "ioredis";
+import { z } from "zod";
+/**
+ * Configuration schema for the Redis provider.
+ * Validates environment variables with REDIS_ prefix.
+ */
+const RedisConfigSchema = z.object({
+    /**
+     * Redis connection URL.
+     * Example: "redis://localhost:6379"
+     */
+    URL: z.string().url(),
+    /**
+     * Redis database number (optional).
+     * Defaults to 0 if not specified.
+     */
+    DB: z.coerce.number().int().min(0).optional(),
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Redis provider that extends ports with cache capabilities.
+ *
+ * Configuration via environment variables:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const redisProvider = createProvider({
+    name: "redis",
+    config: {
+        schema: RedisConfigSchema,
+        envPrefix: "REDIS_",
+    },
+    async setup({ ports, config }) {
+        if (!config) {
+            throw new Error("[redisProvider] Missing Redis config. " +
+                "Please set REDIS_URL environment variable.");
+        }
+        // Create Redis client
+        const client = new Redis(config.URL, {
+            db: config.DB ?? 0,
+            // Prevent ioredis from logging connection errors to console
+            // (we'll handle errors in the application)
+            lazyConnect: true,
+        });
+        // Test connection
+        try {
+            await client.connect();
+        }
+        catch (error) {
+            throw new Error(`[redisProvider] Failed to connect to Redis at ${config.URL}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const instrumentation = createProviderInstrumentation(ports, {
+            providerName: "redis",
+            watcher: "cache",
+        });
+        const recordCacheEvent = (event) => {
+            instrumentation.custom({
+                name: `cache.${event.operation}`,
+                label: `Cache ${event.operation}`,
+                summary: event.summary,
+                details: {
+                    operation: event.operation,
+                    key: event.key,
+                    ...event.details,
+                },
+            });
+        };
+        // Extend ports with cache API
+        const cache = {
+            get: async (key) => {
+                const startedAt = Date.now();
+                try {
+                    const value = await client.get(key);
+                    recordCacheEvent({
+                        operation: "get",
+                        key,
+                        summary: value == null ? "Cache miss" : "Cache hit",
+                        details: {
+                            hit: value != null,
+                            durationMs: Date.now() - startedAt,
+                        },
+                    });
+                    return value;
+                }
+                catch (error) {
+                    recordCacheEvent({
+                        operation: "get.failed",
+                        key,
+                        summary: "Cache get failed",
+                        details: {
+                            durationMs: Date.now() - startedAt,
+                            error: errorMessage(error),
+                        },
+                    });
+                    throw error;
+                }
+            },
+            set: async (key, value, options) => {
+                const startedAt = Date.now();
+                try {
+                    if (options?.ttlSeconds != null && options.ttlSeconds > 0) {
+                        await client.set(key, value, "EX", options.ttlSeconds);
+                    }
+                    else {
+                        await client.set(key, value);
+                    }
+                    recordCacheEvent({
+                        operation: "set",
+                        key,
+                        summary: "Cache set",
+                        details: {
+                            ttlSeconds: options?.ttlSeconds ?? null,
+                            durationMs: Date.now() - startedAt,
+                        },
+                    });
+                }
+                catch (error) {
+                    recordCacheEvent({
+                        operation: "set.failed",
+                        key,
+                        summary: "Cache set failed",
+                        details: {
+                            ttlSeconds: options?.ttlSeconds ?? null,
+                            durationMs: Date.now() - startedAt,
+                            error: errorMessage(error),
+                        },
+                    });
+                    throw error;
+                }
+            },
+            delete: async (key) => {
+                const startedAt = Date.now();
+                try {
+                    const deleted = (await client.del(key)) > 0;
+                    recordCacheEvent({
+                        operation: "delete",
+                        key,
+                        summary: deleted ? "Cache key deleted" : "Cache key missing",
+                        details: {
+                            deleted,
+                            durationMs: Date.now() - startedAt,
+                        },
+                    });
+                    return deleted;
+                }
+                catch (error) {
+                    recordCacheEvent({
+                        operation: "delete.failed",
+                        key,
+                        summary: "Cache delete failed",
+                        details: {
+                            durationMs: Date.now() - startedAt,
+                            error: errorMessage(error),
+                        },
+                    });
+                    throw error;
+                }
+            },
+            has: async (key) => {
+                const startedAt = Date.now();
+                try {
+                    const result = await client.exists(key);
+                    const exists = result === 1;
+                    recordCacheEvent({
+                        operation: "has",
+                        key,
+                        summary: exists ? "Cache key exists" : "Cache key missing",
+                        details: {
+                            exists,
+                            durationMs: Date.now() - startedAt,
+                        },
+                    });
+                    return exists;
+                }
+                catch (error) {
+                    recordCacheEvent({
+                        operation: "has.failed",
+                        key,
+                        summary: "Cache has failed",
+                        details: {
+                            durationMs: Date.now() - startedAt,
+                            error: errorMessage(error),
+                        },
+                    });
+                    throw error;
+                }
+            },
+            remember: async (key, factory, options) => {
+                const startedAt = Date.now();
+                try {
+                    const cached = await client.get(key);
+                    if (cached != null) {
+                        recordCacheEvent({
+                            operation: "remember",
+                            key,
+                            summary: "Cache remember hit",
+                            details: {
+                                hit: true,
+                                ttlSeconds: options?.ttlSeconds ?? null,
+                                durationMs: Date.now() - startedAt,
+                            },
+                        });
+                        return cached;
+                    }
+                    const value = await factory();
+                    if (options?.ttlSeconds != null && options.ttlSeconds > 0) {
+                        await client.set(key, value, "EX", options.ttlSeconds);
+                    }
+                    else {
+                        await client.set(key, value);
+                    }
+                    recordCacheEvent({
+                        operation: "remember",
+                        key,
+                        summary: "Cache remember miss",
+                        details: {
+                            hit: false,
+                            ttlSeconds: options?.ttlSeconds ?? null,
+                            durationMs: Date.now() - startedAt,
+                        },
+                    });
+                    return value;
+                }
+                catch (error) {
+                    recordCacheEvent({
+                        operation: "remember.failed",
+                        key,
+                        summary: "Cache remember failed",
+                        details: {
+                            ttlSeconds: options?.ttlSeconds ?? null,
+                            durationMs: Date.now() - startedAt,
+                            error: errorMessage(error),
+                        },
+                    });
+                    throw error;
+                }
+            },
+            client,
+        };
+        return {
+            ports: { cache },
+            async stop() {
+                try {
+                    await client.quit();
+                }
+                catch {
+                    // Silently ignore errors during shutdown
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@beignet/provider-redis",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Redis provider for Beignet - adds cache port using ioredis",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "redis",
+    "provider",
+    "cache",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-redis"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "ioredis": "^5.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,338 @@
+/**
+ * @beignet/provider-redis
+ *
+ * Redis provider that extends ports with cache capabilities using ioredis.
+ *
+ * Configuration:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional, default: 0)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { redisProvider } from "@beignet/provider-redis";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * async function myUseCase(ctx: AppCtx) {
+ *   const cached = await ctx.ports.cache.get("key");
+ *   if (!cached) {
+ *     const value = await fetchData();
+ *     await ctx.ports.cache.set("key", value, { ttlSeconds: 3600 });
+ *   }
+ * }
+ * ```
+ */
+
+import type { CachePort } from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+} from "@beignet/core/providers";
+import Redis from "ioredis";
+import { z } from "zod";
+
+/**
+ * Configuration schema for the Redis provider.
+ * Validates environment variables with REDIS_ prefix.
+ */
+const RedisConfigSchema = z.object({
+  /**
+   * Redis connection URL.
+   * Example: "redis://localhost:6379"
+   */
+  URL: z.string().url(),
+
+  /**
+   * Redis database number (optional).
+   * Defaults to 0 if not specified.
+   */
+  DB: z.coerce.number().int().min(0).optional(),
+});
+
+/**
+ * Inferred configuration type for Redis provider.
+ */
+export type RedisConfig = z.infer<typeof RedisConfigSchema>;
+
+/**
+ * Extended cache port interface that includes the Redis client.
+ * The Redis provider adds the underlying client for advanced operations.
+ */
+export interface RedisCachePort extends CachePort {
+  /**
+   * The underlying Redis client instance.
+   * Use this for advanced operations not covered by the cache interface.
+   */
+  client: Redis;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Redis provider that extends ports with cache capabilities.
+ *
+ * Configuration via environment variables:
+ * - REDIS_URL: Redis connection URL (required)
+ * - REDIS_DB: Redis database number (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [redisProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const redisProvider = createProvider({
+  name: "redis",
+
+  config: {
+    schema: RedisConfigSchema,
+    envPrefix: "REDIS_",
+  },
+
+  async setup({ ports, config }) {
+    if (!config) {
+      throw new Error(
+        "[redisProvider] Missing Redis config. " +
+          "Please set REDIS_URL environment variable.",
+      );
+    }
+
+    // Create Redis client
+    const client = new Redis(config.URL, {
+      db: config.DB ?? 0,
+      // Prevent ioredis from logging connection errors to console
+      // (we'll handle errors in the application)
+      lazyConnect: true,
+    });
+
+    // Test connection
+    try {
+      await client.connect();
+    } catch (error) {
+      throw new Error(
+        `[redisProvider] Failed to connect to Redis at ${config.URL}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+
+    const instrumentation = createProviderInstrumentation(ports, {
+      providerName: "redis",
+      watcher: "cache",
+    });
+
+    const recordCacheEvent = (event: {
+      operation: string;
+      key: string;
+      summary: string;
+      details?: Record<string, unknown>;
+    }) => {
+      instrumentation.custom({
+        name: `cache.${event.operation}`,
+        label: `Cache ${event.operation}`,
+        summary: event.summary,
+        details: {
+          operation: event.operation,
+          key: event.key,
+          ...event.details,
+        },
+      });
+    };
+
+    // Extend ports with cache API
+    const cache: RedisCachePort = {
+      get: async (key: string) => {
+        const startedAt = Date.now();
+        try {
+          const value = await client.get(key);
+          recordCacheEvent({
+            operation: "get",
+            key,
+            summary: value == null ? "Cache miss" : "Cache hit",
+            details: {
+              hit: value != null,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+          return value;
+        } catch (error) {
+          recordCacheEvent({
+            operation: "get.failed",
+            key,
+            summary: "Cache get failed",
+            details: {
+              durationMs: Date.now() - startedAt,
+              error: errorMessage(error),
+            },
+          });
+          throw error;
+        }
+      },
+
+      set: async (key, value, options) => {
+        const startedAt = Date.now();
+        try {
+          if (options?.ttlSeconds != null && options.ttlSeconds > 0) {
+            await client.set(key, value, "EX", options.ttlSeconds);
+          } else {
+            await client.set(key, value);
+          }
+          recordCacheEvent({
+            operation: "set",
+            key,
+            summary: "Cache set",
+            details: {
+              ttlSeconds: options?.ttlSeconds ?? null,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+        } catch (error) {
+          recordCacheEvent({
+            operation: "set.failed",
+            key,
+            summary: "Cache set failed",
+            details: {
+              ttlSeconds: options?.ttlSeconds ?? null,
+              durationMs: Date.now() - startedAt,
+              error: errorMessage(error),
+            },
+          });
+          throw error;
+        }
+      },
+
+      delete: async (key) => {
+        const startedAt = Date.now();
+        try {
+          const deleted = (await client.del(key)) > 0;
+          recordCacheEvent({
+            operation: "delete",
+            key,
+            summary: deleted ? "Cache key deleted" : "Cache key missing",
+            details: {
+              deleted,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+          return deleted;
+        } catch (error) {
+          recordCacheEvent({
+            operation: "delete.failed",
+            key,
+            summary: "Cache delete failed",
+            details: {
+              durationMs: Date.now() - startedAt,
+              error: errorMessage(error),
+            },
+          });
+          throw error;
+        }
+      },
+
+      has: async (key) => {
+        const startedAt = Date.now();
+        try {
+          const result = await client.exists(key);
+          const exists = result === 1;
+          recordCacheEvent({
+            operation: "has",
+            key,
+            summary: exists ? "Cache key exists" : "Cache key missing",
+            details: {
+              exists,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+          return exists;
+        } catch (error) {
+          recordCacheEvent({
+            operation: "has.failed",
+            key,
+            summary: "Cache has failed",
+            details: {
+              durationMs: Date.now() - startedAt,
+              error: errorMessage(error),
+            },
+          });
+          throw error;
+        }
+      },
+
+      remember: async (key, factory, options) => {
+        const startedAt = Date.now();
+        try {
+          const cached = await client.get(key);
+          if (cached != null) {
+            recordCacheEvent({
+              operation: "remember",
+              key,
+              summary: "Cache remember hit",
+              details: {
+                hit: true,
+                ttlSeconds: options?.ttlSeconds ?? null,
+                durationMs: Date.now() - startedAt,
+              },
+            });
+            return cached;
+          }
+
+          const value = await factory();
+          if (options?.ttlSeconds != null && options.ttlSeconds > 0) {
+            await client.set(key, value, "EX", options.ttlSeconds);
+          } else {
+            await client.set(key, value);
+          }
+
+          recordCacheEvent({
+            operation: "remember",
+            key,
+            summary: "Cache remember miss",
+            details: {
+              hit: false,
+              ttlSeconds: options?.ttlSeconds ?? null,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+
+          return value;
+        } catch (error) {
+          recordCacheEvent({
+            operation: "remember.failed",
+            key,
+            summary: "Cache remember failed",
+            details: {
+              ttlSeconds: options?.ttlSeconds ?? null,
+              durationMs: Date.now() - startedAt,
+              error: errorMessage(error),
+            },
+          });
+          throw error;
+        }
+      },
+
+      client,
+    };
+
+    return {
+      ports: { cache },
+      async stop() {
+        try {
+          await client.quit();
+        } catch {
+          // Silently ignore errors during shutdown
+        }
+      },
+    };
+  },
+});