---
title: Redis API
description: Generated public TypeScript reference for @relkit/redis.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [integrations](/docs/modules/integrations), [local docker](/docs/modules/integrations/local-docker), [providers](/docs/modules/deployment/providers).

For a complete workflow, follow [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/redis` — 14 exports
- `@relkit/redis/runtime` — 11 exports
- `@relkit/redis/local-recipe` — 1 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                     | Kind  | Import from                  | Example                                                                                                                           |
| ------------------------------------------------------------------------------------------------------- | ----- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [assertRedisOptions](/docs/api/integrations/redis#assertredisoptions)                                   | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [createRedisAgentStateProvider](/docs/api/integrations/redis#createredisagentstateprovider)             | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/redis-state-acceptance.ts#L13)                     |
| [createRedisCacheProvider](/docs/api/integrations/redis#createrediscacheprovider)                       | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/redis.test.ts#L13)                                   |
| [createRedisClient](/docs/api/integrations/redis#createredisclient)                                     | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L63)                 |
| [createRedisRealtimeProvider](/docs/api/integrations/redis#createredisrealtimeprovider)                 | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/packed-consumer/packed-mixed-redis.fixture.ts#L78) |
| [localRecipe](/docs/api/integrations/redis#localrecipe)                                                 | Value | `@relkit/redis/local-recipe` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L145)                |
| [redis](/docs/api/integrations/redis#redis)                                                             | Value | `@relkit/redis`              | [API example](/docs/api/integrations/redis#redis)                                                                                 |
| [RedisAdapter](/docs/api/integrations/redis#redisadapter-type-alias)                                    | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisAgentState](/docs/api/integrations/redis#redisagentstate)                                         | Value | `@relkit/redis`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/agents.ts#L9)                               |
| [RedisAgentStateAdapter](/docs/api/integrations/redis#redisagentstateadapter-type-alias)                | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisAgentStateProviderOptions](/docs/api/integrations/redis#redisagentstateprovideroptions-interface) | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisBehavior](/docs/api/integrations/redis#redisbehavior-type-alias)                                  | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisCacheOptions](/docs/api/integrations/redis#rediscacheoptions-interface)                           | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisCacheProvider](/docs/api/integrations/redis#rediscacheprovider-interface)                         | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisClientOptions](/docs/api/integrations/redis#redisclientoptions-interface)                         | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisConnection](/docs/api/integrations/redis#redisconnection-type-alias)                              | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisConnectionContract](/docs/api/integrations/redis#redisconnectioncontract)                         | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisIntegration](/docs/api/integrations/redis#redisintegration)                                       | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisLocalRecipe](/docs/api/integrations/redis#redislocalrecipe)                                       | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisOptions](/docs/api/integrations/redis#redisoptions-interface)                                     | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisProtocolClient](/docs/api/integrations/redis#redisprotocolclient-interface)                       | Type  | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/redis.test.ts#L32)                                   |
| [redisRealtime](/docs/api/integrations/redis#redisrealtime)                                             | Value | `@relkit/redis`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/agents.ts#L8)                               |
| [RedisRealtimeAdapter](/docs/api/integrations/redis#redisrealtimeadapter-type-alias)                    | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisRealtimeProviderOptions](/docs/api/integrations/redis#redisrealtimeprovideroptions-interface)     | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisUrlReference](/docs/api/integrations/redis#redisurlreference-type-alias)                          | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [runtimeIntegration](/docs/api/integrations/redis#runtimeintegration)                                   | Value | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |

## `index.ts`

### "./realtime.js" (namespace export)

Re-exports all named exports from the "./realtime.js" module.

**Signature**

```ts
export * from "./realtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/index.ts#L2)

### "./redis.js" (namespace export)

Re-exports all named exports from the "./redis.js" module.

**Signature**

```ts
export * from "./redis.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/index.ts#L1)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 1;
  integrationId: "redis";
  recipeId: "redis-docker";
  recipeVersion: 1;
  materializerId: "docker";
  image: "redis:7.4.2-alpine@sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952";
  command: ReadonlyArray<string>;
  ports: Readonly<{ redis: 6379 }>;
  volume: Readonly<{ mountPath: "/data" }>;
  health: Readonly<{
    command: ReadonlyArray<string>;
    intervalMs: 250;
    timeoutMs: 2000;
    retries: 40;
  }>;
  outputs: ({
    ports,
  }: LocalServiceRecipeOutputContext) => Readonly<{ url: `redis://127.0.0.1:${number}` }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/local-recipe/index.ts#L10)

## `realtime.ts`

### RedisAgentStateAdapter (type alias)

**Signature**

```ts
type RedisAgentStateAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof agentState,
  "redis-agent-state",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L28)

### RedisRealtimeAdapter (type alias)

**Signature**

```ts
type RedisRealtimeAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof realtime,
  "redis-realtime",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L21)

### redisAgentState

**Signature**

```ts
declare const redisAgentState: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisAgentStateAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L41)

### redisRealtime

**Signature**

```ts
declare const redisRealtime: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisRealtimeAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L35)

## `redis.ts`

### redis

Defines a Redis-compatible cache adapter. Omit `url` for a deferred local or infrastructure source.

**Example**

```ts
import { env } from "@relkit/app/config";
import { redis } from "@relkit/redis";
const cache = redis({ url: env.secret("CACHE_URL") });
```

**Signature**

```ts
declare const redis: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L67)

Since v0.2.0

### RedisAdapter (type alias)

**Signature**

```ts
type RedisAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof cache,
  "redis",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L48)

### RedisBehavior (type alias)

**Signature**

```ts
type RedisBehavior<Options extends RedisOptions> = Options extends {
  readonly connectionTimeoutMs: infer Timeout extends number;
}
  ? Readonly<{ connectionTimeoutMs: Timeout }>
  : Readonly<Record<never, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L42)

### RedisConnection (type alias)

**Signature**

```ts
type RedisConnection<Options extends RedisOptions> = Options extends {
  readonly url: infer Url extends RedisUrlReference;
}
  ? Readonly<{ url: Url }>
  : Readonly<Record<never, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L36)

### RedisOptions (interface)

**Signature**

```ts
export interface RedisOptions<
  Url extends RedisUrlReference | undefined = RedisUrlReference | undefined,
> {
  readonly url?: Url;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L29)

### RedisUrlReference (type alias)

**Signature**

```ts
type RedisUrlReference<Name extends string = string> = BindingValueRef<
  Name,
  string,
  "secret-string"
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L23)

### assertRedisOptions

**Signature**

```ts
declare const assertRedisOptions: (options: RedisOptions) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L88)

### redisConnectionContract

**Signature**

```ts
declare const redisConnectionContract: ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L18)

### redisIntegration

**Signature**

```ts
declare const redisIntegration: IntegrationReference<"redis">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L16)

### redisLocalRecipe

**Signature**

```ts
declare const redisLocalRecipe: ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L21)

## `agent-state-provider.ts`

Binds the native Redis transaction adapter to the generic agent-state provider contract.

### RedisAgentStateProviderOptions (interface)

**Signature**

```ts
export interface RedisAgentStateProviderOptions {
  readonly url: string;
  readonly profile: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/agent-state-provider.ts#L14)

### createRedisAgentStateProvider

**Signature**

```ts
declare const createRedisAgentStateProvider: (
  options: RedisAgentStateProviderOptions,
) => AgentStateProvider & { ready(): Promise<void>; close(): Promise<void> };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/agent-state-provider.ts#L20)

## `client.ts`

Owns the native Redis connection; a later operation can reconnect without replaying failed commands.

### RedisClientOptions (interface)

Owns the native Redis connection; a later operation can reconnect without replaying failed commands.

**Signature**

```ts
export interface RedisClientOptions {
  readonly url: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L2)

### RedisProtocolClient (interface)

**Signature**

```ts
export interface RedisProtocolClient {
  readonly connected: boolean;
  connect(): Promise<void>;
  close(): void;
  ping(): Promise<boolean>;
  get(key: string): Promise<string | null>;
  set(key: string, value: string, ttlMs?: number): Promise<void>;
  delete(key: string): Promise<number>;
  has(key: string): Promise<boolean>;
  increment(key: string, amount?: number): Promise<number>;
  scan(
    cursor: string,
    pattern: string,
    count: number,
  ): Promise<readonly [string, readonly string[]]>;
  type(key: string): Promise<string>;
  ttl(key: string): Promise<number>;
  command(command: string, args: readonly string[]): Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L7)

### createRedisClient

Creates a protocol client whose next connection attempt replaces a failed native socket.

**Signature**

```ts
declare const createRedisClient: (options: RedisClientOptions) => RedisProtocolClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L30)

## `index.ts`

### "./agent-state-provider.js" (namespace export)

Re-exports all named exports from the "./agent-state-provider.js" module.

**Signature**

```ts
export * from "./agent-state-provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L9)

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L6)

### "./provider.js" (namespace export)

Re-exports all named exports from the "./provider.js" module.

**Signature**

```ts
export * from "./provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L7)

### "./realtime-provider.js" (namespace export)

Re-exports all named exports from the "./realtime-provider.js" module.

**Signature**

```ts
export * from "./realtime-provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L8)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "redis";
  registrations: ReadonlyArray<
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: RedisCacheProvider;
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: RealtimeProvider & { ready(): Promise<void>; close(): Promise<void> };
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: AgentStateProvider & { ready(): Promise<void>; close(): Promise<void> };
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L11)

## `provider.ts`

### RedisCacheOptions (interface)

**Signature**

```ts
export interface RedisCacheOptions {
  readonly url: string;
  readonly cacheId: string;
  readonly connectionTimeoutMs?: number;
  readonly client?: RedisProtocolClient;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L5)

### RedisCacheProvider (interface)

**Signature**

```ts
export interface RedisCacheProvider extends CacheProvider {
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
  readonly inspector: {
    readonly scan: (request: {
      readonly search?: string;
      readonly cursor?: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<{ readonly items: readonly unknown[]; readonly nextCursor?: string }>;
    readonly value: (request: {
      readonly key: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<unknown | undefined>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L12)

### createRedisCacheProvider

**Signature**

```ts
declare const createRedisCacheProvider: (options: RedisCacheOptions) => RedisCacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L30)

## `realtime-provider.ts`

### RedisRealtimeProviderOptions (interface)

**Signature**

```ts
export interface RedisRealtimeProviderOptions {
  readonly url: string;
  readonly profile: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/realtime-provider.ts#L9)

### createRedisRealtimeProvider

**Signature**

```ts
declare const createRedisRealtimeProvider: (
  options: RedisRealtimeProviderOptions,
) => RealtimeProvider & { ready(): Promise<void>; close(): Promise<void> };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/realtime-provider.ts#L15)

## `state-store.ts`

### RedisAgentStore (type alias)

**Signature**

```ts
type RedisAgentStore = AgentStateStore & RedisStateWaiter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L28)

### RedisRealtimeStore (type alias)

**Signature**

```ts
type RedisRealtimeStore = RealtimeStateStore & RedisStateWaiter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L27)

### RedisStateStoreOptions (interface)

**Signature**

```ts
export interface RedisStateStoreOptions<State> {
  readonly url: string;
  readonly key: string;
  readonly empty: () => State;
  readonly valid: (state: unknown) => state is State;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L9)

### RedisStateWaiter (interface)

**Signature**

```ts
export interface RedisStateWaiter {
  waitForChange(
    recheck: () => Promise<boolean>,
    deadlineMs: number,
    signal: AbortSignal,
  ): Promise<void>;
  ready(): Promise<void>;
  close(): Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L17)

### createRedisAgentStore

**Signature**

```ts
declare const createRedisAgentStore: (
  options: RedisStateStoreOptions<LocalAgentState>,
) => RedisAgentStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L45)

### createRedisRealtimeStore

**Signature**

```ts
declare const createRedisRealtimeStore: (
  options: RedisStateStoreOptions<LocalRealtimeState>,
) => RedisRealtimeStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L30)