feat(multi-db): WIP MultiDbClient wrapper sketch

Sketch of a multi-database client wrapper managing a homogeneous array of
underlying clients (standalone/pool/cluster/sentinel) behind one drop-in
client surface. Type mechanics only — failover/health/routing stubbed.

- @redis/client: dedicated factories (createMultiDbClient/Pool/Cluster/
  Sentinel) returning { client, controller }; client typed exactly as the
  base client (true drop-in), controller holds multi-db-only admin surface.
  Command forwarding via prototype-walk (no runtime Proxy on hot path).
- redis meta-package: createMultiDbClient wrapper injecting default Stack
  modules, mirroring createClient.
- playground.ts for manual poking.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nkaradzhov

packages/client/index.ts

@@ -60,3 +60,13 @@ export {
   type CommandReplyEvent,
   type PoolConnectionWaitEvent,
 } from './lib/client/tracing';
+
+export {
+  createMultiDbClient,
+  createMultiDbClientPool,
+  createMultiDbCluster,
+  createMultiDbSentinel,
+  MultiDbController,
+  type MultiDbResult,
+  type AnyRedisClientType
+} from './lib/multi-db';

packages/client/lib/multi-db/index.ts

@@ -0,0 +1,248 @@
+import { EventEmitter } from 'node:events';
+import RedisClient, { RedisClientType, RedisClientOptions } from '../client';
+import { RedisClientPool, RedisClientPoolType, RedisPoolOptions } from '../client/pool';
+import RedisCluster, { RedisClusterType, RedisClusterOptions } from '../cluster';
+import RedisSentinel from '../sentinel';
+import { RedisSentinelType, RedisSentinelOptions } from '../sentinel/types';
+import { RedisModules, RedisFunctions, RedisScripts, RespVersions, TypeMapping } from '../RESP/types';
+
+/**
+ * SKETCH — type mechanics only. No failover / health / routing logic yet.
+ *
+ * Each factory returns `{ client, controller }`:
+ *
+ *   - `client`    — typed EXACTLY as the underlying client (`RedisClientType`,
+ *                   `RedisClusterType`, ...). A true drop-in: any code/type that
+ *                   expects the base client accepts it unchanged. Its command
+ *                   methods forward to the active DB; its `connect`/`close`/
+ *                   `destroy`/`quit` are intercepted to fan out across all DBs.
+ *   - `controller`— the multi-db-only surface (topology, weights, active-DB
+ *                   selection, failover events). Kept OFF `client` so `client`
+ *                   stays exactly the base type.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Types                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Every client shape the multi-db layer can wrap. */
+export type AnyRedisClientType =
+  | RedisClientType<any, any, any, any, any>
+  | RedisClientPoolType<any, any, any, any, any>
+  | RedisClusterType<any, any, any, any, any>
+  | RedisSentinelType<any, any, any, any, any>;
+
+/** Lifecycle members the multi-db layer intercepts (fan-out) rather than forwarding to one DB. */
+const INTERCEPTED = new Set<PropertyKey>(['connect', 'close', 'destroy', 'quit']);
+
+export interface MultiDbResult<C extends AnyRedisClientType> {
+  /** drop-in: exactly the base client type */
+  client: C;
+  /** multi-db admin surface */
+  controller: MultiDbController<C>;
+}
+
+interface DatabaseConfig<OPTIONS> {
+  options: OPTIONS;
+  /** highest healthy weight = active DB */
+  weight?: number;
+}
+
+interface PoolDatabaseConfig<OPTIONS> extends DatabaseConfig<OPTIONS> {
+  poolOptions?: Partial<RedisPoolOptions>;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Manager — owns the underlying clients + active selection                   */
+/* -------------------------------------------------------------------------- */
+
+class MultiDbManager<C extends AnyRedisClientType> {
+  readonly clients: ReadonlyArray<C>;
+  active: C;
+
+  constructor(clients: Array<C>) {
+    this.clients = clients;
+    this.active = clients[0]; // failover selection stubbed
+  }
+
+  async connect(): Promise<void> {
+    await Promise.all(this.clients.map(c => c.connect()));
+  }
+
+  async close(): Promise<void> {
+    await Promise.all(this.clients.map(c => c.close()));
+  }
+
+  destroy(): void {
+    for (const c of this.clients) c.destroy();
+  }
+
+  async quit(): Promise<void> {
+    // no per-DB quit fan-out subtleties for the sketch; treat like close
+    await this.close();
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* client — the drop-in surface (typed exactly as C)                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Lifecycle base. `connect`/`close`/`destroy`/`quit` are real methods (fan-out),
+ * NOT forwarded to one DB. Everything else is patched on by `attachForwarders`.
+ */
+class MultiDbClientBase<C extends AnyRedisClientType> {
+  /** @internal read by the forwarders patched below */
+  readonly _mgr: MultiDbManager<C>;
+
+  constructor(mgr: MultiDbManager<C>) {
+    this._mgr = mgr;
+  }
+
+  connect() {
+    return this._mgr.connect().then(() => this);
+  }
+
+  close() {
+    return this._mgr.close();
+  }
+
+  destroy() {
+    this._mgr.destroy();
+  }
+
+  quit() {
+    return this._mgr.quit();
+  }
+}
+
+/**
+ * Patch command methods + module/function namespaces onto `target`, forwarding
+ * each to the ACTIVE DB. Same shape as `attachConfig` — real (own) properties,
+ * no runtime trap — but discovered by walking a representative built client's
+ * prototype chain instead of a command registry (kind-agnostic; avoids
+ * importing each kind's registry + private executor). Runs ONCE at construction;
+ * the closures read `mgr.active` at CALL time, so the method SET is fixed
+ * (homogeneous DBs) while the TARGET tracks failover.
+ */
+function attachForwarders<C extends AnyRedisClientType>(
+  target: MultiDbClientBase<C>,
+  mgr: MultiDbManager<C>
+): void {
+  const skip = new Set<PropertyKey>([...INTERCEPTED, 'constructor']);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic patching
+  const dst = target as any;
+
+  for (let proto = Object.getPrototypeOf(mgr.active); proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (skip.has(name)) continue;
+      skip.add(name); // most-derived wins; don't reattach shadowed base members
+
+      const desc = Object.getOwnPropertyDescriptor(proto, name)!;
+      if (desc.get) {
+        // namespace (`json`, `ts`) or computed prop (`isOpen`) → read from active
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic
+        Object.defineProperty(dst, name, { get: () => (mgr.active as any)[name], enumerable: false });
+      } else if (typeof desc.value === 'function') {
+        // command / script method → call active's own method (this = active)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic
+        dst[name] = (...args: Array<unknown>) => (mgr.active as any)[name](...args);
+      }
+    }
+  }
+}
+
+function makeClient<C extends AnyRedisClientType>(mgr: MultiDbManager<C>): C {
+  const client = new MultiDbClientBase(mgr);
+  attachForwarders(client, mgr);
+  return client as unknown as C;
+}
+
+/* -------------------------------------------------------------------------- */
+/* controller — multi-db-only surface (all stubbed)                           */
+/* -------------------------------------------------------------------------- */
+
+export class MultiDbController<C extends AnyRedisClientType> extends EventEmitter {
+  #mgr: MultiDbManager<C>;
+
+  /** @internal */
+  constructor(mgr: MultiDbManager<C>) {
+    super();
+    this.#mgr = mgr;
+  }
+
+  /** the DB currently receiving commands */
+  getActiveDatabase(): C {
+    return this.#mgr.active;
+  }
+
+  /** all managed DBs, in config order */
+  getDatabases(): ReadonlyArray<C> {
+    return this.#mgr.clients;
+  }
+
+  /** force the active DB (TODO: validate index, emit 'failover') */
+  setActiveDatabase(index: number): void {
+    this.#mgr.active = this.#mgr.clients[index];
+  }
+
+  // TODO: setWeight, addDatabase, removeDatabase, health inspection,
+  //       'failover' / 'database-down' events.
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dedicated factories                                                        */
+/* -------------------------------------------------------------------------- */
+
+function assemble<C extends AnyRedisClientType>(clients: Array<C>): MultiDbResult<C> {
+  const mgr = new MultiDbManager(clients);
+  return { client: makeClient(mgr), controller: new MultiDbController(mgr) };
+}
+
+export function createMultiDbClient<
+  M extends RedisModules = {},
+  F extends RedisFunctions = {},
+  S extends RedisScripts = {},
+  RESP extends RespVersions = 3,
+  T extends TypeMapping = {}
+>(options: {
+  databases: Array<DatabaseConfig<RedisClientOptions<M, F, S, RESP, T>>>;
+}): MultiDbResult<RedisClientType<M, F, S, RESP, T>> {
+  return assemble(options.databases.map(db => RedisClient.create(db.options)));
+}
+
+export function createMultiDbClientPool<
+  M extends RedisModules = {},
+  F extends RedisFunctions = {},
+  S extends RedisScripts = {},
+  RESP extends RespVersions = 3,
+  T extends TypeMapping = {}
+>(options: {
+  databases: Array<PoolDatabaseConfig<RedisClientOptions<M, F, S, RESP, T>>>;
+}): MultiDbResult<RedisClientPoolType<M, F, S, RESP, T>> {
+  return assemble(options.databases.map(db => RedisClientPool.create(db.options, db.poolOptions)));
+}
+
+export function createMultiDbCluster<
+  M extends RedisModules = {},
+  F extends RedisFunctions = {},
+  S extends RedisScripts = {},
+  RESP extends RespVersions = 3,
+  T extends TypeMapping = {}
+>(options: {
+  databases: Array<DatabaseConfig<RedisClusterOptions<M, F, S, RESP, T>>>;
+}): MultiDbResult<RedisClusterType<M, F, S, RESP, T>> {
+  return assemble(options.databases.map(db => RedisCluster.create(db.options)));
+}
+
+export function createMultiDbSentinel<
+  M extends RedisModules = {},
+  F extends RedisFunctions = {},
+  S extends RedisScripts = {},
+  RESP extends RespVersions = 3,
+  T extends TypeMapping = {}
+>(options: {
+  databases: Array<DatabaseConfig<RedisSentinelOptions<M, F, S, RESP, T>>>;
+}): MultiDbResult<RedisSentinelType<M, F, S, RESP, T>> {
+  return assemble(options.databases.map(db => RedisSentinel.create(db.options)));
+}

packages/redis/index.ts

@@ -16,6 +16,8 @@ import {
   createClientPool as genericCreateClientPool,
   RedisClientPoolType as GenericRedisClientPoolType,
   RedisPoolOptions,
+  createMultiDbClient as genericCreateMultiDbClient,
+  MultiDbResult,
 } from '@redis/client';
 import RedisBloomModules from '@redis/bloom';
 import RedisJSON from '@redis/json';
@@ -64,6 +66,37 @@ export function createClient<
   }) as RedisClientType<M, F, S, RESP, TYPE_MAPPING>;
 }
 
+/**
+ * Multi-database client with the Redis Stack default modules pre-registered
+ * (mirrors {@link createClient}). Returns `{ client, controller }`; `client`
+ * is a drop-in {@link RedisClientType}.
+ */
+export function createMultiDbClient<
+  M extends RedisModules = {},
+  F extends RedisFunctions = {},
+  S extends RedisScripts = {},
+  RESP extends RespVersions = 3,
+  TYPE_MAPPING extends TypeMapping = {}
+>(options: {
+  databases: Array<{
+    options: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>;
+    weight?: number;
+  }>;
+}): MultiDbResult<RedisClientType<M, F, S, RESP, TYPE_MAPPING>> {
+  return genericCreateMultiDbClient({
+    databases: options.databases.map(db => ({
+      ...db,
+      options: {
+        ...db.options,
+        modules: {
+          ...modules,
+          ...(db.options?.modules as M)
+        }
+      }
+    }))
+  }) as unknown as MultiDbResult<RedisClientType<M, F, S, RESP, TYPE_MAPPING>>;
+}
+
 export function createClientPool<
   M extends RedisModules = {},
   F extends RedisFunctions = {},

packages/redis/playground.ts

@@ -0,0 +1,35 @@
+// Simple playground for MultiDbClient (meta package — default modules included).
+// Run:
+//   npx tsx packages/redis/playground.ts
+// Needs a Redis on 127.0.0.1:3000 (Redis 8+ ships json/ft/ts builtin).
+
+import { createMultiDbClient } from './index';
+
+async function main() {
+  // two logical DBs on the same server so routing is easy to see
+  const { client, controller } = createMultiDbClient({
+    databases: [
+      { options: { url: 'redis://127.0.0.1:3000/0' }, weight: 100 },
+      { options: { url: 'redis://127.0.0.1:3000/1' }, weight: 50 }
+    ]
+  });
+
+  await client.connect();
+
+  // plain commands — go to the active DB (db0)
+  await client.set('hello', 'world');
+  console.log('db0 hello =', await client.get('hello'));
+
+  // default modules autocomplete: client.json / client.ft / client.ts
+  await client.json.set('doc', '$', { a: 1 });
+  console.log('db0 json.get =', JSON.stringify(await client.json.get('doc')));
+
+  // switch active DB (stand-in for failover)
+  controller.setActiveDatabase(1);
+  console.log('db1 hello =', await client.get('hello')); // null — different DB
+
+  controller.setActiveDatabase(0);
+  await client.close();
+}
+
+main();