@beignet/provider-redis

[!CAUTION] Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

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.

Install

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

Setup

import { createNextServer, createNextServerLoader } 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 getServer = createNextServerLoader(() =>
  createNextServer({
    ports: appPorts,
    providers: [redisProvider],
    context: ({ ports }) => ({
      ports,
    }),
    routes,
  }),
);

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;
}

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 | | REDIS_CONNECT_TIMEOUT_MS | No | Initial connection timeout in milliseconds (default: 5000) | 2000 | | REDIS_MAX_RETRIES_PER_REQUEST | No | Per-command retry limit before the command rejects (default: 2) | 1 | | REDIS_CONNECT_MAX_ATTEMPTS | No | Connection attempts before startup fails (default: 3) | 5 |

Factory options

Use createRedisProvider(options) when the app should own connection defaults. Matching REDIS_* environment variables still win when both are set:

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

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

The default redisProvider export is createRedisProvider() with no options.

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");

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

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");

has(key: string): Promise<boolean>

Check if a key exists in the cache.

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.

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

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();

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 RedisProviderPorts:

import type { RedisProviderPorts } 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 & RedisProviderPorts;
// { cache: CachePort; redis: { client: Redis } }

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