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

1new 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.

Example:

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

Basic Operations

String 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 Usage

1// Set a value
2await client.set('user:123', 'John Doe');
3
4// Get a value
5const user = await client.get('user:123');
6console.log(user); // 'John Doe'
7
8// Delete a key
9await client.del('user:123');

Advanced Operations

1// Start a transaction
2const transaction = client.multi();
3
4// Queue commands (no await needed)
5transaction.set('key', 'value');
6transaction.incr('counter');
7transaction.get('key');
8
9// Execute transaction
10const results = await transaction.exec();
11
12console.log(results); // ['OK', 1, <Buffer 'value'>]

Redis transactions allow the execution of a group of commands in a single step, with two important guarantees: all the commands in a transaction are serialized and executed sequentially, and either all or none of the commands are processed.

Configuration Options

1const client = new SolidisClient({
2  uri: 'redis://localhost:6379',
3  host: '127.0.0.1',
4  port: 6379,
5  useTLS: false,
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

1// Import the client and commands
2import { SolidisClient } from '@vcms-io/solidis';
3import { get, set } from '@vcms-io/solidis/command';
4import type { SolidisClientExtensions } from '@vcms-io/solidis';
5
6// Define extensions with custom commands
7const extensions = {
8  get,
9  set,
10  // Custom command implementation
11  fill: async function(this: typeof client, keys: string[], value: string) {
12    return await Promise.all(keys.map((key) => this.set(key, value)));
13  },
14} satisfies SolidisClientExtensions;
15
16// Initialize client with extensions
17const client = new SolidisClient({
18  host: '127.0.0.1',
19  port: 6379,
20}).extend(extensions);
21
22// Use custom command
23await client.fill(['key1', 'key2', 'key3'], 'value');

You can extend Solidis with custom commands to create higher-level abstractions or implement specialized functionality for your application.

Error Handling

1// Import error classes
2import {
3  SolidisError,
4  SolidisClientError,
5  SolidisCommandError,
6  SolidisConnectionError,
7  SolidisParserError,
8  SolidisPubSubError,
9  SolidisRequesterError,
10  unwrapSolidisError,
11} from '@vcms-io/solidis';
12
13// Error handling example
14try {
15  await client.set('key', 'value');
16} catch (error) {
17  // Get the root cause with stack trace
18  console.error(unwrapSolidisError(error));
19
20  // Handle specific error types
21  if (error instanceof SolidisConnectionError) {
22    console.error('Connection error:', error.message);
23  } else if (error instanceof SolidisParserError) {
24    console.error('Parser error:', error.message);
25  } else if (error instanceof SolidisCommandError) {
26    console.error('Command error:', error.message);
27  } else if (error instanceof SolidisClientError) {
28    console.error('Client error:', error.message);
29  }
30}

Error Types

SolidisErrorBase error class for all Solidis errors
SolidisClientErrorSubclass of SolidisError 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

1// Connection events
2client.on('connect', () => console.log('Connected to server'));
3client.on('ready', () => console.log('Client is ready'));
4client.on('end', () => console.log('Connection closed'));
5client.on('close', () => console.log('Connection closed'));
6client.on('drain', () => console.log('Socket drain occurred'));
7client.on('error', (err) => console.error('Error:', err));
8
9// Pub/Sub events
10client.on('message', (channel, message) => console.log(`${channel}: ${message}`));
11client.on('smessage', (channel, message) => console.log(`${channel}: ${message}`));
12client.on('pmessage', (pattern, channel, message) => console.log(`${pattern} ${channel}: ${message}`));
13client.on('subscribe', (channel, count) => console.log(`Subscribed to ${channel}`));
14client.on('ssubscribe', (channel, count) => console.log(`Subscribed to shard channel ${channel}`));
15client.on('unsubscribe', (channel, count) => console.log(`Unsubscribed from ${channel}`));
16client.on('sunsubscribe', (channel, count) => console.log(`Unsubscribed from shard channel ${channel}`));
17
18// Debug events
19client.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
closeEmitted when the connection is closed
drainEmitted when the socket drain occurs
errorEmitted when an error occurs
messageEmitted when a message is received on a subscribed channel
smessageEmitted when a message is received on a subscribed shard channel
ssubscribeEmitted when subscribed to a shard channel
sunsubscribeEmitted when unsubscribed from a shard channel