182 lines
7.4 KiB
TypeScript
182 lines
7.4 KiB
TypeScript
import { Readable } from 'stream';
|
||
/**
|
||
* Redis client interface for BullMQ.
|
||
*
|
||
* Abstracts the underlying Redis client library (ioredis, node-redis, Bun
|
||
* built-in Redis, etc.) while keeping Redis semantics. Only the Redis
|
||
* commands that BullMQ actually uses are declared here.
|
||
*
|
||
* Method signatures use **structured options objects** instead of ioredis-style
|
||
* varargs so that every adapter (ioredis, node-redis, Bun, …) can map the
|
||
* call to its native API without parsing positional string tokens.
|
||
*
|
||
* The reference implementation for ioredis lives in
|
||
* `src/classes/ioredis-client.ts`.
|
||
*/
|
||
export interface IRedisClient {
|
||
/**
|
||
* Current connection status.
|
||
* Adapters must expose at least the values `'ready'`, `'wait'`, and
|
||
* `'end'` so that {@link RedisConnection.waitUntilReady} works correctly.
|
||
*/
|
||
status: string;
|
||
/** Whether this client is connected to a Redis Cluster. */
|
||
readonly isCluster: boolean;
|
||
/** Client configuration options (shape is adapter-specific). */
|
||
options: Record<string, any>;
|
||
connect(): Promise<void>;
|
||
disconnect(reconnect?: boolean): void;
|
||
quit(): Promise<string>;
|
||
/** Create a duplicate connection with optional overrides. */
|
||
duplicate(...args: any[]): IRedisClient;
|
||
on(event: string, listener: (...args: any[]) => void): this;
|
||
once(event: string, listener: (...args: any[]) => void): this;
|
||
removeListener(event: string, listener: (...args: any[]) => void): this;
|
||
off(event: string, listener: (...args: any[]) => void): this;
|
||
emit(event: string | symbol, ...args: any[]): boolean;
|
||
setMaxListeners(n: number): this;
|
||
getMaxListeners(): number;
|
||
removeAllListeners(event?: string | symbol): this;
|
||
/**
|
||
* Register a Lua script as a named command so it can later be invoked via
|
||
* {@link runCommand}.
|
||
*
|
||
* @param name - Command name that will be callable via runCommand.
|
||
* @param definition - Script definition.
|
||
* - `numberOfKeys` – number of KEYS[] arguments the script expects.
|
||
* - `lua` – Lua source code.
|
||
* - `readOnly` – (optional) hint that the script only reads data;
|
||
* some adapters (e.g. ioredis) use this to route the
|
||
* call to a replica in read-only mode.
|
||
*/
|
||
defineCommand(name: string, definition: {
|
||
numberOfKeys: number;
|
||
lua: string;
|
||
readOnly?: boolean;
|
||
}): void;
|
||
/**
|
||
* Execute a previously registered Lua script command by name.
|
||
*
|
||
* @param name - The command name passed to {@link defineCommand}.
|
||
* @param args - Arguments forwarded to the script (KEYS first, then ARGV).
|
||
* @returns A `Promise<any>` whose resolved value matches the return value of
|
||
* the Lua script. BullMQ scripts return integers, strings, or arrays of
|
||
* strings/integers. Callers in {@link Scripts.execCommand} cast the result
|
||
* to the expected concrete type after the call.
|
||
*/
|
||
runCommand(name: string, args: any[]): Promise<any>;
|
||
multi(): IRedisTransaction;
|
||
pipeline(): IRedisTransaction;
|
||
hgetall(key: string): Promise<Record<string, string>>;
|
||
hget(key: string, field: string): Promise<string | null>;
|
||
hmget(key: string, ...fields: string[]): Promise<(string | null)[]>;
|
||
/** SET one or more hash fields from a field→value map. */
|
||
hset(key: string, data: Record<string, string | number>): Promise<number>;
|
||
hdel(key: string, ...fields: string[]): Promise<number>;
|
||
hexists(key: string, field: string): Promise<number>;
|
||
get(key: string): Promise<string | null>;
|
||
set(key: string, value: string | number, options?: {
|
||
PX?: number;
|
||
EX?: number;
|
||
}): Promise<string | null>;
|
||
del(...keys: string[]): Promise<number>;
|
||
zrange(key: string, start: number, end: number, options?: {
|
||
WITHSCORES?: boolean;
|
||
}): Promise<string[]>;
|
||
zrevrange(key: string, start: number, end: number, options?: {
|
||
WITHSCORES?: boolean;
|
||
}): Promise<string[]>;
|
||
zcard(key: string): Promise<number>;
|
||
zscore(key: string, member: string): Promise<string | null>;
|
||
lrange(key: string, start: number, end: number): Promise<string[]>;
|
||
llen(key: string): Promise<number>;
|
||
ltrim(key: string, start: number, end: number): Promise<string>;
|
||
lpos(key: string, value: string): Promise<number | null>;
|
||
smembers(key: string): Promise<string[]>;
|
||
/**
|
||
* Append an entry to a stream.
|
||
*
|
||
* @param key - Stream key
|
||
* @param id - Entry ID (typically `'*'` for auto-generated)
|
||
* @param fields - Field-value pairs for the stream entry
|
||
* @param options - Optional MAXLEN trimming parameters
|
||
*/
|
||
xadd(key: string, id: string, fields: Record<string, string | number>, options?: {
|
||
MAXLEN?: number;
|
||
approximate?: boolean;
|
||
}): Promise<string>;
|
||
/**
|
||
* Read from one or more streams.
|
||
*
|
||
* @param streams - Array of stream/id pairs to read from
|
||
* @param options - Optional BLOCK timeout and COUNT
|
||
*/
|
||
xread(streams: {
|
||
key: string;
|
||
id: string;
|
||
}[], options?: {
|
||
BLOCK?: number;
|
||
COUNT?: number;
|
||
}): Promise<any>;
|
||
/**
|
||
* Trim a stream.
|
||
*
|
||
* @param key - Stream key
|
||
* @param strategy - Trim strategy (e.g. `'MAXLEN'`)
|
||
* @param threshold - Maximum stream length
|
||
* @param options - Optional approximate trimming
|
||
*/
|
||
xtrim(key: string, strategy: 'MAXLEN', threshold: number, options?: {
|
||
approximate?: boolean;
|
||
}): Promise<number>;
|
||
/**
|
||
* Block until an element is available in the given sorted set, or the
|
||
* timeout expires.
|
||
*
|
||
* The return shape mirrors ioredis' native `bzpopmin`:
|
||
* `[key, member, score]` on success, or `null` on timeout. Adapters for
|
||
* other clients (node-redis, bun) MUST convert their native return value
|
||
* to this tuple form. This avoids mutating the shape of `bzpopmin` on
|
||
* shared ioredis instances, which would be a breaking change for code
|
||
* that uses the same client outside of BullMQ.
|
||
*/
|
||
bzpopmin(key: string, timeout: number): Promise<[key: string, member: string, score: string] | null>;
|
||
info(): Promise<string>;
|
||
clientSetName(name: string): Promise<any>;
|
||
clientList(): Promise<string>;
|
||
scan(cursor: string | number, options: {
|
||
MATCH?: string;
|
||
COUNT?: number;
|
||
}): Promise<[string, string[]]>;
|
||
scanStream(options: {
|
||
match: string;
|
||
count?: number;
|
||
}): Readable;
|
||
/** Return connections for each cluster node (only when isCluster). */
|
||
nodes?(): IRedisClient[];
|
||
}
|
||
/**
|
||
* Redis pipeline or transaction (MULTI).
|
||
*
|
||
* Commands are queued and executed together via {@link exec}.
|
||
* Only the subset of commands BullMQ uses inside pipelines is declared.
|
||
*/
|
||
export interface IRedisTransaction {
|
||
hgetall(key: string): this;
|
||
hset(key: string, data: Record<string, string | number>): this;
|
||
hscan(key: string, cursor: string | number, options?: {
|
||
COUNT?: number;
|
||
}): this;
|
||
smembers(key: string): this;
|
||
sscan(key: string, cursor: string | number, options?: {
|
||
COUNT?: number;
|
||
}): this;
|
||
zrange(key: string, start: number, end: number): this;
|
||
lrange(key: string, start: number, end: number): this;
|
||
llen(key: string): this;
|
||
del(...keys: string[]): this;
|
||
runCommand(name: string, args: any[]): this;
|
||
/** Execute all queued commands. */
|
||
exec(): Promise<[Error | null, any][] | null>;
|
||
}
|