effect-redis 0.0.31 → 0.0.32

package/README.md

@@ -1,12 +1,33 @@
 # Effect-Redis
 
-A modern, type-safe [Effect](https://github.com/Effect-TS/effect) wrapper for the official `redis` client.
+A modern, type-safe [Effect-TS](https://github.com/Effect-TS/effect) wrapper for
+the official [`redis`](https://github.com/redis/node-redis) client.
 
-- **Resource-safe**: Automatic connection management via `Scope`.
-- **Modular Services**: Separate services for Core, Pub/Sub, and Streams.
-- **Shared Connection**: Share a single Redis connection across multiple services.
-- **Comprehensive API**: Pre-wrapped common commands with proper Effect error handling.
-- **Raw Access**: Escalate to the raw `node-redis` client when needed.
+| Feature | Description |
+| :--- | :--- |
+| **Resource-safe** | Automatic connection lifecycle via `Scope` and `Layer.scoped` |
+| **Modular services** | Independent services for Core, Pub/Sub, and Streams |
+| **Shared connection** | Multiple services reuse a single managed connection |
+| **Typed errors** | Tagged error union (`RedisConnectionError`, `RedisCommandError`, `RedisGeneralError`) |
+| **Raw escape hatch** | Direct access to the underlying `node-redis` client via `use()` |
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Services & Layers](#services--layers)
+- [Configuration](#configuration)
+- [Redis Service (Core)](#redis-service-core)
+- [RedisPubSub Service](#redispubsub-service)
+- [RedisStream Service](#redisstream-service)
+- [Error Model](#error-model)
+- [Types Reference](#types-reference)
+- [Configuration Utilities](#configuration-utilities)
+- [Usage Examples](#usage-examples)
+- [Peer Dependencies](#peer-dependencies)
 
 ---
 
@@ -21,41 +42,37 @@ pnpm add effect-redis
 ## Quick Start
 
 ```ts
-import { Effect, Layer, Stream } from "effect";
+import { Effect, Layer, Stream } from 'effect';
 import {
   RedisConnectionOptionsLive,
   RedisLive,
   RedisPubSubLive,
   Redis,
   RedisPubSub,
-} from "effect-redis";
+} from 'effect-redis';
 
 const program = Effect.gen(function* () {
   const redis = yield* Redis;
   const pubsub = yield* RedisPubSub;
 
-  // Key-Value operations
-  yield* redis.set("user:42", JSON.stringify({ name: "Ada" }));
-  const val = yield* redis.get("user:42");
+  yield* redis.set('user:42', JSON.stringify({ name: 'Ada' }));
+  const val = yield* redis.get('user:42');
 
-  // Core commands
-  yield* redis.set("counter", "1");
-  yield* redis.incr("counter");
+  yield* redis.set('counter', '1');
+  yield* redis.incr('counter');
 
-  // Pub/Sub
-  const subscription = yield* pubsub.subscribe("notifications");
+  const subscription = yield* pubsub.subscribe('notifications');
   yield* Effect.fork(
     Stream.runForEach(subscription, (msg) =>
-      Effect.log(`🔔 Received: ${msg}`)
+      Effect.log(`Received: ${msg}`)
     )
   );
 
-  yield* pubsub.publish("notifications", "Hello world!");
+  yield* pubsub.publish('notifications', 'Hello world!');
 });
 
-// Compose the layers
 const RedisLayer = RedisConnectionOptionsLive({
-  url: "redis://localhost:6379",
+  url: 'redis://localhost:6379',
 }).pipe(
   Layer.provideMerge(RedisLive),
   Layer.provideMerge(RedisPubSubLive)
@@ -66,92 +83,372 @@ Effect.runPromise(program.pipe(Effect.provide(RedisLayer)));
 
 ---
 
-## Provided Services & Layers
+## Architecture
+
+```
+RedisConnectionOptionsLive(options)
+        |
+        v
+  RedisConnectionLive          (Layer.scoped — manages connection lifecycle)
+   /       |        \
+  v        v         v
+RedisLive  RedisPubSubLive  RedisStreamLive
+(core)     (pub/sub)        (streams)
+```
 
-The library is organized into several services, all of which can share a single underlying connection.
+All service layers attempt to reuse a shared `RedisConnection` from context. If
+none is provided, each creates its own scoped connection. Services that require
+dedicated connections (Pub/Sub subscriber, Stream consumer) always create
+additional clients internally.
 
-| Service | Layer | Purpose |
-| :--- | :--- | :--- |
-| `Redis` | `RedisLive` | Comprehensive Redis commands (Get, Set, Hash, List, etc.) |
-| `RedisPubSub` | `RedisPubSubLive` | Specialized Pub/Sub operations |
-| `RedisStream` | `RedisStreamLive` | Redis Streams operations (XADD, XREAD, XRANGE, etc.) |
-| `RedisConnection` | `RedisConnectionLive` | The underlying shared connection manager |
+---
 
-### Connection Management
+## Services & Layers
 
-Use `RedisConnectionOptionsLive(options)` to provide connection settings. All service layers automatically use the shared `RedisConnection` if provided, otherwise they create their own managed connection.
+| Service | Layer | Tag | Purpose |
+| :--- | :--- | :--- | :--- |
+| `Redis` | `RedisLive` | `'Redis'` | Comprehensive key-value, hash, list, set, sorted set, and admin commands |
+| `RedisPubSub` | `RedisPubSubLive` | `'RedisPubSub'` | Publish/Subscribe messaging |
+| `RedisStream` | `RedisStreamLive` | `'RedisStream'` | Redis Streams (XADD, XREAD, XRANGE, continuous polling) |
+| `RedisConnection` | `RedisConnectionLive` | `'RedisConnection'` | Shared managed connection |
+| `RedisConnectionOptions` | `RedisConnectionOptionsLive(opts)` | `'RedisConnectionOptions'` | Connection configuration provider |
+
+### Layer Composition
 
 ```ts
-const layers = RedisConnectionOptionsLive({ url: "..." }).pipe(
+import { Layer } from 'effect';
+import {
+  RedisConnectionOptionsLive,
+  RedisLive,
+  RedisPubSubLive,
+  RedisStreamLive,
+} from 'effect-redis';
+
+const FullRedisLayer = RedisConnectionOptionsLive({
+  url: 'redis://localhost:6379',
+}).pipe(
   Layer.provideMerge(RedisLive),
-  Layer.provideMerge(RedisPubSubLive)
+  Layer.provideMerge(RedisPubSubLive),
+  Layer.provideMerge(RedisStreamLive)
 );
 ```
 
 ---
 
-## Reference
-
-### `Redis` Service
-The most comprehensive service, wrapping hundreds of Redis commands.
-- `get(key)` / `set(key, value, options?)`
-- `del(...keys)` / `exists(...keys)`
-- `expire(key, seconds)` / `ttl(key)`
-- **Hashes**: `hset`, `hget`, `hgetall`, `hdel`, `hexists`, `hkeys`, `hvals`, `hlen`
-- **Lists**: `lpush`, `rpush`, `lpop`, `rpop`, `lrange`, `llen`, `lrem`
-- **Sets**: `sadd`, `srem`, `sismember`, `smembers`, `scard`
-- **Sorted Sets**: `zadd`, `zrange`, `zrangebyscore`, `zscore`, `zrem`, `zcard`
-- **Transactions**: `multi(commands)`
-- **Raw Execution**: `execute(command, ...args)`
-- **Raw Client Access**: `use(client => ...)`
-
-### `RedisPubSub` Service
-- `publish(channel, message)`
-- `subscribe(channel)` -> Returns `Effect<Stream<string>>`
-
-### `RedisStream` Service
-- `xadd(key, id, message)`
-- `xread(key, id, options?)`
-- `xrange(key, start, end, options?)`
-- `subscribe(key, options?)` -> Returns `Stream<StreamEntry>` (continuous polling)
-- `xack(key, group, ...ids)`
+## Configuration
+
+`RedisConnectionOptionsLive` accepts the same options as `redis.createClient()`.
+An optional second argument overrides the client factory (useful for testing).
+
+```ts
+// URL-based
+RedisConnectionOptionsLive({ url: 'redis://localhost:6379' });
+
+// Host/port-based
+RedisConnectionOptionsLive({
+  socket: { host: '10.0.0.1', port: 6380 },
+  password: 'secret',
+  database: 2,
+});
+
+// Custom client factory (e.g. for mocking)
+RedisConnectionOptionsLive(
+  { url: 'redis://localhost:6379' },
+  (opts) => myMockClient(opts)
+);
+```
+
+### Configuration Utilities
+
+Helper functions for validating and working with `RedisConfig`:
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `validateRedisConfig` | `(config: RedisConfig) => Effect<RedisConfig, RedisConnectionError>` | Validates host/port ranges, URL format |
+| `mergeWithDefaults` | `(config?: Partial<RedisConfig>) => RedisConfig` | Fills missing fields with defaults |
+| `getConnectionInfo` | `(config: RedisConfig) => string` | Returns a safe-to-log connection string (no credentials) |
+| `DEFAULT_REDIS_CONFIG` | `{ host: 'localhost', port: 6379, connectTimeout: 10000, commandTimeout: 5000 }` | Default values |
+
+---
+
+## Redis Service (Core)
+
+The `Redis` service provides typed wrappers for common Redis commands. Every
+method returns `Effect<T, RedisError>`.
+
+### Key-Value
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `get` | `(key: string) => Effect<string \| null>` | Get the value of a key |
+| `set` | `(key: string, value: RedisValue, options?: KeyOptions) => Effect<'OK' \| string \| null>` | Set a key to a value with optional expiration, condition, and GET |
+| `del` | `(...keys: string[]) => Effect<number>` | Delete one or more keys; returns the number of keys removed |
+| `exists` | `(...keys: string[]) => Effect<number>` | Check how many of the given keys exist |
+| `expire` | `(key: string, seconds: number) => Effect<number>` | Set a timeout on a key in seconds |
+| `pexpire` | `(key: string, milliseconds: number) => Effect<number>` | Set a timeout on a key in milliseconds |
+| `ttl` | `(key: string) => Effect<number>` | Get remaining time-to-live in seconds (`-1` if no expiry, `-2` if missing) |
+| `pttl` | `(key: string) => Effect<number>` | Get remaining time-to-live in milliseconds |
+| `incr` | `(key: string) => Effect<number>` | Atomically increment the integer value of a key by 1 |
+| `decr` | `(key: string) => Effect<number>` | Atomically decrement the integer value of a key by 1 |
+| `incrby` | `(key: string, increment: number) => Effect<number>` | Increment the integer value of a key by a given amount |
+| `decrby` | `(key: string, decrement: number) => Effect<number>` | Decrement the integer value of a key by a given amount |
+
+### Hash
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `hset` | `(key: string, field: string, value: RedisHashValue) => Effect<number>` | Set a field in a hash |
+| `hget` | `(key: string, field: string) => Effect<string \| null>` | Get the value of a hash field |
+| `hgetall` | `(key: string) => Effect<Record<string, string>>` | Get all fields and values of a hash |
+| `hdel` | `(key: string, ...fields: string[]) => Effect<number>` | Delete one or more hash fields |
+| `hexists` | `(key: string, field: string) => Effect<boolean>` | Check if a hash field exists |
+| `hkeys` | `(key: string) => Effect<string[]>` | Get all field names in a hash |
+| `hvals` | `(key: string) => Effect<string[]>` | Get all values in a hash |
+| `hlen` | `(key: string) => Effect<number>` | Get the number of fields in a hash |
+
+### List
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `lpush` | `(key: string, ...values: RedisListValue[]) => Effect<number>` | Prepend one or more values to a list |
+| `rpush` | `(key: string, ...values: RedisListValue[]) => Effect<number>` | Append one or more values to a list |
+| `lpop` | `(key: string, count?: number) => Effect<string \| string[] \| null>` | Remove and return element(s) from the head of a list |
+| `rpop` | `(key: string, count?: number) => Effect<string \| string[] \| null>` | Remove and return element(s) from the tail of a list |
+| `lrange` | `(key: string, start: number, stop: number) => Effect<string[]>` | Get a range of elements from a list |
+| `llen` | `(key: string) => Effect<number>` | Get the length of a list |
+| `lrem` | `(key: string, count: number, element: RedisListValue) => Effect<number>` | Remove elements matching a value from a list |
+
+### Set
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `sadd` | `(key: string, ...members: RedisSetMember[]) => Effect<number>` | Add one or more members to a set |
+| `srem` | `(key: string, ...members: RedisSetMember[]) => Effect<number>` | Remove one or more members from a set |
+| `sismember` | `(key: string, member: RedisSetMember) => Effect<boolean>` | Check if a value is a member of a set |
+| `smembers` | `(key: string) => Effect<string[]>` | Get all members of a set |
+| `scard` | `(key: string) => Effect<number>` | Get the number of members in a set |
+
+### Sorted Set
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `zadd` | `(key: string, score: number, member: string, ...rest: (number \| string)[]) => Effect<number>` | Add one or more members with scores to a sorted set |
+| `zrange` | `(key: string, start: number, stop: number, withScores?: boolean) => Effect<string[] \| { value: string; score: number }[]>` | Get a range of members by index; optionally include scores |
+| `zrangebyscore` | `(key: string, min: number \| string, max: number \| string, withScores?: boolean) => Effect<string[] \| { value: string; score: number }[]>` | Get members with scores within a given range |
+| `zscore` | `(key: string, member: string) => Effect<number \| null>` | Get the score of a member in a sorted set |
+| `zrem` | `(key: string, ...members: string[]) => Effect<number>` | Remove one or more members from a sorted set |
+| `zcard` | `(key: string) => Effect<number>` | Get the number of members in a sorted set |
+
+### Admin & Utilities
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `scan` | `(options?: ScanOptions) => Effect<ScanResult>` | Incrementally iterate over keys with optional pattern and type filtering |
+| `ping` | `(message?: string) => Effect<string>` | Test connection liveness; returns `PONG` or the provided message |
+| `dbsize` | `() => Effect<number>` | Get the number of keys in the current database |
+| `flushdb` | `() => Effect<'OK'>` | Remove all keys from the current database |
+| `flushall` | `() => Effect<'OK'>` | Remove all keys from all databases |
+| `quit` | `() => Effect<'OK'>` | Gracefully close the connection |
+| `disconnect` | `() => Effect<void>` | Force-close the connection immediately |
+
+### Raw Access
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `use` | `<T>(fn: (client: RedisClient) => T) => Effect<Awaited<T>>` | Execute any operation on the raw `node-redis` client |
+| `execute` | `<A>(command: string, ...args: (string \| number \| Buffer)[]) => Effect<A>` | Send a raw Redis command |
+| `multi` | `(commands: [string, ...(string \| number \| Buffer)[]][]) => Effect<unknown[]>` | Execute a MULTI/EXEC transaction |
+
+---
+
+## RedisPubSub Service
+
+Provides publish/subscribe messaging with **separate connections** for publish
+(shared) and subscribe (dedicated) to avoid blocking.
 
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `publish` | `(channel: string, message: string) => Effect<void>` | Publish a message to a channel |
+| `subscribe` | `(channel: string) => Effect<Stream<string>>` | Subscribe to a channel; returns a continuous `Stream` of messages |
+
+### Connection Model
+
+- **Publish**: reuses the shared `RedisConnection` if available
+- **Subscribe**: always creates a dedicated connection (Redis requires a
+  separate client for blocking subscribe operations)
+
+---
+
+## RedisStream Service
+
+Provides Redis Streams operations with **separate producer/consumer
+connections**. The producer reuses the shared connection; the consumer always
+gets a dedicated client for blocking reads.
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `xadd` | `(key, id, message) => Effect<string>` | Append an entry to a stream; use `'*'` for auto-generated IDs |
+| `xread` | `(key, id, options?) => Effect<StreamEntry[]>` | Read entries from a stream (supports blocking) |
+| `xrange` | `(key, start, end, options?) => Effect<StreamEntry[]>` | Read a range of entries (`'-'` to `'+'` for all) |
+| `subscribe` | `(key, options?) => Stream<StreamEntry>` | Continuous polling stream (blocks and yields new entries) |
+| `xack` | `(key, group, ...ids) => Effect<number>` | Acknowledge processed entries in a consumer group |
+
+### `StreamEntry`
+
+```ts
+interface StreamEntry {
+  id: RedisArgument;           // e.g. "1234567890-0"
+  data: Record<string, string>;
+}
+```
+
+### `StreamSubscribeOptions`
+
+```ts
+interface StreamSubscribeOptions {
+  readonly id?: string;    // Start ID (default: '$' — new entries only)
+  readonly block?: number; // Block time in ms (default: 5000)
+  readonly count?: number; // Max entries per read
+}
+```
+
+---
+
+## Error Model
+
+Every operation fails with `RedisError`, a discriminated union of three tagged
+error types. All extend `Data.TaggedError` for pattern matching with
+`Effect.catchTag`.
+
+```ts
+class RedisConnectionError extends Data.TaggedError('RedisConnectionError')<{
+  readonly cause: unknown;
+  readonly message: string;
+}> {}
+
+class RedisCommandError extends Data.TaggedError('RedisCommandError')<{
+  readonly cause: unknown;
+  readonly message: string;
+  readonly command: string;
+}> {}
+
+class RedisGeneralError extends Data.TaggedError('RedisGeneralError')<{
+  readonly cause: unknown;
+  readonly message: string;
+}> {}
+
+type RedisError = RedisConnectionError | RedisCommandError | RedisGeneralError;
+```
+
+| Error | Tag | Fields | When |
+| :--- | :--- | :--- | :--- |
+| `RedisConnectionError` | `'RedisConnectionError'` | `cause`, `message` | Connection failures (ECONNREFUSED, ETIMEDOUT, etc.) |
+| `RedisCommandError` | `'RedisCommandError'` | `cause`, `message`, `command` | Command execution failures (WRONGTYPE, NOAUTH, etc.) |
+| `RedisGeneralError` | `'RedisGeneralError'` | `cause`, `message` | All other Redis-related failures |
+
+The `toRedisError` utility automatically classifies raw errors into the correct
+type using error codes and message pattern matching.
+
+```ts
+import { Effect } from 'effect';
+import { Redis } from 'effect-redis';
+
+const program = Effect.gen(function* () {
+  const redis = yield* Redis;
+  yield* redis.get('my-key').pipe(
+    Effect.catchTag('RedisConnectionError', (e) =>
+      Effect.logError(`Connection lost: ${e.message}`)
+    ),
+    Effect.catchTag('RedisCommandError', (e) =>
+      Effect.logError(`Command ${e.command} failed: ${e.message}`)
+    )
+  );
+});
+```
+
+---
+
+## Types Reference
+
+### Value Types
+
+| Type | Definition |
+| :--- | :--- |
+| `RedisValue` | `string \| number \| Buffer` |
+| `RedisHashValue` | `string \| number \| Buffer \| Record<string, string \| number \| Buffer>` |
+| `RedisSetMember` | `string \| Buffer` |
+| `RedisListValue` | `string \| number \| Buffer` |
+
+### `KeyOptions` (for `set`)
+
+```ts
+interface KeyOptions {
+  readonly expiration?: {
+    readonly mode: 'EX' | 'PX' | 'EXAT' | 'PXAT';
+    readonly time: number;
+  };
+  readonly condition?: 'NX' | 'XX';
+  readonly get?: boolean; // When true, SET returns the old value
+}
+```
+
+### `ScanOptions` / `ScanResult`
+
+```ts
+interface ScanOptions {
+  readonly cursor?: string;
+  readonly match?: string;   // Glob pattern (e.g. 'user:*')
+  readonly count?: number;
+  readonly type?: 'string' | 'list' | 'set' | 'zset' | 'hash' | 'stream';
+}
+
+interface ScanResult {
+  readonly cursor: string;
+  readonly keys: readonly string[];
+}
+```
+
+### `RedisConfig`
+
+```ts
+type RedisConfig =
+  | { host: string; port: number; username?: string; password?: string;
+      database?: number; ssl?: boolean; connectTimeout?: number;
+      commandTimeout?: number; }
+  | { url: string; connectTimeout?: number; commandTimeout?: number; };
+```
 
 ---
 
 ## Usage Examples
 
-### 1. Automatic Reconnection & Retries
-In production, connections can drop. Use `Stream.retry` with a `Schedule` to handle this gracefully:
+### 1. Retry with Exponential Backoff
 
 ```ts
-import { Effect, Stream, Schedule, Duration } from "effect";
-import { RedisPubSub } from "effect-redis";
+import { Effect, Stream, Schedule, Duration } from 'effect';
+import { RedisPubSub } from 'effect-redis';
 
 const program = Effect.gen(function* () {
   const pubsub = yield* RedisPubSub;
-  const subscription = yield* pubsub.subscribe("raw-data");
+  const subscription = yield* pubsub.subscribe('raw-data');
 
-  const monitoringStream = subscription.pipe(
-    Stream.tap(msg => Effect.log(`Received: ${msg}`)),
-    // Retry with exponential backoff if the connection fails
+  yield* subscription.pipe(
+    Stream.tap((msg) => Effect.log(`Received: ${msg}`)),
     Stream.retry(
       Schedule.exponential(Duration.seconds(1)).pipe(
         Schedule.intersect(Schedule.recurs(5))
       )
-    )
+    ),
+    Stream.runDrain
   );
-
-  yield* Stream.runDrain(monitoringStream);
 });
 ```
 
-### 2. Stream Processing with Schema Validation
-Integrate with `@effect/schema` to build type-safe data pipelines:
+### 2. Schema-Validated Stream Processing
 
 ```ts
-import { Effect, Stream, Schema, pipe } from "effect";
-import { RedisPubSub } from "effect-redis";
+import { Effect, Stream, Schema, pipe } from 'effect';
+import { RedisPubSub } from 'effect-redis';
 
 const TradeSchema = Schema.Struct({
   symbol: Schema.String,
@@ -160,89 +457,92 @@ const TradeSchema = Schema.Struct({
 
 const program = Effect.gen(function* () {
   const pubsub = yield* RedisPubSub;
-  const trades = yield* pubsub.subscribe("trades");
+  const trades = yield* pubsub.subscribe('trades');
 
   yield* pipe(
     trades,
     Stream.map(JSON.parse),
-    Stream.mapEffect(data => 
+    Stream.mapEffect((data) =>
       Schema.decodeUnknown(TradeSchema)(data).pipe(
-        Effect.tapError(err => Effect.logWarning(`Invalid trade: ${err}`)),
-        Effect.option // Filter out invalid entries
+        Effect.tapError((err) => Effect.logWarning(`Invalid trade: ${err}`)),
+        Effect.option
       )
     ),
-    Stream.filterMap(opt => opt),
-    Stream.tap(trade => Effect.log(`Valid trade: ${trade.symbol} @ ${trade.price}`)),
+    Stream.filterMap((opt) => opt),
+    Stream.tap((trade) =>
+      Effect.log(`Valid trade: ${trade.symbol} @ ${trade.price}`)
+    ),
     Stream.runDrain
   );
 });
 ```
 
-### 3. Custom Commands & Transactions
-Escalate to the raw `node-redis` client for features not natively wrapped:
+### 3. Raw Client & Transactions
 
 ```ts
-import { Effect } from "effect";
-import { Redis } from "effect-redis";
+import { Effect } from 'effect';
+import { Redis } from 'effect-redis';
 
 const program = Effect.gen(function* () {
   const redis = yield* Redis;
 
-  // Execute a transaction using the raw client
   const results = yield* redis.use((client) =>
-    client
-      .multi()
-      .set("key1", "val1")
-      .set("key2", "val2")
-      .exec()
+    client.multi().set('key1', 'val1').set('key2', 'val2').exec()
   );
 
   yield* Effect.log(`Transaction results: ${JSON.stringify(results)}`);
 });
 ```
 
-### 4. Continuous Redis Stream Polling
-Use `RedisStream.subscribe` for continuous polling. You can track the last seen ID to ensure continuity across restarts:
+### 4. Continuous Stream Polling
 
 ```ts
-import { Effect, Stream } from "effect";
-import { RedisStream } from "effect-redis";
+import { Effect, Stream, Ref } from 'effect';
+import { RedisStream } from 'effect-redis';
 
 const program = Effect.gen(function* () {
-  const redisStream = yield* RedisStream;
-
-  // Track the last seen ID in a Ref for continuity
-  const lastId = yield* Effect.makeRef("$"); 
-
-  const events = redisStream.subscribe("app-events", {
-    id: yield* lastId.get,
-    block: 5000 // Wait up to 5s if idle
-  }).pipe(
-    Stream.tap(entry => lastId.set(String(entry.id)))
-  );
-
-  yield* Stream.runForEach(events, entry => 
-    Effect.log(`Event ID: ${entry.id}, Data: ${JSON.stringify(entry.message)}`)
+  const stream = yield* RedisStream;
+  const lastId = yield* Ref.make('$');
+
+  const events = stream
+    .subscribe('app-events', {
+      id: yield* Ref.get(lastId),
+      block: 5000,
+    })
+    .pipe(Stream.tap((entry) => Ref.set(lastId, String(entry.id))));
+
+  yield* Stream.runForEach(events, (entry) =>
+    Effect.log(`Event ${entry.id}: ${JSON.stringify(entry.data)}`)
   );
 });
 ```
 
----
+### 5. SET with Expiration and Conditions
 
-## Error Model
+```ts
+import { Effect } from 'effect';
+import { Redis } from 'effect-redis';
 
-Every operation can fail with a `RedisError`, which is a union of specific error types:
-- `RedisConnectionError`: Failures during connection.
-- `RedisCommandError`: Failures during command execution.
-- `RedisGeneralError`: Other Redis-related failures.
+const program = Effect.gen(function* () {
+  const redis = yield* Redis;
 
-All errors are tagged and include the original `cause`.
+  // Set only if key does not exist, expire in 60 seconds
+  yield* redis.set('lock:resource', 'owner-1', {
+    condition: 'NX',
+    expiration: { mode: 'EX', time: 60 },
+  });
 
-```ts
-const program = Redis.pipe(
-  Effect.flatMap(r => r.get("my-key")),
-  Effect.catchTag("RedisCommandError", (e) =>
-    Effect.logError(`Command failed: ${e.command}`, e.cause)
-  )
-);
+  // Set and return the previous value
+  const oldValue = yield* redis.set('config:version', '2', { get: true });
+});
 ```
+
+---
+
+## Peer Dependencies
+
+| Package | Version |
+| :--- | :--- |
+| `redis` | `^5.1.0` |
+| `typescript` | `^5` |
+| `effect` | (provided via workspace catalog) |