GitHub

@probitas/client-redis

v0.2.0 View on JSR

Redis client for Probitas scenario testing framework.

This package provides a Redis client designed for integration testing of applications using Redis.

Features

  • Data Structures: Strings, Hashes, Lists, Sets, Sorted Sets
  • Pub/Sub: Publish and subscribe to channels
  • Transactions: Atomic operations with MULTI/EXEC
  • Raw Commands: Execute any Redis command via command()
  • Resource Management: Implements AsyncDisposable for proper cleanup

Installation

deno add jsr:@probitas/client-redis

Quick Start

import { createRedisClient } from "@probitas/client-redis";

const client = await createRedisClient({
  url: "redis://localhost:6379/0",
});

// String operations
await client.set("user:1:name", "Alice", { ex: 3600 });
const result = await client.get("user:1:name");
console.log("Name:", result.value);

// Hash operations
await client.hset("user:1", "email", "alice@example.com");
const email = await client.hget("user:1", "email");
console.log("Email:", email.value);

// List operations
await client.rpush("queue", "job1", "job2", "job3");
const job = await client.lpop("queue");
console.log("Job:", job.value);

await client.close();

Transactions

// Atomic transaction
const tx = client.multi();
tx.incr("counter");
tx.get("counter");
await tx.exec();

Pub/Sub

// Subscribe to a channel
const subscription = client.subscribe("events");
for await (const message of subscription) {
  console.log("Received:", message.message);
  break;
}

// Publish to a channel
await client.publish("events", JSON.stringify({ type: "update" }));

Connection Configuration

// Using URL string
const client1 = await createRedisClient({ url: "redis://localhost:6379" });

// Using URL with password and database
const client2 = await createRedisClient({ url: "redis://:secret@localhost:6379/1" });

// Using config object
const client3 = await createRedisClient({
  url: { host: "localhost", port: 6379, password: "secret", db: 1 },
});

Using with using Statement

await using client = await createRedisClient({ url: "redis://localhost:6379" });

await client.set("test", "value");
const result = await client.get("test");
console.log(result.value);
// Client automatically closed when block exits
Package Description
@probitas/client Core utilities and types
@probitas/client-deno-kv Deno KV client

Installation

deno add jsr:@probitas/client-redis

Classes

class

#RedisCommandError

class RedisCommandError extends RedisError
ExtendsRedisError

Error thrown when a Redis command fails.

NameDescription
name—
kind—
command—
Constructor
new RedisCommandError(message: string, options: RedisCommandErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"command"
  • readonlycommandstring
Links
class

#RedisConnectionError

class RedisConnectionError extends RedisError
ExtendsRedisError

Error thrown when a Redis connection cannot be established.

NameDescription
name—
kind—
Constructor
new RedisConnectionError(message: string, options?: RedisErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"connection"
Links
class

#RedisError

class RedisError extends ClientError
ExtendsClientError

Base error class for Redis client errors.

NameDescription
name—
code—
Constructor
new RedisError(message: string, _: unknown, options?: RedisErrorOptions)
Properties
  • readonlynamestring
  • readonlycode?string
Links
class

#RedisScriptError

class RedisScriptError extends RedisError
ExtendsRedisError

Error thrown when a Redis Lua script fails.

NameDescription
name—
kind—
script—
Constructor
new RedisScriptError(message: string, options: RedisScriptErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"script"
  • readonlyscriptstring
Links

Interfaces

interface

#RedisArrayResult

interface RedisArrayResult<T = string> extends RedisResultBase<readonly T[]>

Redis array result (LRANGE, SMEMBERS, etc.)

NameDescription
type—
Properties
  • readonlytype"redis:array"
Links
interface

#RedisClient

interface RedisClient extends AsyncDisposable

Redis client interface

NameDescription
config—
get()—
set()—
del()—
incr()—
decr()—
hget()—
hset()—
hgetall()—
hdel()—
lpush()—
rpush()—
lpop()—
rpop()—
lrange()—
llen()—
sadd()—
srem()—
smembers()—
sismember()—
zadd()—
zrange()—
zscore()—
publish()—
subscribe()—
multi()—
command()—
close()—
Properties
Methods
get(key: string, options?: CommonOptions): Promise<RedisGetResult>
Parameters
set(key: string, value: string, options?: RedisSetOptions): Promise<RedisSetResult>
Parameters
del(_: string[]): Promise<RedisCountResult>
Parameters
  • _string[]
incr(key: string): Promise<RedisCountResult>
Parameters
  • keystring
decr(key: string): Promise<RedisCountResult>
Parameters
  • keystring
hget(key: string, field: string, options?: CommonOptions): Promise<RedisGetResult>
Parameters
hset(key: string, field: string, value: string, options?: CommonOptions): Promise<RedisCountResult>
Parameters
hgetall(key: string, options?: CommonOptions): Promise<RedisHashResult>
Parameters
hdel(key: string, _: string[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _string[]
lpush(key: string, _: string[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _string[]
rpush(key: string, _: string[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _string[]
lpop(key: string): Promise<RedisGetResult>
Parameters
  • keystring
rpop(key: string): Promise<RedisGetResult>
Parameters
  • keystring
lrange(key: string, start: number, stop: number, options?: CommonOptions): Promise<RedisArrayResult>
Parameters
llen(key: string): Promise<RedisCountResult>
Parameters
  • keystring
sadd(key: string, _: string[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _string[]
srem(key: string, _: string[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _string[]
smembers(key: string, options?: CommonOptions): Promise<RedisArrayResult>
Parameters
sismember(key: string, member: string): Promise<RedisCommonResult<boolean>>
Parameters
  • keystring
  • memberstring
zadd(key: string, _: { score: number; member: string }[]): Promise<RedisCountResult>
Parameters
  • keystring
  • _{ score: number; member: string }[]
zrange(key: string, start: number, stop: number, options?: CommonOptions): Promise<RedisArrayResult>
Parameters
zscore(key: string, member: string): Promise<RedisCommonResult<number | null>>
Parameters
  • keystring
  • memberstring
publish(channel: string, message: string): Promise<RedisCountResult>
Parameters
  • channelstring
  • messagestring
subscribe(channel: string): AsyncIterable<RedisMessage>
Parameters
  • channelstring
multi(): RedisTransaction
command<T = unknown>(cmd: string, _: unknown[]): Promise<RedisCommonResult<T>>
Parameters
  • cmdstring
  • _unknown[]
close(): Promise<void>
Links
interface

#RedisClientConfig

interface RedisClientConfig extends CommonOptions

Redis client configuration.

NameDescription
urlRedis connection URL or configuration object.
Properties
Links
interface

#RedisCommandErrorOptions

interface RedisCommandErrorOptions extends RedisErrorOptions

Options for Redis command errors.

NameDescription
command—
Properties
  • readonlycommandstring
Links
interface

#RedisCommonResult

interface RedisCommonResult<T = unknown> extends RedisResultBase<T>

Redis operation result (common/generic)

NameDescription
type—
Properties
  • readonlytype"redis:common"
Links
interface

#RedisConnectionConfig

interface RedisConnectionConfig extends CommonConnectionConfig

Redis connection configuration.

Extends CommonConnectionConfig with Redis-specific options.

NameDescription
dbDatabase index.
Properties
  • readonlydb?number

    Database index.

Links
interface

#RedisCountResult

interface RedisCountResult extends RedisResultBase<number>

Redis numeric result (DEL, LPUSH, SADD, etc.)

NameDescription
type—
Properties
  • readonlytype"redis:count"
Links
interface

#RedisErrorOptions

interface RedisErrorOptions extends ErrorOptions

Options for Redis errors.

NameDescription
code—
Properties
  • readonlycode?string
interface

#RedisGetResult

interface RedisGetResult extends RedisResultBase<string | null>

Redis GET result

NameDescription
type—
Properties
  • readonlytype"redis:get"
Links
interface

#RedisHashResult

interface RedisHashResult extends RedisResultBase<Record<string, string>>

Redis hash result (HGETALL)

NameDescription
type—
Properties
  • readonlytype"redis:hash"
Links
interface

#RedisMessage

interface RedisMessage

Redis Pub/Sub message

NameDescription
channel—
message—
Properties
  • readonlychannelstring
  • readonlymessagestring
interface

#RedisResultBase

interface RedisResultBase<T = unknown>

Base interface for Redis operation results. All Redis result types extend this interface.

NameDescription
type—
ok—
value—
duration—
Properties
  • readonlytypestring
  • readonlyokboolean
  • readonlyvalueT
  • readonlydurationnumber
interface

#RedisScriptErrorOptions

interface RedisScriptErrorOptions extends RedisErrorOptions

Options for Redis script errors.

NameDescription
script—
Properties
  • readonlyscriptstring
Links
interface

#RedisSetOptions

interface RedisSetOptions extends CommonOptions

Redis SET options

NameDescription
exExpiration in seconds
pxExpiration in milliseconds
nxOnly set if key does not exist
xxOnly set if key exists
Properties
  • readonlyex?number

    Expiration in seconds

  • readonlypx?number

    Expiration in milliseconds

  • readonlynx?boolean

    Only set if key does not exist

  • readonlyxx?boolean

    Only set if key exists

Links
interface

#RedisSetResult

interface RedisSetResult extends RedisResultBase<"OK">

Redis SET result

NameDescription
type—
Properties
  • readonlytype"redis:set"
Links
interface

#RedisTransaction

interface RedisTransaction

Redis transaction interface

NameDescription
get()—
set()—
del()—
incr()—
decr()—
hget()—
hset()—
hgetall()—
hdel()—
lpush()—
rpush()—
lpop()—
rpop()—
lrange()—
llen()—
sadd()—
srem()—
smembers()—
sismember()—
zadd()—
zrange()—
zscore()—
exec()—
discard()—
Methods
get(key: string): this
Parameters
  • keystring
set(key: string, value: string, options?: RedisSetOptions): this
Parameters
del(_: string[]): this
Parameters
  • _string[]
incr(key: string): this
Parameters
  • keystring
decr(key: string): this
Parameters
  • keystring
hget(key: string, field: string): this
Parameters
  • keystring
  • fieldstring
hset(key: string, field: string, value: string): this
Parameters
  • keystring
  • fieldstring
  • valuestring
hgetall(key: string): this
Parameters
  • keystring
hdel(key: string, _: string[]): this
Parameters
  • keystring
  • _string[]
lpush(key: string, _: string[]): this
Parameters
  • keystring
  • _string[]
rpush(key: string, _: string[]): this
Parameters
  • keystring
  • _string[]
lpop(key: string): this
Parameters
  • keystring
rpop(key: string): this
Parameters
  • keystring
lrange(key: string, start: number, stop: number): this
Parameters
  • keystring
  • startnumber
  • stopnumber
llen(key: string): this
Parameters
  • keystring
sadd(key: string, _: string[]): this
Parameters
  • keystring
  • _string[]
srem(key: string, _: string[]): this
Parameters
  • keystring
  • _string[]
smembers(key: string): this
Parameters
  • keystring
sismember(key: string, member: string): this
Parameters
  • keystring
  • memberstring
zadd(key: string, _: { score: number; member: string }[]): this
Parameters
  • keystring
  • _{ score: number; member: string }[]
zrange(key: string, start: number, stop: number): this
Parameters
  • keystring
  • startnumber
  • stopnumber
zscore(key: string, member: string): this
Parameters
  • keystring
  • memberstring
exec(): Promise<RedisArrayResult<unknown>>
discard(): void
Links

Functions

function

#createRedisClient

async function createRedisClient(config: RedisClientConfig): Promise<RedisClient>

Create a new Redis client instance.

The client provides comprehensive Redis data structure support including strings, hashes, lists, sets, sorted sets, pub/sub, and transactions.

Parameters
Returns

Promise<RedisClient> — A promise resolving to a new Redis client instance

Examples

Using URL string

const client = await createRedisClient({
  url: "redis://localhost:6379/0",
});

await client.set("key", "value");
const result = await client.get("key");
console.log(result.value);  // "value"

await client.close();

Using connection config object

const client = await createRedisClient({
  url: {
    host: "localhost",
    port: 6379,
    password: "secret",
    db: 0,
  },
});

Set with expiration

// Set key with 1 hour TTL
await client.set("session", sessionData, { ex: 3600 });

// Set key with 5 second TTL in milliseconds
await client.set("temp", data, { px: 5000 });

Hash operations

await client.hset("user:123", "name", "Alice");
await client.hset("user:123", "email", "alice@example.com");

const user = await client.hgetall("user:123");
console.log(user.value);  // { name: "Alice", email: "alice@example.com" }

Pub/Sub

// Subscribe to channel
for await (const message of client.subscribe("events")) {
  console.log("Received:", message.message);
}

// In another session
await client.publish("events", JSON.stringify({ type: "user.created" }));

Using await using for automatic cleanup

await using client = await createRedisClient({
  url: "redis://localhost:6379",
});

await client.set("test", "value");
// Client automatically closed when scope exits
Links

Type Aliases

type

#RedisResult

type RedisResult<T = unknown> = RedisCommonResult<T> | RedisGetResult | RedisSetResult | RedisCountResult | RedisArrayResult<T> | RedisHashResult

Union of all Redis result types.

Links
Search Documentation