API Reference

The client class, its core methods, options, errors and events.

Quick Navigation

SolidisClient

The core client: connect(), quit(), send(), extend() and the handshake commands. SolidisFeaturedClient, used in the examples below, adds every command.

Constructor

new SolidisClient(options?: SolidisClientOptions)

Parameters

options

SolidisClientOptions

Optional configuration object

Connection Methods

async connect(): Promise<void>

Connects to the server and resolves once the client is ready. The constructor calls it unless lazyConnect is true, in which case the first command also connects. Commands sent before the client is ready wait for it.

import { SolidisFeaturedClient } from '@vcms-io/solidis/featured';

const client = new SolidisFeaturedClient();
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, options?: CommandBufferOptions): Promise<string | Buffer | 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'>]

A transaction runs a group of commands atomically, in one step, with MULTI/EXEC.

Configuration Options

1const client = new SolidisClient({
2  uri: 'redis://user:password@localhost:6379/0',
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  maxConnectionRetryDelay: 2000,
25  commandTimeout: 5000,
26  connectionTimeout: 2000,
27  readyCheckInterval: 100,
28  maxReadyCheckRetries: 100,
29  maxCommandsPerPipeline: 300,
30  maxEventListenersForClient: 10240,
31  rejectOnPartialPipelineError: false,
32  parser: {
33    maxBulkStringLength: 536870912,
34  },
35  debug: false,
36});

Advanced Features

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

const client = new SolidisClient({ host: '127.0.0.1', port: 6379 }).extend({
  get,
  set,
  async fill(keys: string[], value: string) {
    return await Promise.all(keys.map((key) => this.set(key, value)));
  },
});

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

Add your own commands with extend() to build higher-level abstractions without touching the core.

Error Handling

import {
  SolidisCommandError,
  SolidisConnectionError,
  SolidisParserError,
  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

SolidisRequesterErrorCommand timeouts and commands rejected before sending

Events

client.on('connect', () => console.log('Connected to server'));
client.on('ready', () => console.log('Client is ready'));
client.on('close', (error) => console.log('Connection lost:', error.message));
client.on('reconnecting', (attempt, delay) => console.log(`Reconnect attempt ${attempt} in ${delay} ms`));
client.on('reconnected', () => console.log('Connection re-established'));
client.on('end', () => console.log('Client quit'));
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('push', (reply) => console.log('push:', reply));

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

closeEmitted with the cause when the connection is lost

reconnectingEmitted with the attempt number and delay before each reconnect attempt

reconnectedEmitted when a reconnect completes and the client is ready again

endEmitted when the client quits

drainEmitted when the socket's write buffer drains

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

pmessageEmitted when a message matches a subscribed pattern

subscribeEmitted with the channel or pattern and the subscription count when a subscription changes; psubscribe, ssubscribe and each unsubscribe event work the same way

pushEmitted for pushes that are not Pub/Sub messages, such as client tracking invalidations, including those RESP2 delivers on __redis__:invalidate

debugEmitted when a debug event is logged