API Reference

Complete reference documentation for all Solidis classes, methods, and interfaces.

Quick Navigation

SolidisClient

The main client class for interacting with Redis servers

Constructor

new SolidisClient(options?: SolidisClientOptions)

Parameters

options

SolidisClientOptions

Optional configuration object

Connection Methods

async connect(): Promise<void>

Establishes a connection to the Redis server. Must be called before performing any operations.

const client = new SolidisClient();
await client.connect();

Basic Operations

async set(key: string, value: StringOrBuffer, options?: CommandSetOptions): Promise<StringOrBuffer | RespOK | null>

Sets a key to hold the string value.

async get(key: string): Promise<string | null>

Gets the value of a key.

async del(...keys: string[]): Promise<number>

Deletes one or more keys.

Example

await client.set('user:123', 'John Doe');

const user = await client.get('user:123');
console.log(user); // 'John Doe'

await client.del('user:123');

Advanced Operations

const transaction = client.multi();

transaction.set('key', 'value');
transaction.incr('counter');
transaction.get('key');

const results = await transaction.exec();
console.log(results); // ['OK', 1, <Buffer 'value'>]

Redis transactions allow the execution of a group of commands in a single step, using the MULTI/EXEC pattern to perform transactions atomically.

Configuration Options

1const client = new SolidisClient({
2  uri: 'redis://localhost:6379',
3  host: '127.0.0.1',
4  port: 6379,
5  tls: { /* tls.ConnectionOptions */ },
6  lazyConnect: false,
7  authentication: {
8    username: 'user',
9    password: 'password',
10  },
11  database: 0,
12  clientName: 'solidis',
13  protocol: 'RESP2',
14  autoReconnect: true,
15  autoRecovery: {
16    database: true,
17    subscribe: true,
18    ssubscribe: true,
19    psubscribe: true,
20  },
21  enableReadyCheck: true,
22  maxConnectionRetries: 20,
23  connectionRetryDelay: 100,
24  commandTimeout: 5000,
25  connectionTimeout: 2000,
26  socketWriteTimeout: 1000,
27  readyCheckInterval: 100,
28  maxCommandsPerPipeline: 300,
29  maxEventListenersForClient: 10240,
30  maxEventListenersForSocket: 10240,
31  maxProcessRepliesPerChunk: 4096,
32  maxSocketWriteSizePerOnce: 65536,
33  rejectOnPartialPipelineError: false,
34  parser: {
35    buffer: {
36      initial: 4194304,
37      shiftThreshold: 2097152,
38    },
39  },
40  debug: false,
41  debugMaxEntries: 10240,
42});

Advanced Features

import { SolidisClient } from '@vcms-io/solidis';
import { get, set } from '@vcms-io/solidis/command';
import type { SolidisClientExtensions } from '@vcms-io/solidis';

const extensions = {
  get,
  set,
  fill: async function(this: typeof client, keys: string[], value: string) {
    return await Promise.all(keys.map((key) => this.set(key, value)));
  },
} satisfies SolidisClientExtensions;

const client = new SolidisClient({
  host: '127.0.0.1',
  port: 6379,
}).extend(extensions);

await client.fill(['key1', 'key2', 'key3'], 'value');

Extend Solidis with custom commands to create higher-level abstractions. The extension system allows adding new features without modifying core code.

Error Handling

import {
  SolidisError,
  SolidisClientError,
  SolidisCommandError,
  SolidisConnectionError,
  SolidisParserError,
  SolidisPubSubError,
  SolidisRequesterError,
  unwrapSolidisError,
} from '@vcms-io/solidis';

try {
  await client.set('key', 'value');
} catch (error) {
  console.error(unwrapSolidisError(error));

  if (error instanceof SolidisConnectionError) {
    console.error('Connection error:', error.message);
  } else if (error instanceof SolidisParserError) {
    console.error('Parser error:', error.message);
  } else if (error instanceof SolidisCommandError) {
    console.error('Command error:', error.message);
  }
}

Error Types

SolidisErrorBase error class for all Solidis errors

SolidisClientErrorSubclass for client-level errors

SolidisCommandErrorErrors during command execution or reply handling

SolidisConnectionErrorErrors related to connection issues

SolidisParserErrorErrors during RESP protocol parsing

SolidisPubSubErrorErrors related to Pub/Sub operations

SolidisRequesterErrorErrors during command execution

Events

client.on('connect', () => console.log('Connected to server'));
client.on('ready', () => console.log('Client is ready'));
client.on('end', () => console.log('Connection closed'));
client.on('close', () => console.log('Connection closed'));
client.on('drain', () => console.log('Socket drain occurred'));
client.on('error', (err) => console.error('Error:', err));

client.on('message', (channel, message) => console.log(`${channel}: ${message}`));
client.on('smessage', (channel, message) => console.log(`${channel}: ${message}`));
client.on('pmessage', (pattern, channel, message) => console.log(`${pattern} ${channel}: ${message}`));

client.on('debug', (entry) => console.log(`[${entry.type}] ${entry.message}`));

Event Types

connectEmitted when the client connects to the server

readyEmitted when the client is ready to send commands

endEmitted when the connection is closed

errorEmitted when an error occurs

messageEmitted when a message is received on a subscribed channel

smessageEmitted when a message is received on a shard channel

debugEmitted when a debug event is logged