Redis Client

import { RedisClient } from "bun";

/**
 * High-performance Redis client with automatic connection management
 */
class RedisClient {
  /**
   * Creates a new Redis client
   * @param url - Redis connection URL (defaults to environment variables or localhost)
   * @param options - Connection configuration options
   */
  constructor(url?: string, options?: RedisOptions);

  /** Whether the client is connected to the Redis server */
  readonly connected: boolean;
  
  /** Amount of data buffered in bytes */
  readonly bufferedAmount: number;
  
  /** Connection event callback */
  onconnect: ((this: RedisClient) => void) | null;
  
  /** Disconnection event callback */
  onclose: ((this: RedisClient, error: Error) => void) | null;
  
  /**
   * Connect to the Redis server
   * @returns Promise that resolves when connected
   */
  connect(): Promise<void>;
  
  /**
   * Disconnect from the Redis server
   */
  close(): void;
  
  /**
   * Send a raw command to the Redis server
   * @param command - The command to send
   * @param args - The arguments to the command
   * @returns Promise that resolves with the command result
   */
  send(command: string, args: string[]): Promise<any>;
}

interface RedisOptions {
  /** Connection timeout in milliseconds @default 10000 */
  connectionTimeout?: number;
  /** Idle timeout in milliseconds @default 0 */
  idleTimeout?: number;
  /** Whether to automatically reconnect @default true */
  autoReconnect?: boolean;
  /** Maximum number of reconnection attempts @default 10 */
  maxRetries?: number;
  /** Whether to queue commands when disconnected @default true */
  enableOfflineQueue?: boolean;
  /** Whether to enable auto-pipelining @default true */
  enableAutoPipelining?: boolean;
  /** TLS configuration */
  tls?: boolean | {
    key?: string | Buffer;
    cert?: string | Buffer;
    ca?: string | Buffer | Array<string | Buffer>;
    rejectUnauthorized?: boolean;
  };
}

type KeyLike = string | ArrayBufferView | Blob;

import { RedisClient } from "bun";

// Connect with defaults (localhost:6379)
const redis = new RedisClient();

// Connect with URL
const redis = new RedisClient("redis://user:pass@localhost:6379/0");

// Connect with TLS
const secureRedis = new RedisClient("rediss://redis.example.com:6380", {
  tls: {
    rejectUnauthorized: true
  }
});

// Connection event handling
redis.onconnect = function() {
  console.log("Connected to Redis");
};

redis.onclose = function(error) {
  console.log("Disconnected:", error.message);
};

await redis.connect();

/**
 * Get the value of a key
 * @param key - The key to get
 * @returns Promise that resolves with the key's value or null
 */
get(key: KeyLike): Promise<string | null>;

/**
 * Get the value of a key as a Uint8Array
 * @param key - The key to get
 * @returns Promise that resolves with the key's value as bytes or null
 */
getBuffer(key: KeyLike): Promise<Uint8Array | null>;

/**
 * Set key to hold the string value
 * @param key - The key to set
 * @param value - The value to set
 * @returns Promise that resolves with "OK" on success
 */
set(key: KeyLike, value: KeyLike): Promise<"OK">;

/**
 * Set key with expiration in seconds
 * @param key - The key to set
 * @param value - The value to set
 * @param ex - "EX" flag for seconds
 * @param seconds - Expiration time in seconds
 * @returns Promise that resolves with "OK" on success
 */
set(key: KeyLike, value: KeyLike, ex: "EX", seconds: number): Promise<"OK">;

/**
 * Set key with expiration in milliseconds
 * @param key - The key to set
 * @param value - The value to set
 * @param px - "PX" flag for milliseconds
 * @param milliseconds - Expiration time in milliseconds
 * @returns Promise that resolves with "OK" on success
 */
set(key: KeyLike, value: KeyLike, px: "PX", milliseconds: number): Promise<"OK">;

/**
 * Set key only if it does not exist
 * @param key - The key to set
 * @param value - The value to set
 * @param nx - "NX" flag for not exists
 * @returns Promise that resolves with "OK" or null if key exists
 */
set(key: KeyLike, value: KeyLike, nx: "NX"): Promise<"OK" | null>;

/**
 * Set key only if it already exists
 * @param key - The key to set
 * @param value - The value to set
 * @param xx - "XX" flag for exists
 * @returns Promise that resolves with "OK" or null if key doesn't exist
 */
set(key: KeyLike, value: KeyLike, xx: "XX"): Promise<"OK" | null>;

/**
 * Set key and return the old value
 * @param key - The key to set
 * @param value - The value to set
 * @param get - "GET" flag to return old value
 * @returns Promise that resolves with the old value or null
 */
set(key: KeyLike, value: KeyLike, get: "GET"): Promise<string | null>;

/**
 * Delete one or more keys
 * @param keys - The keys to delete
 * @returns Promise that resolves with the number of keys removed
 */
del(...keys: KeyLike[]): Promise<number>;

/**
 * Increment the integer value of a key by one
 * @param key - The key to increment
 * @returns Promise that resolves with the new value
 */
incr(key: KeyLike): Promise<number>;

/**
 * Decrement the integer value of a key by one
 * @param key - The key to decrement
 * @returns Promise that resolves with the new value
 */
decr(key: KeyLike): Promise<number>;

/**
 * Determine if a key exists
 * @param key - The key to check
 * @returns Promise that resolves with true if the key exists
 */
exists(key: KeyLike): Promise<boolean>;

const redis = new RedisClient();
await redis.connect();

// Basic string operations
await redis.set("message", "Hello Redis!");
const value = await redis.get("message"); // "Hello Redis!"

// Set with expiration
await redis.set("session:123", "user-data", "EX", 3600); // Expires in 1 hour
await redis.set("cache:key", "data", "PX", 5000); // Expires in 5 seconds

// Conditional sets
const result1 = await redis.set("counter", "0", "NX"); // Only if not exists
const result2 = await redis.set("counter", "1", "XX"); // Only if exists

// Atomic operations
await redis.set("views", "0");
await redis.incr("views"); // 1
await redis.incr("views"); // 2
await redis.decr("views"); // 1

// Check existence and delete
const exists = await redis.exists("message"); // true
const deleted = await redis.del("message", "views"); // 2 (number of keys deleted)

/**
 * Insert all the specified values at the head of the list
 * @param key - The list key
 * @param elements - The elements to prepend
 * @returns Promise that resolves with the length of the list after the operation
 */
lpush(key: KeyLike, ...elements: KeyLike[]): Promise<number>;

/**
 * Insert all the specified values at the tail of the list
 * @param key - The list key
 * @param elements - The elements to append
 * @returns Promise that resolves with the length of the list after the operation
 */
rpush(key: KeyLike, ...elements: KeyLike[]): Promise<number>;

/**
 * Remove and return the first element of the list
 * @param key - The list key
 * @returns Promise that resolves with the popped element or null if list is empty
 */
lpop(key: KeyLike): Promise<string | null>;

/**
 * Remove and return the last element of the list
 * @param key - The list key
 * @returns Promise that resolves with the popped element or null if list is empty
 */
rpop(key: KeyLike): Promise<string | null>;

/**
 * Get the length of a list
 * @param key - The list key
 * @returns Promise that resolves with the length of the list
 */
llen(key: KeyLike): Promise<number>;

/**
 * Get a range of elements from a list
 * @param key - The list key
 * @param start - Start index (0-based)
 * @param stop - Stop index (inclusive, -1 for last element)
 * @returns Promise that resolves with array of elements
 */
lrange(key: KeyLike, start: number, stop: number): Promise<string[]>;

// Queue operations (FIFO)
await redis.rpush("queue", "job1", "job2", "job3"); // Add to tail
const job = await redis.lpop("queue"); // Remove from head: "job1"

// Stack operations (LIFO)
await redis.lpush("stack", "item1", "item2", "item3"); // Add to head
const item = await redis.lpop("stack"); // Remove from head: "item3"

// List inspection
const length = await redis.llen("queue"); // Get list length
const items = await redis.lrange("queue", 0, -1); // Get all items
const recent = await redis.lrange("queue", 0, 4); // Get first 5 items