@contract-kit/provider-redis

Redis provider for contract-kit that extends your application ports with cache capabilities using ioredis.

Installation

npm install @contract-kit/provider-redis ioredis
# or
bun add @contract-kit/provider-redis ioredis

TypeScript Requirements

This package requires TypeScript 5.0 or higher for proper type inference.

Usage

Basic Setup

import { createServer } from "@contract-kit/server";
import { redisProvider } from "@contract-kit/provider-redis";

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

const app = createServer({
  ports: basePorts,
  providers: [redisProvider],
  createContext: ({ ports }) => ({
    ports,
    // ... other context
  }),
  routes: [
    // ... your routes
  ],
});

Using the Cache in Use Cases

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

// In your use case
async function getUserProfile(ctx: AppCtx) {
  const cacheKey = `user:${ctx.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(ctx.userId);
  
  // Store in cache for 1 hour
  await ctx.ports.cache.set(
    cacheKey,
    JSON.stringify(profile),
    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.

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

set(key: string, value: string, 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", 3600);

del(key: string): Promise<number>

Delete a key from the cache. Returns the number of keys deleted (0 or 1).

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

exists(key: string): Promise<boolean>

Check if a key exists in the cache.

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

client: Redis

Access the underlying ioredis client for advanced operations.

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

TypeScript Support

To get proper type inference for the cache port, extend your ports type:

import type { CachePort } from "@contract-kit/provider-redis";

// Your base ports
const basePorts = definePorts({
  db: dbAdapter,
});

// After using redisProvider, your ports will have this shape:
type AppPorts = typeof basePorts & {
  cache: CachePort;
};

Lifecycle

The Redis provider:

1. During register: Connects to Redis and adds the cache port
2. During onAppStop: 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