Skip to main content

​
Overview

The Redis persistence adapter provides distributed locks, circuit breaker state management, caching, and checkpoint support using Redis as the backend. It leverages Redis’s native expiration features and atomic operations for high-performance distributed coordination.

​
Installation

npm install @go-go-scope/persistence-redis ioredis

​
Features

  • Distributed Locks: TTL-based locks with automatic expiration
  • Circuit Breaker State: Persistent failure tracking across instances
  • Caching: High-performance cache with TTL support
  • Checkpoints: Save and restore task state for fault tolerance
  • Idempotency: Prevent duplicate operations (via RedisIdempotencyAdapter)
  • Key Prefixing: Namespace isolation for multi-tenant applications

​
Basic Usage

import { Redis } from 'ioredis'
import { RedisAdapter } from '@go-go-scope/persistence-redis'
import { scope } from 'go-go-scope'

const redis = new Redis(process.env.REDIS_URL)
const persistence = new RedisAdapter(redis, { keyPrefix: 'myapp:' })

await using s = scope({ persistence })

​
Configuration

​
redis
Redis
required
ioredis Redis client instance
​
options
PersistenceAdapterOptions
Configuration options

​
Lock Provider Methods

​
acquire(key, ttl, owner?)

Acquires a distributed lock with automatic TTL-based expiration.
​
key
string
required
Lock identifier
​
ttl
number
required
Time-to-live in milliseconds
​
owner
string
Optional lock owner identifier (auto-generated if not provided)
Returns: Promise<LockHandle | null> - Lock handle or null if already locked

​
extend(key, ttl, owner)

Extends the TTL of an existing lock.
​
key
string
required
Lock identifier
​
ttl
number
required
New time-to-live in milliseconds
​
owner
string
required
Lock owner identifier
Returns: Promise<boolean> - True if extended successfully

​
forceRelease(key)

Forces release of a lock regardless of owner.
​
key
string
required
Lock identifier

​
Cache Provider Methods

​
get(key)

Retrieves a cached value.
​
key
string
required
Cache key
Returns: Promise<T | null> - Cached value or null if not found

​
set(key, value, ttl?)

Stores a value in the cache.
​
key
string
required
Cache key
​
value
T
required
Value to cache (must be JSON-serializable)
​
ttl
number
Time-to-live in milliseconds (optional, no expiration if omitted)

​
delete(key)

Removes a cached value.
​
key
string
required
Cache key

​
clear()

Clears all cached values (respects key prefix if set).

​
keys(pattern?)

Lists all cache keys matching an optional pattern.
​
pattern
string
Optional glob pattern (e.g., 'user:*')
Returns: Promise<string[]> - Array of matching keys

​
Checkpoint Provider Methods

​
saveCheckpoint(checkpoint)

Saves a checkpoint for task recovery.
​
checkpoint
Checkpoint<T>
required
Checkpoint data including taskId, sequence, progress, and data

​
loadLatestCheckpoint(taskId)

Loads the most recent checkpoint for a task.
​
taskId
string
required
Task identifier
Returns: Promise<Checkpoint<T> | undefined> - Latest checkpoint or undefined

​
Connection Example

import { Redis } from 'ioredis'
import { RedisAdapter } from '@go-go-scope/persistence-redis'

const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD,
  db: 0,
})

const persistence = new RedisAdapter(redis, {
  keyPrefix: 'myapp:',
})

// Connect if needed
await persistence.connect()

// Use with scope
await using s = scope({ persistence })

// Cleanup
await persistence.disconnect()

​
Key Storage Patterns

The adapter uses the following Redis key patterns:
  • Locks: {prefix}lock:{key}
  • Circuit Breaker: {prefix}circuit:{key}
  • Cache: {prefix}cache:{key}
  • Checkpoints: {prefix}checkpoint:{taskId}:{sequence}

​
Best Practices

Always use a keyPrefix in multi-tenant or shared Redis environments to prevent key collisions.
Redis TTL is eventually consistent. For critical locking scenarios, verify lock validity before performing operations.
The Redis adapter uses native Redis expiration (SETEX, PEXPIRE) for automatic cleanup. No manual cleanup required.

PostgreSQL Adapter

PostgreSQL-based persistence

MongoDB Adapter

MongoDB-based persistence

Build docs developers (and LLMs) love

Get started for freeTalk to us