diff --git a/packages/client/lib/RESP/types.ts b/packages/client/lib/RESP/types.ts index 692c433a49d..6bf8802dbed 100644 --- a/packages/client/lib/RESP/types.ts +++ b/packages/client/lib/RESP/types.ts @@ -5,13 +5,22 @@ import { RedisScriptConfig, SHA1 } from '../lua-script'; import { RESP_TYPES } from './decoder'; import { VerbatimString } from './verbatim-string'; +/** + * Type definition for RESP (Redis Serialization Protocol) types. + */ export type RESP_TYPES = typeof RESP_TYPES; +/** + * Union type of all possible RESP types. + */ export type RespTypes = RESP_TYPES[keyof RESP_TYPES]; // using interface(s) to allow circular references // type X = BlobStringReply | ArrayReply; +/** + * Base interface for all RESP types. + */ export interface RespType< RESP_TYPE extends RespTypes, DEFAULT, @@ -24,11 +33,17 @@ export interface RespType< TYPE_MAPPING: MappedType; } +/** + * Represents a NULL response in Redis. + */ export interface NullReply extends RespType< RESP_TYPES['NULL'], null > {} +/** + * Represents a boolean response in Redis. + */ export interface BooleanReply< T extends boolean = boolean > extends RespType< @@ -36,6 +51,9 @@ export interface BooleanReply< T > {} +/** + * Represents a numeric response in Redis. + */ export interface NumberReply< T extends number = number > extends RespType< @@ -45,6 +63,9 @@ export interface NumberReply< number | string > {} +/** + * Represents a big number response in Redis. + */ export interface BigNumberReply< T extends bigint = bigint > extends RespType< @@ -54,6 +75,9 @@ export interface BigNumberReply< bigint | number | string > {} +/** + * Represents a double-precision floating point response in Redis. + */ export interface DoubleReply< T extends number = number > extends RespType< @@ -63,6 +87,9 @@ export interface DoubleReply< number | string > {} +/** + * Represents a simple string response in Redis. + */ export interface SimpleStringReply< T extends string = string > extends RespType< @@ -72,6 +99,9 @@ export interface SimpleStringReply< string | Buffer > {} +/** + * Represents a bulk string response in Redis. + */ export interface BlobStringReply< T extends string = string > extends RespType< @@ -83,6 +113,9 @@ export interface BlobStringReply< toString(): string } +/** + * Represents a verbatim string response in Redis. + */ export interface VerbatimStringReply< T extends string = string > extends RespType< @@ -92,18 +125,27 @@ export interface VerbatimStringReply< string | Buffer | VerbatimString > {} +/** + * Represents a simple error response in Redis. + */ export interface SimpleErrorReply extends RespType< RESP_TYPES['SIMPLE_ERROR'], SimpleError, Buffer > {} +/** + * Represents a bulk error response in Redis. + */ export interface BlobErrorReply extends RespType< RESP_TYPES['BLOB_ERROR'], BlobError, Buffer > {} +/** + * Represents an array response in Redis. + */ export interface ArrayReply extends RespType< RESP_TYPES['ARRAY'], Array, @@ -111,6 +153,9 @@ export interface ArrayReply extends RespType< Array > {} +/** + * Represents a tuple response in Redis. + */ export interface TuplesReply]> extends RespType< RESP_TYPES['ARRAY'], T, @@ -118,6 +163,9 @@ export interface TuplesReply]> extends RespType< Array > {} +/** + * Represents a set response in Redis. + */ export interface SetReply extends RespType< RESP_TYPES['SET'], Array, @@ -125,6 +173,9 @@ export interface SetReply extends RespType< Array | Set > {} +/** + * Represents a map response in Redis. + */ export interface MapReply extends RespType< RESP_TYPES['MAP'], { [key: string]: V }, @@ -222,8 +273,14 @@ export type ReplyWithTypeMapping< export type TransformReply = (this: void, reply: any, preserve?: any, typeMapping?: TypeMapping) => any; // TODO; +/** + * Type definition for Redis command arguments. + */ export type RedisArgument = string | Buffer; +/** + * Type definition for Redis command arguments with optional preserve flag. + */ export type CommandArguments = Array & { preserve?: unknown }; // export const REQUEST_POLICIES = { @@ -273,6 +330,9 @@ export type CommandArguments = Array & { preserve?: unknown }; // response?: ResponsePolicies | null; // }; +/** + * Interface defining a Redis command. + */ export type Command = { CACHEABLE?: boolean; IS_READ_ONLY?: boolean; @@ -289,21 +349,41 @@ export type Command = { unstableResp3?: boolean; }; +/** + * Type definition for Redis commands. + */ export type RedisCommands = Record; +/** + * Type definition for Redis modules. + */ export type RedisModules = Record; +/** + * Interface extending Command for Redis functions. + */ export interface RedisFunction extends Command { NUMBER_OF_KEYS?: number; } +/** + * Type definition for Redis functions. + */ export type RedisFunctions = Record>; +/** + * Type definition for Redis scripts. + */ export type RedisScript = RedisScriptConfig & SHA1; +/** + * Type definition for Redis scripts collection. + */ export type RedisScripts = Record; -// TODO: move to Commander? +/** + * Interface for Redis commander configuration. + */ export interface CommanderConfig< M extends RedisModules, F extends RedisFunctions, @@ -314,11 +394,11 @@ export interface CommanderConfig< functions?: F; scripts?: S; /** - * TODO + * The RESP protocol version to use (2 or 3) */ RESP?: RESP; /** - * TODO + * Whether to use unstable RESP3 features */ unstableResp3?: boolean; } @@ -350,8 +430,14 @@ export type Resp2Reply = ( RESP3REPLY ); +/** + * Type definition for RESP protocol versions (2 or 3). + */ export type RespVersions = 2 | 3; +/** + * Type definition for command replies. + */ export type CommandReply< COMMAND extends Command, RESP extends RespVersions @@ -364,6 +450,9 @@ export type CommandReply< ReplyUnion ); +/** + * Type definition for command signatures. + */ export type CommandSignature< COMMAND extends Command, RESP extends RespVersions, diff --git a/packages/client/lib/client/index.ts b/packages/client/lib/client/index.ts index 5dae1271ecb..59ec0e59dfa 100644 --- a/packages/client/lib/client/index.ts +++ b/packages/client/lib/client/index.ts @@ -18,6 +18,9 @@ import { RedisPoolOptions, RedisClientPool } from './pool'; import { RedisVariadicArgument, parseArgs, pushVariadicArguments } from '../commands/generic-transformers'; import { BasicCommandParser, CommandParser } from './parser'; +/** + * Interface defining options for creating a Redis client. + */ export interface RedisClientOptions< M extends RedisModules = RedisModules, F extends RedisFunctions = RedisFunctions, @@ -82,6 +85,11 @@ export interface RedisClientOptions< commandOptions?: CommandOptions; } +/** + * Type mapping Redis commands to their signatures. + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithCommands< RESP extends RespVersions, TYPE_MAPPING extends TypeMapping @@ -89,6 +97,12 @@ type WithCommands< [P in keyof typeof COMMANDS]: CommandSignature<(typeof COMMANDS)[P], RESP, TYPE_MAPPING>; }; +/** + * Type mapping Redis modules to their command signatures. + * @template M - Redis modules type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithModules< M extends RedisModules, RESP extends RespVersions, @@ -99,6 +113,12 @@ type WithModules< }; }; +/** + * Type mapping Redis functions to their command signatures. + * @template F - Redis functions type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithFunctions< F extends RedisFunctions, RESP extends RespVersions, @@ -109,6 +129,12 @@ type WithFunctions< }; }; +/** + * Type mapping Redis scripts to their command signatures. + * @template S - Redis scripts type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithScripts< S extends RedisScripts, RESP extends RespVersions, @@ -117,6 +143,9 @@ type WithScripts< [P in keyof S]: CommandSignature; }; +/** + * Type combining all Redis client extensions (commands, modules, functions, scripts). + */ export type RedisClientExtensions< M extends RedisModules = {}, F extends RedisFunctions = {}, @@ -130,6 +159,9 @@ export type RedisClientExtensions< WithScripts ); +/** + * Type definition for a Redis client with all its extensions. + */ export type RedisClientType< M extends RedisModules = {}, F extends RedisFunctions = {}, @@ -141,16 +173,31 @@ export type RedisClientType< RedisClientExtensions ); +/** + * Type for a proxy client that can handle any Redis modules, functions, scripts, and RESP versions. + */ type ProxyClient = RedisClient; +/** + * Type for a namespace proxy client that contains a reference to the underlying proxy client. + */ type NamespaceProxyClient = { _self: ProxyClient }; +/** + * Interface defining options for scan iterators. + */ interface ScanIteratorOptions { cursor?: RedisArgument; } +/** + * Type definition for a monitor callback function. + */ export type MonitorCallback = (reply: ReplyWithTypeMapping) => unknown; +/** + * The main Redis client class that handles connections, commands, and pub/sub functionality. + */ export default class RedisClient< M extends RedisModules, F extends RedisFunctions, diff --git a/packages/client/lib/cluster/index.ts b/packages/client/lib/cluster/index.ts index 12928e71f12..2d1fd67744c 100644 --- a/packages/client/lib/cluster/index.ts +++ b/packages/client/lib/cluster/index.ts @@ -13,6 +13,14 @@ import ASKING from '../commands/ASKING'; import { BasicCommandParser } from '../client/parser'; import { parseArgs } from '../commands/generic-transformers'; +/** + * Interface extending CommanderConfig for Redis cluster commands. + * @template M - Redis modules type + * @template F - Redis functions type + * @template S - Redis scripts type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ interface ClusterCommander< M extends RedisModules, F extends RedisFunctions, @@ -24,11 +32,18 @@ interface ClusterCommander< commandOptions?: ClusterCommandOptions; } +/** + * Type definition for Redis cluster client options. + * Omits cluster-specific options from the base client options. + */ export type RedisClusterClientOptions = Omit< RedisClientOptions, keyof ClusterCommander >; +/** + * Interface defining options for creating a Redis cluster client. + */ export interface RedisClusterOptions< M extends RedisModules = RedisModules, F extends RedisFunctions = RedisFunctions, @@ -68,7 +83,11 @@ export interface RedisClusterOptions< nodeAddressMap?: NodeAddressMap; } -// remove once request & response policies are ready +/** + * Type mapping cluster commands to their signatures. + * @template NAME - The command name + * @template COMMAND - The command type + */ type ClusterCommand< NAME extends PropertyKey, COMMAND extends Command @@ -84,6 +103,12 @@ type WithCommands< [P in keyof typeof COMMANDS as ClusterCommand]: CommandSignature<(typeof COMMANDS)[P], RESP, TYPE_MAPPING>; }; +/** + * Type mapping Redis modules to their command signatures in a cluster context. + * @template M - Redis modules type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithModules< M extends RedisModules, RESP extends RespVersions, @@ -94,6 +119,12 @@ type WithModules< }; }; +/** + * Type mapping Redis functions to their command signatures in a cluster context. + * @template F - Redis functions type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithFunctions< F extends RedisFunctions, RESP extends RespVersions, @@ -104,6 +135,12 @@ type WithFunctions< }; }; +/** + * Type mapping Redis scripts to their command signatures in a cluster context. + * @template S - Redis scripts type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithScripts< S extends RedisScripts, RESP extends RespVersions, @@ -112,21 +149,26 @@ type WithScripts< [P in keyof S as ClusterCommand]: CommandSignature; }; +/** + * Type definition for a Redis cluster client with all its extensions. + */ export type RedisClusterType< M extends RedisModules = {}, F extends RedisFunctions = {}, S extends RedisScripts = {}, RESP extends RespVersions = 2, - TYPE_MAPPING extends TypeMapping = {}, - // POLICIES extends CommandPolicies = {} + TYPE_MAPPING extends TypeMapping = {} > = ( - RedisCluster & + RedisCluster & WithCommands & WithModules & WithFunctions & WithScripts ); +/** + * Interface defining options for cluster commands. + */ export interface ClusterCommandOptions< TYPE_MAPPING extends TypeMapping = TypeMapping // POLICIES extends CommandPolicies = CommandPolicies @@ -134,10 +176,19 @@ export interface ClusterCommandOptions< // policies?: POLICIES; } +/** + * Type for a proxy cluster that can handle any Redis modules, functions, scripts, and RESP versions. + */ type ProxyCluster = RedisCluster; +/** + * Type for a namespace proxy cluster that contains a reference to the underlying proxy cluster. + */ type NamespaceProxyCluster = { _self: ProxyCluster }; +/** + * The main Redis cluster client class that handles cluster connections, commands, and pub/sub functionality. + */ export default class RedisCluster< M extends RedisModules, F extends RedisFunctions, diff --git a/packages/client/lib/sentinel/types.ts b/packages/client/lib/sentinel/types.ts index 428e7bccd66..770d90337f3 100644 --- a/packages/client/lib/sentinel/types.ts +++ b/packages/client/lib/sentinel/types.ts @@ -5,11 +5,17 @@ import COMMANDS from '../commands'; import RedisSentinel, { RedisSentinelClient } from '.'; import { RedisTcpSocketOptions } from '../client/socket'; +/** + * Interface defining a Redis node with host and port. + */ export interface RedisNode { host: string; port: number; } +/** + * Interface defining options for creating a Redis Sentinel client. + */ export interface RedisSentinelOptions< M extends RedisModules = RedisModules, F extends RedisFunctions = RedisFunctions, @@ -63,6 +69,9 @@ export interface RedisSentinelOptions< reserveClient?: boolean; } +/** + * Interface extending CommanderConfig for Redis Sentinel commands. + */ export interface SentinelCommander< M extends RedisModules, F extends RedisFunctions, @@ -74,11 +83,20 @@ export interface SentinelCommander< commandOptions?: CommandOptions; } +/** + * Type definition for Redis Sentinel client options. + * Omits sentinel-specific options from the base client options. + */ export type RedisSentinelClientOptions = Omit< RedisClientOptions, keyof SentinelCommander >; +/** + * Type mapping Redis commands to their signatures in a sentinel context. + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithCommands< RESP extends RespVersions, TYPE_MAPPING extends TypeMapping @@ -86,6 +104,12 @@ type WithCommands< [P in keyof typeof COMMANDS]: CommandSignature<(typeof COMMANDS)[P], RESP, TYPE_MAPPING>; }; +/** + * Type mapping Redis modules to their command signatures in a sentinel context. + * @template M - Redis modules type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithModules< M extends RedisModules, RESP extends RespVersions, @@ -96,6 +120,12 @@ type WithModules< }; }; +/** + * Type mapping Redis functions to their command signatures in a sentinel context. + * @template F - Redis functions type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithFunctions< F extends RedisFunctions, RESP extends RespVersions, @@ -106,6 +136,12 @@ type WithFunctions< }; }; +/** + * Type mapping Redis scripts to their command signatures in a sentinel context. + * @template S - Redis scripts type + * @template RESP - RESP protocol version + * @template TYPE_MAPPING - Type mapping for Redis responses + */ type WithScripts< S extends RedisScripts, RESP extends RespVersions, @@ -114,6 +150,9 @@ type WithScripts< [P in keyof S]: CommandSignature; }; +/** + * Type definition for a Redis Sentinel client with all its extensions. + */ export type RedisSentinelClientType< M extends RedisModules = {}, F extends RedisFunctions = {}, @@ -128,13 +167,15 @@ export type RedisSentinelClientType< WithScripts ); +/** + * Type definition for a Redis Sentinel with all its extensions. + */ export type RedisSentinelType< M extends RedisModules = {}, F extends RedisFunctions = {}, S extends RedisScripts = {}, RESP extends RespVersions = 2, TYPE_MAPPING extends TypeMapping = {}, - // POLICIES extends CommandPolicies = {} > = ( RedisSentinel & WithCommands & @@ -143,33 +184,66 @@ export type RedisSentinelType< WithScripts ); +/** + * Interface defining options for sentinel commands. + */ export interface SentinelCommandOptions< TYPE_MAPPING extends TypeMapping = TypeMapping > extends CommandOptions {} +/** + * Type for a proxy sentinel that can handle any Redis modules, functions, scripts, and RESP versions. + */ export type ProxySentinel = RedisSentinel; + +/** + * Type for a proxy sentinel client that can handle any Redis modules, functions, scripts, and RESP versions. + */ export type ProxySentinelClient = RedisSentinelClient; + +/** + * Type for a namespace proxy sentinel that contains a reference to the underlying proxy sentinel. + */ export type NamespaceProxySentinel = { _self: ProxySentinel }; + +/** + * Type for a namespace proxy sentinel client that contains a reference to the underlying proxy sentinel client. + */ export type NamespaceProxySentinelClient = { _self: ProxySentinelClient }; +/** + * Type definition for Redis node information. + */ export type NodeInfo = { ip: any, port: any, flags: any, }; +/** + * Type definition for Redis Sentinel events. + */ export type RedisSentinelEvent = NodeChangeEvent | SizeChangeEvent; - + +/** + * Type definition for node change events in Redis Sentinel. + */ export type NodeChangeEvent = { type: "SENTINEL_CHANGE" | "MASTER_CHANGE" | "REPLICA_ADD" | "REPLICA_REMOVE"; node: RedisNode; } +/** + * Type definition for size change events in Redis Sentinel. + */ export type SizeChangeEvent = { type: "SENTINE_LIST_CHANGE"; size: Number; } +/** + * Type definition for client error events in Redis Sentinel. + */ export type ClientErrorEvent = { type: 'MASTER' | 'REPLICA' | 'SENTINEL' | 'PUBSUBPROXY'; node: RedisNode; diff --git a/packages/redis/index.ts b/packages/redis/index.ts index 73477363d3b..eec380843a1 100644 --- a/packages/redis/index.ts +++ b/packages/redis/index.ts @@ -32,8 +32,15 @@ const modules = { ts: RedisTimeSeries }; +/** + * The default Redis modules available in this package. + * Includes RedisBloom, RedisJSON, RediSearch, and RedisTimeSeries modules. + */ export type RedisDefaultModules = typeof modules; +/** + * Type definition for a Redis client with support for modules, functions, and scripts. + */ export type RedisClientType< M extends RedisModules = RedisDefaultModules, F extends RedisFunctions = {}, @@ -42,6 +49,11 @@ export type RedisClientType< TYPE_MAPPING extends TypeMapping = {} > = GenericRedisClientType; +/** + * Creates a new Redis client. + * @param options - The options for the Redis client. + * @returns A new Redis client. + */ export function createClient< M extends RedisModules, F extends RedisFunctions, @@ -60,14 +72,11 @@ export function createClient< }); } -export type RedisClusterType< - M extends RedisModules = RedisDefaultModules, - F extends RedisFunctions = {}, - S extends RedisScripts = {}, - RESP extends RespVersions = 2, - TYPE_MAPPING extends TypeMapping = {} -> = genericRedisClusterType; - +/** + * Creates a new Redis cluster client. + * @param options - Configuration options for the Redis cluster client + * @returns A new Redis cluster client instance + */ export function createCluster< M extends RedisModules, F extends RedisFunctions, @@ -86,6 +95,20 @@ export function createCluster< }); } +/** + * Type definition for a Redis cluster client. + */ +export type RedisClusterType< + M extends RedisModules = RedisDefaultModules, + F extends RedisFunctions = {}, + S extends RedisScripts = {}, + RESP extends RespVersions = 2, + TYPE_MAPPING extends TypeMapping = {} +> = genericRedisClusterType; + +/** + * Type definition for a Redis Sentinel client. + */ export type RedisSentinelType< M extends RedisModules = RedisDefaultModules, F extends RedisFunctions = {}, @@ -94,6 +117,11 @@ export type RedisSentinelType< TYPE_MAPPING extends TypeMapping = {} > = genericRedisSentinelType; +/** + * Creates a new Redis Sentinel client. + * @param options - Configuration options for the Redis Sentinel client + * @returns A new Redis Sentinel client instance + */ export function createSentinel< M extends RedisModules, F extends RedisFunctions,