WebSocket String Operations

The DBX WebSocket API provides real-time string operations for Redis. This guide covers all available string methods and their usage patterns.

Installation

npm install @0dbx/redis

Basic Usage

import { DbxWsClient } from "@0dbx/redis";
 
// Create WebSocket client
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// String operations
await wsClient.string.set("my-key", "hello world");
const value = await wsClient.string.get("my-key");

Connection Setup

Before using string operations, establish a WebSocket connection:

import { DbxWsClient } from "@0dbx/redis";
 
const client = new DbxWsClient("ws://localhost:8080/ws");
 
await client.connect();

String Operations

GET - Retrieve a String Value

Retrieve a string value by key.

Request:

{
  "id": "req-1",
  "method": "GET",
  "params": {
    "key": "user:123:name"
  }
}

Response:

{
  "id": "req-1",
  "result": {
    "value": "John Doe"
  }
}

Error Response:

{
  "id": "req-1",
  "error": {
    "code": "KEY_NOT_FOUND",
    "message": "Key 'user:123:name' not found"
  }
}

SET - Set a String Value

Set a string value with optional expiration.

Request:

{
  "id": "req-2",
  "method": "SET",
  "params": {
    "key": "user:123:name",
    "value": "John Doe",
    "expire": 3600
  }
}

Response:

{
  "id": "req-2",
  "result": {
    "success": true
  }
}

SETNX - Set if Not Exists

Set a string value only if the key doesn't already exist.

Request:

{
  "id": "req-3",
  "method": "SETNX",
  "params": {
    "key": "user:123:name",
    "value": "John Doe"
  }
}

Response:

{
  "id": "req-3",
  "result": {
    "success": true,
    "created": true
  }
}

MSET - Set Multiple Values

Set multiple string values atomically.

Request:

{
  "id": "req-4",
  "method": "MSET",
  "params": {
    "pairs": {
      "user:123:name": "John Doe",
      "user:123:email": "john@example.com",
      "user:123:age": "30"
    }
  }
}

Response:

{
  "id": "req-4",
  "result": {
    "success": true
  }
}

MGET - Get Multiple Values

Retrieve multiple string values by keys.

Request:

{
  "id": "req-5",
  "method": "MGET",
  "params": {
    "keys": ["user:123:name", "user:123:email", "user:123:age"]
  }
}

Response:

{
  "id": "req-5",
  "result": {
    "values": ["John Doe", "john@example.com", "30"]
  }
}

INCR - Increment Counter

Increment a numeric string value by 1.

Request:

{
  "id": "req-6",
  "method": "INCR",
  "params": {
    "key": "counter:visits"
  }
}

Response:

{
  "id": "req-6",
  "result": {
    "value": 42
  }
}

INCRBY - Increment by Amount

Increment a numeric string value by a specified amount.

Request:

{
  "id": "req-7",
  "method": "INCRBY",
  "params": {
    "key": "counter:visits",
    "amount": 5
  }
}

Response:

{
  "id": "req-7",
  "result": {
    "value": 47
  }
}

DECR - Decrement Counter

Decrement a numeric string value by 1.

Request:

{
  "id": "req-8",
  "method": "DECR",
  "params": {
    "key": "counter:visits"
  }
}

Response:

{
  "id": "req-8",
  "result": {
    "value": 46
  }
}

DECRBY - Decrement by Amount

Decrement a numeric string value by a specified amount.

Request:

{
  "id": "req-9",
  "method": "DECRBY",
  "params": {
    "key": "counter:visits",
    "amount": 3
  }
}

Response:

{
  "id": "req-9",
  "result": {
    "value": 43
  }
}

APPEND - Append to String

Append a value to an existing string.

Request:

{
  "id": "req-10",
  "method": "APPEND",
  "params": {
    "key": "user:123:notes",
    "value": " - Updated on 2024-01-15"
  }
}

Response:

{
  "id": "req-10",
  "result": {
    "length": 45
  }
}

STRLEN - Get String Length

Get the length of a string value.

Request:

{
  "id": "req-11",
  "method": "STRLEN",
  "params": {
    "key": "user:123:name"
  }
}

Response:

{
  "id": "req-11",
  "result": {
    "length": 8
  }
}

GETRANGE - Get String Range

Get a substring from a string value.

Request:

{
  "id": "req-12",
  "method": "GETRANGE",
  "params": {
    "key": "user:123:name",
    "start": 0,
    "end": 3
  }
}

Response:

{
  "id": "req-12",
  "result": {
    "value": "John"
  }
}

SETRANGE - Set String Range

Set a substring within a string value.

Request:

{
  "id": "req-13",
  "method": "SETRANGE",
  "params": {
    "key": "user:123:name",
    "offset": 5,
    "value": "Smith"
  }
}

Response:

{
  "id": "req-13",
  "result": {
    "length": 10
  }
}

Error Handling

All WebSocket string operations return standardized error responses:

{
  "id": "request-id",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}

Common error codes:

KEY_NOT_FOUND: The specified key doesn't exist
INVALID_VALUE: The value is not valid for the operation
TYPE_MISMATCH: The key exists but is not a string type
AUTHENTICATION_FAILED: Invalid or missing authentication token
RATE_LIMITED: Request rate limit exceeded

TypeScript SDK Example

import { DbxWsClient } from "@0dbx/redis";
 
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// String operations
await wsClient.string.set("user:1:name", "John Doe");
const name = await wsClient.string.get("user:1:name");
console.log(name); // "John Doe"

Best Practices

Connection Management: Reuse WebSocket connections when possible
Error Handling: Always handle potential errors in your application
Rate Limiting: Respect rate limits and implement backoff strategies
Key Naming: Use consistent key naming conventions (e.g., type:id:field)
Expiration: Set appropriate TTL values for temporary data
Batch Operations: Use MSET/MGET for multiple operations when possible

Performance Considerations

WebSocket connections provide lower latency than REST API calls
Batch operations (MSET/MGET) are more efficient than individual calls
Connection pooling can improve performance in high-throughput scenarios
Consider using pipelining for multiple sequential operations