GitHub

@probitas/client-redis

v0.4.2 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

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

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

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

await client.close();

Pub/Sub

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

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

// 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" }));

await client.close();

Connection Configuration

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

// 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 },
});

await client1.close();
await client2.close();
await client3.close();

Using with using Statement

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

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
PackageDescription
`@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

#RedisArrayResultError

interface RedisArrayResultError<T = string> extends RedisArrayResultBase<T>

Array result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisArrayResultFailure

interface RedisArrayResultFailure<T = string> extends RedisArrayResultBase<T>

Array result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisArrayResultSuccess

interface RedisArrayResultSuccess<T = string> extends RedisArrayResultBase<T>

Successful array result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvaluereadonly T[]
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?: RedisCommandOptions): Promise<RedisGetResult>
Parameters
set(
  key: string,
  value: string,
  options?: RedisSetOptions,
): Promise<RedisSetResult>
Parameters
del(keys: string[], options?: RedisCommandOptions): Promise<RedisCountResult>
Parameters
incr(key: string, options?: RedisCommandOptions): Promise<RedisCountResult>
Parameters
decr(key: string, options?: RedisCommandOptions): Promise<RedisCountResult>
Parameters
hget(
  key: string,
  field: string,
  options?: RedisCommandOptions,
): Promise<RedisGetResult>
Parameters
hset(
  key: string,
  field: string,
  value: string,
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
hgetall(key: string, options?: RedisCommandOptions): Promise<RedisHashResult>
Parameters
hdel(
  key: string,
  fields: string[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
lpush(
  key: string,
  values: string[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
rpush(
  key: string,
  values: string[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
lpop(key: string, options?: RedisCommandOptions): Promise<RedisGetResult>
Parameters
rpop(key: string, options?: RedisCommandOptions): Promise<RedisGetResult>
Parameters
lrange(
  key: string,
  start: number,
  stop: number,
  options?: RedisCommandOptions,
): Promise<RedisArrayResult>
Parameters
llen(key: string, options?: RedisCommandOptions): Promise<RedisCountResult>
Parameters
sadd(
  key: string,
  members: string[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
srem(
  key: string,
  members: string[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
smembers(key: string, options?: RedisCommandOptions): Promise<RedisArrayResult>
Parameters
sismember(
  key: string,
  member: string,
  options?: RedisCommandOptions,
): Promise<RedisCommonResult<boolean>>
Parameters
zadd(
  key: string,
  entries: { score: number; member: string }[],
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
zrange(
  key: string,
  start: number,
  stop: number,
  options?: RedisCommandOptions,
): Promise<RedisArrayResult>
Parameters
zscore(
  key: string,
  member: string,
  options?: RedisCommandOptions,
): Promise<RedisCommonResult<number | null>>
Parameters
publish(
  channel: string,
  message: string,
  options?: RedisCommandOptions,
): Promise<RedisCountResult>
Parameters
subscribe(channel: string): AsyncIterable<RedisMessage>
Parameters
  • channelstring
multi(): RedisTransaction
command<T = any>(
  cmd: string,
  args: unknown[],
  options?: RedisCommandOptions,
): Promise<RedisCommonResult<T>>
Parameters
close(): Promise<void>
Links
interface

#RedisClientConfig

interface RedisClientConfig extends CommonOptions

Redis client configuration.

NameDescription
urlRedis connection URL or configuration object.
throwOnErrorWhether to throw an error when operations fail.
Properties
  • readonlyurlstring | RedisConnectionConfig

    Redis connection URL or configuration object.

  • readonlythrowOnError?boolean

    Whether to throw an error when operations fail.

    When true, failures will throw an error instead of returning a result with ok: false. This can be overridden per-command.

Links
interface

#RedisCommandErrorOptions

interface RedisCommandErrorOptions extends RedisErrorOptions

Options for Redis command errors.

NameDescription
command—
Properties
  • readonlycommandstring
Links
interface

#RedisCommandOptions

interface RedisCommandOptions extends CommonOptions

Redis command options.

Extends CommonOptions with Redis-specific behavior options.

NameDescription
throwOnErrorWhether to throw an error when the operation fails.
Properties
  • readonlythrowOnError?boolean

    Whether to throw an error when the operation fails.

    When true, failures will throw an error instead of returning a result with ok: false.

Links
interface

#RedisCommonResultError

interface RedisCommonResultError<T = any> extends RedisCommonResultBase<T>

Common result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisCommonResultFailure

interface RedisCommonResultFailure<T = any> extends RedisCommonResultBase<T>

Common result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisCommonResultSuccess

interface RedisCommonResultSuccess<T = any> extends RedisCommonResultBase<T>

Successful common result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvalueT
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

#RedisCountResultError

interface RedisCountResultError extends RedisCountResultBase

Count result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisCountResultFailure

interface RedisCountResultFailure extends RedisCountResultBase

Count result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisCountResultSuccess

interface RedisCountResultSuccess extends RedisCountResultBase

Successful count result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvaluenumber
interface

#RedisErrorOptions

interface RedisErrorOptions extends ErrorOptions

Options for Redis errors.

NameDescription
code—
Properties
  • readonlycode?string
interface

#RedisGetResultError

interface RedisGetResultError extends RedisGetResultBase

GET result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisGetResultFailure

interface RedisGetResultFailure extends RedisGetResultBase

GET result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisGetResultSuccess

interface RedisGetResultSuccess extends RedisGetResultBase

Successful GET result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvaluestring | null
interface

#RedisHashResultError

interface RedisHashResultError extends RedisHashResultBase

Hash result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisHashResultFailure

interface RedisHashResultFailure extends RedisHashResultBase

Hash result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisHashResultSuccess

interface RedisHashResultSuccess extends RedisHashResultBase

Successful hash result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvalueRecord<string, string>
interface

#RedisMessage

interface RedisMessage

Redis Pub/Sub message

NameDescription
channel—
message—
Properties
  • readonlychannelstring
  • readonlymessagestring
interface

#RedisScriptErrorOptions

interface RedisScriptErrorOptions extends RedisErrorOptions

Options for Redis script errors.

NameDescription
script—
Properties
  • readonlyscriptstring
Links
interface

#RedisSetOptions

interface RedisSetOptions extends RedisCommandOptions

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

#RedisSetResultError

interface RedisSetResultError extends RedisSetResultBase

SET result with Redis error.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisSetResultFailure

interface RedisSetResultFailure extends RedisSetResultBase

SET result with connection failure.

NameDescription
processed—
ok—
error—
value—
Properties
Links
interface

#RedisSetResultSuccess

interface RedisSetResultSuccess extends RedisSetResultBase

Successful SET result.

NameDescription
processed—
ok—
error—
value—
Properties
  • readonlyprocessedtrue
  • readonlyoktrue
  • readonlyerrornull
  • readonlyvalue"OK"
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(options?: RedisCommandOptions): Promise<RedisArrayResult<unknown>>
Parameters
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

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

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

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

await client.close();

Using connection config object

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

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

Set with expiration

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

const client = await createRedisClient({ url: "redis://localhost:6379" });
const sessionData = JSON.stringify({ userId: "123" });
const data = "temporary value";

// 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 });

await client.close();

Hash operations

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

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

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

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

await client.close();

Pub/Sub

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

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

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

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

await client.close();

Using await using for automatic cleanup

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

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

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

Types

type

#RedisArrayResult

type RedisArrayResult<T = string> = RedisArrayResultSuccess<T>
  | RedisArrayResultError<T>
  | RedisArrayResultFailure<T>

Redis array result (LRANGE, SMEMBERS, etc.).

Links
type

#RedisCommonResult

type RedisCommonResult<T = any> = RedisCommonResultSuccess<T>
  | RedisCommonResultError<T>
  | RedisCommonResultFailure<T>

Redis operation result (common/generic).

Used for operations without a more specific result type.

Links
type

#RedisCountResult

type RedisCountResult = RedisCountResultSuccess | RedisCountResultError | RedisCountResultFailure

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

Links
type

#RedisFailureError

type RedisFailureError = RedisConnectionError | AbortError | TimeoutError

Error types that indicate the operation was not processed. These are errors that occur before the operation reaches the Redis server.

Links
type

#RedisGetResult

type RedisGetResult = RedisGetResultSuccess | RedisGetResultError | RedisGetResultFailure

Redis GET result.

Links
type

#RedisHashResult

type RedisHashResult = RedisHashResultSuccess | RedisHashResultError | RedisHashResultFailure

Redis hash result (HGETALL).

Links
type

#RedisOperationError

type RedisOperationError = RedisCommandError | RedisScriptError | RedisError

Error types that indicate the operation was processed but failed. These are errors returned by the Redis server.

Links
type

#RedisResult

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

Union of all Redis result types.

Links
type

#RedisSetResult

type RedisSetResult = RedisSetResultSuccess | RedisSetResultError | RedisSetResultFailure

Redis SET result.

Links
Search Documentation