@beignet/provider-cache-redis

Redis-backed CachePort provider for Beignet applications.

The provider installs ctx.ports.cache using ioredis and exposes the raw Redis client separately as ctx.ports.redis for Redis-specific features.

createRedisCacheProvider(...) returns the stable RedisCacheProvider type. RedisConfig describes its validated config; the Zod schema remains internal.

Install

bun add @beignet/provider-cache-redis @beignet/core ioredis
Copy

Setup

import { createNextServer, createNextServerLoader } from "@beignet/next";
import { definePorts } from "@beignet/core/ports";
import { createRedisCacheProvider } from "@beignet/provider-cache-redis";
import { routes } from "@/server/routes";

// Set environment variables:
// REDIS_URL=redis://localhost:6379
// REDIS_DB=0 (optional)

const initialPorts = definePorts({});

export const getServer = createNextServerLoader(() =>
  createNextServer({
    ports: initialPorts,
    providers: [createRedisCacheProvider()],
    context: ({ ports }) => ({
      ports,
    }),
    routes,
  }),
);
Copy

beignet doctor --strict checks that installed Redis cache providers are registered in server/providers.ts and that REDIS_URL is present in app env examples or config when the env-backed provider is used.

Usage

Once the provider is registered, your ports will include a cache property:

// In your use case
async function getUserProfile(ctx: AppContext) {
  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;
}
Copy

Configuration

The Redis provider reads configuration from environment variables with the REDIS_ prefix:

Factory options

Use createRedisCacheProvider(options) when the app should own connection defaults. Defined options override matching REDIS_* environment variables:

import { createRedisCacheProvider } from "@beignet/provider-cache-redis";

const provider = createRedisCacheProvider({
  connectTimeoutMs: 2000,
  maxRetriesPerRequest: 1,
  db: 1,
  // Optional: replace the default retry strategy entirely.
  retryStrategy: (times) => Math.min(times * 100, 1000),
});
Copy

Calling createRedisCacheProvider() with no options uses the env-backed defaults above.

Direct adapter

Use createRedisCache(...) when the app already owns an ioredis client. The factory adapts the client to CachePort without connecting, disconnecting, or reading environment variables:

import { createRedisCache } from "@beignet/provider-cache-redis";
import { Redis } from "ioredis";

const client = new Redis(process.env.APP_REDIS_URL!);
const cache = createRedisCache({ client });
Copy

Pass instrumentation when direct cache operations should appear in Beignet provider instrumentation. The caller remains responsible for client startup, retry policy, health checks, and shutdown.

Connection behavior

During startup the provider connects eagerly and fails fast: the initial connect() stops retrying after REDIS_CONNECT_MAX_ATTEMPTS attempts (or after REDIS_CONNECT_TIMEOUT_MS per attempt) and throws a clear error instead of hanging against an unreachable host. After a successful connection, lost connections are retried forever with capped exponential backoff (maximum 2 seconds between attempts).

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.

const value = await ctx.ports.cache.get("my-key");
Copy

set(key: string, value: string, options?: { ttlSeconds?: number }): Promise<void>

Set a value in the cache with optional TTL (time-to-live) in seconds.

// 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 });
Copy

delete(key: string): Promise<boolean>

Delete a key from the cache. Returns true when a key was deleted.

const deleted = await ctx.ports.cache.delete("my-key");
Copy

has(key: string): Promise<boolean>

Check if a key exists in the cache.

const exists = await ctx.ports.cache.has("my-key");
Copy

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.

const value = await ctx.ports.cache.remember(
  "my-key",
  async () => JSON.stringify(await loadExpensiveData()),
  { ttlSeconds: 300 },
);
Copy

Escape hatch

The provider also contributes ctx.ports.redis with the raw ioredis client for operations the stable cache port does not model:

// Use ioredis methods directly
await ctx.ports.redis.client.expire("key", 300);
await ctx.ports.redis.client.incr("counter");

// Use from app-owned readiness endpoints
const health = await ctx.ports.redis.checkHealth();
Copy

Use the stable CachePort for normal application behavior. Use the raw client only when the Redis-specific operation is intentional. checkHealth() sends a cheap Redis PING and returns a structured result instead of throwing.

Failure behavior

The env-backed provider throws during startup when REDIS_URL is missing or Redis cannot be reached within the configured connection attempts. Runtime cache operations throw Redis errors so callers can decide whether to fail, retry, or fall back to the source of truth.

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 contributed ports, extend your ports type with RedisCacheProviderPorts:

import type { RedisCacheProviderPorts } from "@beignet/provider-cache-redis";

// Your base ports, if any
const basePorts = definePorts({});

// After using createRedisCacheProvider(), your ports will have this shape:
type AppPorts = typeof basePorts & RedisCacheProviderPorts;
// { cache: CachePort; redis: { client: Redis } }
Copy

Direct wiring can use the exported RedisCacheClient and CreateRedisCacheOptions types without adopting the lifecycle provider ports.

Lifecycle

The Redis provider:

1. During setup: Connects to Redis and returns the cache and redis ports
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 after REDIS_CONNECT_MAX_ATTEMPTS attempts

Make sure to handle these during application startup.

Local and tests

Use an app-owned fake or memory CachePort in use-case tests. For local development, either run Redis locally or omit this provider until cache behavior is part of the workflow being tested.

Deployment notes

Set REDIS_DB or a key prefix strategy per app/environment if Redis is shared. Cache values are never the source of truth; design misses and Redis outages so the app can rebuild from durable state when appropriate.

License

MIT