@objectstack/service-cluster-redis 5.1.1

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-cluster-redis/dist/index.cjs","../src/index.ts","../src/client.ts","../src/pubsub.ts","../src/lock.ts","../src/kv.ts","../src/counter.ts"],"names":[],"mappings":"AAAA;ACwBA;AACI;AACA;AAAA,8DAEG;ADvBP;AACA;AEJA,kCAAyC;AAkDlC,SAAS,iBAAA,CAAkB,KAAA,EAA2B,CAAC,CAAA,EAAU;AACpE,EAAA,GAAA,CAAI,IAAA,CAAK,QAAA,EAAU,OAAO,IAAA,CAAK,QAAA;AAE/B,EAAA,MAAM,KAAA,EAAqB;AAAA,IACvB,WAAA,mBAAa,IAAA,CAAK,WAAA,UAAe,MAAA;AAAA,IACjC,oBAAA,EAAsB,CAAA;AAAA,IACtB,oBAAA,EAAsB;AAAA,EAC1B,CAAA;AAEA,EAAA,GAAA,CAAI,IAAA,CAAK,GAAA,EAAK;AACV,IAAA,OAAO,IAAI,mBAAA,CAAM,IAAA,CAAK,GAAA,EAAK,EAAE,GAAG,IAAA,EAAM,GAAG,IAAA,CAAK,QAAQ,CAAC,CAAA;AAAA,EAC3D;AACA,EAAA,OAAO,IAAI,mBAAA,CAAM,EAAE,GAAG,IAAA,EAAM,GAAG,IAAA,CAAK,QAAQ,CAAC,CAAA;AACjD;AAOO,SAAS,kBAAA,CAAmB,MAAA,EAAsB;AACrD,EAAA,OAAO,MAAA,CAAO,SAAA,CAAU,CAAA;AAC5B;AFnDA;AACA;AG2BO,IAAM,YAAA,EAAN,MAAqC;AAAA,EASxC,WAAA,CAAY,IAAA,EAA0B;AAHtC,IAAA,IAAA,CAAiB,KAAA,kBAAO,IAAI,GAAA,CAAyC,CAAA;AACrE,IAAA,IAAA,CAAQ,OAAA,EAAS,KAAA;AAGb,IAAA,IAAA,CAAK,UAAA,EAAY,IAAA,CAAK,MAAA;AACtB,IAAA,IAAA,CAAK,WAAA,EAAa,kBAAA,CAAmB,IAAA,CAAK,MAAM,CAAA;AAChD,IAAA,IAAA,CAAK,OAAA,EAAS,IAAA,CAAK,MAAA;AACnB,IAAA,IAAA,CAAK,UAAA,mBAAY,IAAA,CAAK,SAAA,UAAa,OAAA;AACnC,IAAA,IAAA,CAAK,QAAA,mBACD,IAAA,CAAK,OAAA,UAAA,CACJ,CAAC,GAAA,EAAK,OAAA,EAAA,GAAY;AAEf,MAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,gCAAA,EAAmC,OAAO,CAAA,EAAA,CAAA,EAAM,GAAG,CAAA;AAAA,IACrE,CAAA,GAAA;AAEJ,IAAA,IAAA,CAAK,UAAA,CAAW,EAAA,CAAG,SAAA,EAAW,CAAC,GAAA,EAAa,IAAA,EAAA,GAAiB;AACzD,MAAA,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,IAAI,CAAA;AAAA,IAC3B,CAAC,CAAA;AAAA,EACL;AAAA,EAEA,MAAM,OAAA,CACF,OAAA,EACA,OAAA,EACA,KAAA,EACa;AACb,IAAA,GAAA,CAAI,IAAA,CAAK,MAAA,EAAQ,MAAM,IAAI,KAAA,CAAM,uBAAuB,CAAA;AACxD,IAAA,MAAM,SAAA,EAAgC;AAAA,MAClC,CAAA,EAAG,IAAA,CAAK,MAAA;AAAA,MACR,CAAA,EAAG,IAAA,CAAK,GAAA,CAAI,CAAA;AAAA,MACZ,CAAA,EAAG;AAAA,IACP,CAAA;AACA,IAAA,MAAM,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,IAAA,CAAK,QAAA,CAAS,OAAO,CAAA,EAAG,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA;AAAA,EACjF;AAAA,EAEA,SAAA,CACI,OAAA,EACA,OAAA,EACA,KAAA,EACW;AACX,IAAA,GAAA,CAAI,IAAA,CAAK,MAAA,EAAQ,MAAM,IAAI,KAAA,CAAM,uBAAuB,CAAA;AACxD,IAAA,MAAM,SAAA,EAAW,IAAA,CAAK,QAAA,CAAS,OAAO,CAAA;AACtC,IAAA,IAAI,OAAA,EAAS,IAAA,CAAK,IAAA,CAAK,GAAA,CAAI,QAAQ,CAAA;AACnC,IAAA,GAAA,CAAI,CAAC,MAAA,EAAQ;AACT,MAAA,OAAA,kBAAS,IAAI,GAAA,CAAI,CAAA;AACjB,MAAA,IAAA,CAAK,IAAA,CAAK,GAAA,CAAI,QAAA,EAAU,MAAM,CAAA;AAG9B,MAAA,KAAK,IAAA,CAAK,UAAA,CAAW,SAAA,CAAU,QAAQ,CAAA,CAAE,KAAA,CAAM,CAAC,GAAA,EAAA,GAAQ;AACpD,QAAA,IAAA,CAAK,OAAA,CAAQ,GAAA,EAAK,OAAO,CAAA;AAAA,MAC7B,CAAC,CAAA;AAAA,IACL;AACA,IAAA,MAAM,QAAA,EAAU,OAAA;AAChB,IAAA,MAAA,CAAO,GAAA,CAAI,OAAO,CAAA;AAElB,IAAA,IAAI,SAAA,EAAW,KAAA;AACf,IAAA,OAAO,CAAA,EAAA,GAAM;AACT,MAAA,GAAA,CAAI,QAAA,EAAU,MAAA;AACd,MAAA,SAAA,EAAW,IAAA;AACX,MAAA,MAAM,EAAA,EAAI,IAAA,CAAK,IAAA,CAAK,GAAA,CAAI,QAAQ,CAAA;AAChC,MAAA,GAAA,CAAI,CAAC,CAAA,EAAG,MAAA;AACR,MAAA,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA;AAChB,MAAA,GAAA,CAAI,CAAA,CAAE,KAAA,IAAS,CAAA,EAAG;AACd,QAAA,IAAA,CAAK,IAAA,CAAK,MAAA,CAAO,QAAQ,CAAA;AACzB,QAAA,KAAK,IAAA,CAAK,UAAA,CAAW,WAAA,CAAY,QAAQ,CAAA,CAAE,KAAA,CAAM,CAAA,EAAA,GAAM;AAAA,QAAgB,CAAC,CAAA;AAAA,MAC5E;AAAA,IACJ,CAAA;AAAA,EACJ;AAAA,EAEA,MAAM,KAAA,CAAA,EAAuB;AACzB,IAAA,GAAA,CAAI,IAAA,CAAK,MAAA,EAAQ,MAAA;AACjB,IAAA,IAAA,CAAK,OAAA,EAAS,IAAA;AACd,IAAA,IAAA,CAAK,IAAA,CAAK,KAAA,CAAM,CAAA;AAChB,IAAA,IAAI;AAAE,MAAA,MAAM,IAAA,CAAK,UAAA,CAAW,IAAA,CAAK,CAAA;AAAA,IAAG,EAAA,UAAQ;AAAA,IAAgB;AAAA,EAEhE;AAAA,EAEQ,QAAA,CAAS,OAAA,EAAyB;AACtC,IAAA,OAAO,CAAA,EAAA;AACX,EAAA;AAEiB,EAAA;AACP,IAAA;AACD,IAAA;AAED,IAAA;AACA,IAAA;AACA,MAAA;AACJ,IAAA;AACS,MAAA;AACL,MAAA;AACJ,IAAA;AAGM,IAAA;AAIA,IAAA;AACN,IAAA;AACQ,MAAA;AACA,QAAA;AACI,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACH,QAAA;AACG,QAAA;AACC,UAAA;AAA+B,YAAA;AAEhC,UAAA;AACJ,QAAA;AACJ,MAAA;AACI,QAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AACJ;AHtDY;AACA;AI/GN;AACA;AAOA;AAAiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAYjB;AAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAmCR;AAQT,EAAA;AAFQ,IAAA;AAGC,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACT,EAAA;AAEM,EAAA;AACE,IAAA;AACE,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AAGA,IAAA;AACI,MAAA;AACV,IAAA;AACM,IAAA;AAGF,IAAA;AACA,MAAA;AACJ,IAAA;AACI,IAAA;AAIG,IAAA;AACG,MAAA;AACF,MAAA;AACA,QAAA;AACJ,MAAA;AACJ,IAAA;AACO,IAAA;AACX,EAAA;AAEM,EAAA;AAKI,IAAA;AACD,IAAA;AACD,IAAA;AACA,MAAA;AACJ,IAAA;AACU,MAAA;AACV,IAAA;AACJ,EAAA;AAEM,EAAA;AACG,IAAA;AACT,EAAA;AAEc,EAAA;AAEJ,IAAA;AACC,IAAA;AACX,EAAA;AAEQ,EAAA;AAOE,IAAA;AACF,IAAA;AACA,IAAA;AAIA,IAAA;AACA,MAAA;AACI,IAAA;AAED,IAAA;AACE,MAAA;AACL,MAAA;AACA,MAAA;AACI,QAAA;AACJ,MAAA;AACM,MAAA;AACE,QAAA;AACA,UAAA;AACJ,QAAA;AACA,QAAA;AACA,QAAA;AACI,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACJ,QAAA;AACI,QAAA;AACA,UAAA;AACA,UAAA;AAAa,YAAA;AAAqB,YAAA;AAAmB,UAAA;AACrD,UAAA;AACI,YAAA;AACJ,UAAA;AACJ,QAAA;AACA,QAAA;AACI,QAAA;AACJ,QAAA;AAA2B,UAAA;AAAoB,QAAA;AACnD,MAAA;AACM,MAAA;AACE,QAAA;AACJ,QAAA;AACI,QAAA;AAAS,UAAA;AAAqB,UAAA;AAAmB,QAAA;AACjD,QAAA;AACA,UAAA;AACJ,QAAA;AAEA,QAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AAEgB,EAAA;AACL,IAAA;AACX,EAAA;AAEiB,EAAA;AACN,IAAA;AACX,EAAA;AACJ;AAES;AACE,EAAA;AACX;AJ6CY;AACA;AK3OC;AACT,EAAA;AAKI,IAAA;AACI,MAAA;AACJ,IAAA;AANgB,IAAA;AACA,IAAA;AACA,IAAA;AAKX,IAAA;AACT,EAAA;AACJ;AAuBa;AAKT,EAAA;AAFQ,IAAA;AAGC,IAAA;AACA,IAAA;AACT,EAAA;AAEuB,EAAA;AACb,IAAA;AACF,IAAA;AACE,IAAA;AACD,IAAA;AACC,IAAA;AACA,IAAA;AACC,IAAA;AACH,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACJ,IAAA;AACJ,EAAA;AAGI,EAAA;AAII,IAAA;AACE,IAAA;AACA,IAAA;AAKC,IAAA;AACG,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AAEF,MAAA;AACA,QAAA;AACA,QAAA;AACJ,MAAA;AAEM,MAAA;AACA,MAAA;AACA,MAAA;AAEA,MAAA;AACF,MAAA;AACA,QAAA;AACJ,MAAA;AACI,QAAA;AACJ,MAAA;AACM,MAAA;AAEF,MAAA;AAEJ,MAAA;AACI,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AAEM,EAAA;AACE,IAAA;AACE,IAAA;AAEF,IAAA;AACM,MAAA;AACN,MAAA;AACJ,IAAA;AAGO,IAAA;AACG,MAAA;AACA,MAAA;AACD,MAAA;AACD,QAAA;AACA,QAAA;AACJ,MAAA;AACM,MAAA;AACD,MAAA;AACD,QAAA;AACA,QAAA;AACJ,MAAA;AACM,MAAA;AACF,MAAA;AACA,QAAA;AACA,QAAA;AACJ,MAAA;AACM,MAAA;AACA,MAAA;AACA,MAAA;AACF,MAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AAGI,EAAA;AAKI,IAAA;AACA,MAAA;AACJ,IAAA;AACQ,MAAA;AACE,MAAA;AACV,IAAA;AACJ,EAAA;AAEM,EAAA;AACG,IAAA;AACT,EAAA;AAEc,EAAA;AACH,IAAA;AACX,EAAA;AAEc,EAAA;AACN,IAAA;AACM,MAAA;AACF,MAAA;AACJ,MAAA;AACI,IAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AACJ;ALuLY;AACA;AM/VC;AAKT,EAAA;AAFQ,IAAA;AAGC,IAAA;AACA,IAAA;AACT,EAAA;AAEM,EAAA;AACE,IAAA;AACE,IAAA;AACA,IAAA;AACC,IAAA;AACX,EAAA;AAEM,EAAA;AACI,IAAA;AACF,IAAA;AACA,IAAA;AACA,MAAA;AACI,IAAA;AACJ,MAAA;AACJ,IAAA;AACJ,EAAA;AAEM,EAAA;AACE,IAAA;AACA,IAAA;AACM,MAAA;AACN,MAAA;AACJ,IAAA;AACM,IAAA;AACV,EAAA;AAEM,EAAA;AACG,IAAA;AACT,EAAA;AAEe,EAAA;AACJ,IAAA;AACX,EAAA;AACJ;ANyVY;AACA;ACzVH;AACC,EAAA;AACA,EAAA;AACA,EAAA;AAIA,EAAA;AACA,EAAA;AAEA,EAAA;AACF,IAAA;AACQ,IAAA;AACR,IAAA;AACA,IAAA;AACH,EAAA;AACK,EAAA;AACF,IAAA;AACA,IAAA;AACA,IAAA;AACQ,IAAA;AACX,EAAA;AACK,EAAA;AACA,EAAA;AAEA,EAAA;AACK,IAAA;AACP,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACJ,EAAA;AAGM,EAAA;AACC,EAAA;AACG,IAAA;AACF,IAAA;AACI,MAAA;AAAE,QAAA;AAAqB,MAAA;AAAwB,MAAA;AACvD,IAAA;AACJ,EAAA;AAEO,EAAA;AACX;AAGA;ADoVY;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","file":"/home/runner/work/framework/framework/packages/services/service-cluster-redis/dist/index.cjs","sourcesContent":[null,"// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/service-cluster-redis\n *\n * Redis driver for `@objectstack/service-cluster`. Import this package\n * once at process start to register the `'redis'` driver:\n *\n * ```ts\n * import '@objectstack/service-cluster-redis';\n * import { defineCluster } from '@objectstack/service-cluster';\n *\n * const cluster = defineCluster({\n *     driver: 'redis',\n *     url: 'redis://localhost:6379',\n *     nodeId: 'web-1',\n * });\n * ```\n *\n * The driver also exports raw constructors so callers who already own\n * an ioredis client can compose primitives by hand.\n */\n\nimport type { Redis } from 'ioredis';\nimport {\n    ComposedClusterService,\n    registerClusterDriver,\n    type DriverFactoryConfig,\n} from '@objectstack/service-cluster';\nimport { createRedisClient } from './client.js';\nimport { RedisPubSub } from './pubsub.js';\nimport { RedisLock } from './lock.js';\nimport { RedisKV } from './kv.js';\nimport { RedisCounter } from './counter.js';\n\n// Re-exports for advanced composition.\nexport { createRedisClient, duplicateForPubSub, type CreateRedisOptions } from './client.js';\nexport { RedisPubSub, type RedisPubSubOptions } from './pubsub.js';\nexport { RedisLock, type RedisLockOptions } from './lock.js';\nexport { RedisKV, VersionMismatchError, type RedisKVOptions } from './kv.js';\nexport { RedisCounter, type RedisCounterOptions } from './counter.js';\n\n/**\n * Driver-specific options accepted under `driverOptions` in\n * `ClusterCapabilityConfig`. All are optional — supply a `client` to\n * share a Redis pool with other services (e.g. `service-cache`).\n */\nexport interface RedisDriverOptions {\n    /** Pre-built ioredis client. When provided, `url` is ignored. */\n    client?: Redis;\n    /** Key prefix applied to every Redis key (default: 'os:'). */\n    keyPrefix?: string;\n    /** Default lock TTL in ms. Overridden by `LockAcquireOptions.ttlMs`. */\n    lockTtlMs?: number;\n    /** Pub/sub subscriber error sink. */\n    onError?: (err: unknown, channel: string) => void;\n}\n\n/**\n * Factory consumed by `defineCluster({ driver: 'redis' })`. Builds an\n * `IClusterService` backed by Redis. Owns the underlying ioredis client\n * iff it created it (i.e. when caller didn't pass `driverOptions.client`).\n */\nfunction redisDriverFactory(config: DriverFactoryConfig) {\n    const driverOpts = (config.driverOptions ?? {}) as RedisDriverOptions;\n    const ownsClient = !driverOpts.client;\n    const client =\n        driverOpts.client ??\n        createRedisClient({ url: config.url });\n\n    const keyPrefix = driverOpts.keyPrefix ?? 'os:';\n    const ttlMs = config.lockTtlMs ?? driverOpts.lockTtlMs;\n\n    const pubsub = new RedisPubSub({\n        client,\n        nodeId: config.nodeId,\n        keyPrefix,\n        onError: driverOpts.onError,\n    });\n    const lock = new RedisLock({\n        client,\n        keyPrefix,\n        defaultTtlMs: ttlMs,\n        nodeId: config.nodeId,\n    });\n    const kv = new RedisKV({ client, keyPrefix });\n    const counter = new RedisCounter({ client, keyPrefix });\n\n    const facade = new ComposedClusterService(\n        config.nodeId,\n        'redis',\n        pubsub,\n        lock,\n        kv,\n        counter,\n    );\n\n    // Wrap close() so we also tear down the publisher client if we own it.\n    const originalClose = facade.close.bind(facade);\n    facade.close = async () => {\n        await originalClose();\n        if (ownsClient) {\n            try { await client.quit(); } catch { /* swallow */ }\n        }\n    };\n\n    return facade;\n}\n\n// Module-load registration — importing this package is enough.\nregisterClusterDriver('redis', redisDriverFactory);\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { Redis, type RedisOptions } from 'ioredis';\n\n/**\n * Options accepted by {@link createRedisClient}.\n *\n * Either pass `url` (e.g. `redis://user:pass@host:6379/0`) or a full\n * ioredis `options` bag. The two are merged with `options` taking\n * precedence so callers can override individual fields parsed from the\n * URL.\n *\n * This factory is intended to be the single Redis-client construction\n * point across ObjectStack — `service-cluster-redis` uses it for the\n * driver, and `service-cache` will eventually share the same connection\n * pool via {@link CreateRedisOptions.existing}.\n */\nexport interface CreateRedisOptions {\n    /** Connection URL. Ignored when `existing` is provided. */\n    url?: string;\n    /** Extra ioredis options merged on top of `url`. */\n    options?: RedisOptions;\n    /**\n     * Bring-your-own client. When provided, this exact instance is\n     * returned and `url`/`options` are ignored — useful for sharing one\n     * pool across cluster + cache.\n     */\n    existing?: Redis;\n    /**\n     * If true, the returned client is created in lazyConnect mode so the\n     * TCP connection happens on first command rather than at construction.\n     * Default: true (matches ObjectStack's \"fail at usage, not boot\" stance).\n     */\n    lazyConnect?: boolean;\n}\n\n/**\n * Construct (or reuse) an ioredis client with ObjectStack defaults.\n *\n * Defaults applied when `existing` is absent:\n *   - `lazyConnect: true` — don't crash boot if Redis is briefly down\n *   - `maxRetriesPerRequest: 3` — bound the failure window before surfacing\n *   - `enableAutoPipelining: true` — modest throughput boost for batch workloads\n *\n * @example\n *   const client = createRedisClient({ url: 'redis://localhost:6379' });\n *\n * @example reuse one pool across services\n *   const shared = createRedisClient({ url });\n *   const clusterClient = createRedisClient({ existing: shared });\n *   const cacheClient   = createRedisClient({ existing: shared });\n */\nexport function createRedisClient(opts: CreateRedisOptions = {}): Redis {\n    if (opts.existing) return opts.existing;\n\n    const base: RedisOptions = {\n        lazyConnect: opts.lazyConnect ?? true,\n        maxRetriesPerRequest: 3,\n        enableAutoPipelining: true,\n    };\n\n    if (opts.url) {\n        return new Redis(opts.url, { ...base, ...opts.options });\n    }\n    return new Redis({ ...base, ...opts.options });\n}\n\n/**\n * Duplicate a Redis client so that pub/sub commands (which monopolize\n * the connection) don't block regular commands. Mirrors the standard\n * ioredis \"two clients\" pattern.\n */\nexport function duplicateForPubSub(client: Redis): Redis {\n    return client.duplicate();\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Redis } from 'ioredis';\nimport type {\n    IPubSub,\n    PubSubHandler,\n    PublishOptions,\n    SubscribeOptions,\n    Unsubscribe,\n} from '@objectstack/spec/contracts';\nimport { duplicateForPubSub } from './client.js';\n\n/**\n * Wire-format envelope sent over Redis. Adds `fromNode` and\n * `publishedAt` so subscribers see the same surface as the memory\n * driver. The user payload is nested under `p` to avoid colliding with\n * reserved keys.\n */\ninterface RedisPubSubEnvelope {\n    n?: string;\n    t: number;\n    p: unknown;\n}\n\nexport interface RedisPubSubOptions {\n    /** Already-connected client used for PUBLISH. */\n    client: Redis;\n    /** Optional node id surfaced as `fromNode` on every delivered message. */\n    nodeId?: string;\n    /** Key namespace prefix applied to every channel (default: 'os:'). */\n    keyPrefix?: string;\n    /** Error sink for subscriber handler exceptions. */\n    onError?: (err: unknown, channel: string) => void;\n}\n\n/**\n * Redis pub/sub implementation of {@link IPubSub}.\n *\n * Uses two ioredis clients under the hood:\n *   - `publisher` (caller-provided) — runs PUBLISH commands\n *   - `subscriber` (auto-duplicated) — held in subscribe mode, can't run\n *     regular commands per Redis protocol\n *\n * Delivery semantics match Redis pub/sub: at-most-once, fire-and-forget,\n * no persistence. For at-least-once + replay use the planned `streams`\n * adapter (separate driver).\n *\n * Channel names are prefixed with `keyPrefix` before being sent to\n * Redis, so the same Redis instance can host multiple isolated\n * ObjectStack deployments.\n */\nexport class RedisPubSub implements IPubSub {\n    private readonly publisher: Redis;\n    private readonly subscriber: Redis;\n    private readonly nodeId?: string;\n    private readonly keyPrefix: string;\n    private readonly onError: (err: unknown, channel: string) => void;\n    private readonly subs = new Map<string, Set<PubSubHandler<unknown>>>();\n    private closed = false;\n\n    constructor(opts: RedisPubSubOptions) {\n        this.publisher = opts.client;\n        this.subscriber = duplicateForPubSub(opts.client);\n        this.nodeId = opts.nodeId;\n        this.keyPrefix = opts.keyPrefix ?? 'os:';\n        this.onError =\n            opts.onError ??\n            ((err, channel) => {\n                // eslint-disable-next-line no-console\n                console.error(`[RedisPubSub] handler error on \"${channel}\":`, err);\n            });\n\n        this.subscriber.on('message', (raw: string, data: string) => {\n            this.dispatch(raw, data);\n        });\n    }\n\n    async publish<T = unknown>(\n        channel: string,\n        payload: T,\n        _opts?: PublishOptions,\n    ): Promise<void> {\n        if (this.closed) throw new Error('RedisPubSub is closed');\n        const envelope: RedisPubSubEnvelope = {\n            n: this.nodeId,\n            t: Date.now(),\n            p: payload,\n        };\n        await this.publisher.publish(this.prefixed(channel), JSON.stringify(envelope));\n    }\n\n    subscribe<T = unknown>(\n        channel: string,\n        handler: PubSubHandler<T>,\n        _opts?: SubscribeOptions,\n    ): Unsubscribe {\n        if (this.closed) throw new Error('RedisPubSub is closed');\n        const prefixed = this.prefixed(channel);\n        let bucket = this.subs.get(prefixed);\n        if (!bucket) {\n            bucket = new Set();\n            this.subs.set(prefixed, bucket);\n            // Fire-and-forget; if subscribe fails the next publish will\n            // simply not deliver — caller can resubscribe.\n            void this.subscriber.subscribe(prefixed).catch((err) => {\n                this.onError(err, channel);\n            });\n        }\n        const wrapped = handler as PubSubHandler<unknown>;\n        bucket.add(wrapped);\n\n        let disposed = false;\n        return () => {\n            if (disposed) return;\n            disposed = true;\n            const b = this.subs.get(prefixed);\n            if (!b) return;\n            b.delete(wrapped);\n            if (b.size === 0) {\n                this.subs.delete(prefixed);\n                void this.subscriber.unsubscribe(prefixed).catch(() => { /* swallow */ });\n            }\n        };\n    }\n\n    async close(): Promise<void> {\n        if (this.closed) return;\n        this.closed = true;\n        this.subs.clear();\n        try { await this.subscriber.quit(); } catch { /* swallow */ }\n        // We don't quit `publisher` — caller owns it.\n    }\n\n    private prefixed(channel: string): string {\n        return `${this.keyPrefix}ps:${channel}`;\n    }\n\n    private dispatch(prefixedChannel: string, data: string): void {\n        const bucket = this.subs.get(prefixedChannel);\n        if (!bucket || bucket.size === 0) return;\n\n        let envelope: RedisPubSubEnvelope;\n        try {\n            envelope = JSON.parse(data) as RedisPubSubEnvelope;\n        } catch (err) {\n            this.onError(err, prefixedChannel);\n            return;\n        }\n\n        // Strip our keyPrefix so the handler sees the logical channel.\n        const logical = prefixedChannel.startsWith(`${this.keyPrefix}ps:`)\n            ? prefixedChannel.slice(`${this.keyPrefix}ps:`.length)\n            : prefixedChannel;\n\n        const snapshot = Array.from(bucket);\n        for (const handler of snapshot) {\n            try {\n                const result = handler({\n                    channel: logical,\n                    payload: envelope.p,\n                    publishedAt: envelope.t,\n                    fromNode: envelope.n,\n                });\n                if (result && typeof (result as Promise<void>).then === 'function') {\n                    (result as Promise<void>).catch((err) =>\n                        this.onError(err, logical),\n                    );\n                }\n            } catch (err) {\n                this.onError(err, logical);\n            }\n        }\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Redis } from 'ioredis';\nimport type {\n    ILock,\n    LockAcquireOptions,\n    LockHandle,\n} from '@objectstack/spec/contracts';\n\nconst DEFAULT_TTL_MS = 15_000;\nconst POLL_INTERVAL_MS = 50;\n\n/**\n * Lua script for safe release: only DEL when the value matches our\n * fencing token. Prevents a delayed release from kicking out the\n * legitimate next holder.\n */\nconst RELEASE_SCRIPT = `\nif redis.call(\"GET\", KEYS[1]) == ARGV[1] then\n    return redis.call(\"DEL\", KEYS[1])\nelse\n    return 0\nend\n`;\n\n/**\n * Lua script for renew: PEXPIRE only when we still hold the lock.\n * Returns 1 on success, 0 if the lock was lost.\n */\nconst RENEW_SCRIPT = `\nif redis.call(\"GET\", KEYS[1]) == ARGV[1] then\n    return redis.call(\"PEXPIRE\", KEYS[1], ARGV[2])\nelse\n    return 0\nend\n`;\n\nexport interface RedisLockOptions {\n    client: Redis;\n    /** Counter client for fencing-token allocation. Same Redis is fine. */\n    counterClient?: Redis;\n    keyPrefix?: string;\n    defaultTtlMs?: number;\n    /** Stable node id baked into lock values for debugging. */\n    nodeId?: string;\n}\n\n/**\n * Redis-backed distributed lock with TTL fencing.\n *\n * Algorithm (single-instance Redis, NOT Redlock — adequate for\n * typical ObjectStack deployments with one Redis primary):\n *\n *   acquire = SET key {nodeId}:{token} NX PX ttl\n *   release = Lua: GET == expected ? DEL : 0\n *   renew   = Lua: GET == expected ? PEXPIRE : 0\n *\n * Fencing tokens come from a Redis counter (INCR on `{prefix}fence:{key}`)\n * so that two clients in a split-brain see strictly increasing tokens\n * downstream.\n *\n * For multi-master Redis (Sentinel failover, etc.) consider switching to\n * a Redlock variant — not implemented yet.\n */\nexport class RedisLock implements ILock {\n    private readonly client: Redis;\n    private readonly counterClient: Redis;\n    private readonly keyPrefix: string;\n    private readonly defaultTtlMs: number;\n    private readonly nodeId: string;\n    private closed = false;\n\n    constructor(opts: RedisLockOptions) {\n        this.client = opts.client;\n        this.counterClient = opts.counterClient ?? opts.client;\n        this.keyPrefix = opts.keyPrefix ?? 'os:';\n        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;\n        this.nodeId = opts.nodeId ?? 'node';\n    }\n\n    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {\n        if (this.closed) throw new Error('RedisLock is closed');\n        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;\n        const waitMs = opts.waitMs ?? 0;\n        const deadline = Date.now() + waitMs;\n        const lockKey = this.lockKey(key);\n\n        // Allocate a fresh fencing token up-front.\n        const fencingToken = BigInt(\n            await this.counterClient.incr(this.fenceKey(key)),\n        );\n        const value = `${this.nodeId}:${fencingToken}`;\n\n        // First attempt — fast path.\n        if (await this.trySet(lockKey, value, ttlMs)) {\n            return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);\n        }\n        if (waitMs <= 0) return null;\n\n        // Polling loop: simple, correct, good enough for typical\n        // contention. Future: pub/sub-driven wakeup on release.\n        while (Date.now() < deadline) {\n            await sleep(Math.min(POLL_INTERVAL_MS, Math.max(1, deadline - Date.now())));\n            if (await this.trySet(lockKey, value, ttlMs)) {\n                return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);\n            }\n        }\n        return null;\n    }\n\n    async withLock<T>(\n        key: string,\n        fn: (h: LockHandle) => Promise<T>,\n        opts?: LockAcquireOptions,\n    ): Promise<T | null> {\n        const handle = await this.acquire(key, opts);\n        if (!handle) return null;\n        try {\n            return await fn(handle);\n        } finally {\n            await handle.release();\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n    }\n\n    private async trySet(lockKey: string, value: string, ttlMs: number): Promise<boolean> {\n        // SET key value NX PX ttlMs — atomic acquire.\n        const res = await this.client.set(lockKey, value, 'PX', ttlMs, 'NX');\n        return res === 'OK';\n    }\n\n    private makeHandle(\n        logicalKey: string,\n        lockKey: string,\n        value: string,\n        fencingToken: bigint,\n        ttlMs: number,\n    ): LockHandle {\n        const self = this;\n        let released = false;\n        let currentTtl = ttlMs;\n        // Local expiry timer — mirrors memory driver so `isHeld()` flips\n        // on TTL without a Redis roundtrip. Not authoritative (clocks may\n        // drift), but matches contract test expectations.\n        let timer: NodeJS.Timeout | undefined = setTimeout(() => {\n            released = true;\n        }, ttlMs);\n\n        return {\n            key: logicalKey,\n            fencingToken,\n            isHeld(): boolean {\n                return !released;\n            },\n            async renew(extendMs?: number): Promise<void> {\n                if (released) {\n                    throw new Error(`Lock \"${logicalKey}\" already released`);\n                }\n                const next = extendMs ?? currentTtl;\n                const result = await self.client.eval(\n                    RENEW_SCRIPT,\n                    1,\n                    lockKey,\n                    value,\n                    String(next),\n                );\n                if (result !== 1) {\n                    released = true;\n                    if (timer) { clearTimeout(timer); timer = undefined; }\n                    throw new Error(\n                        `Lock \"${logicalKey}\" no longer held (fence=${fencingToken})`,\n                    );\n                }\n                currentTtl = next;\n                if (timer) clearTimeout(timer);\n                timer = setTimeout(() => { released = true; }, next);\n            },\n            async release(): Promise<void> {\n                if (released) return;\n                released = true;\n                if (timer) { clearTimeout(timer); timer = undefined; }\n                try {\n                    await self.client.eval(RELEASE_SCRIPT, 1, lockKey, value);\n                } catch {\n                    /* swallow — release is best-effort */\n                }\n            },\n        };\n    }\n\n    private lockKey(key: string): string {\n        return `${this.keyPrefix}lock:${key}`;\n    }\n\n    private fenceKey(key: string): string {\n        return `${this.keyPrefix}fence:${key}`;\n    }\n}\n\nfunction sleep(ms: number): Promise<void> {\n    return new Promise((r) => setTimeout(r, ms));\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Redis } from 'ioredis';\nimport type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';\n\n/**\n * Stored payload shape: `{v: <value>, ver: <bigint as string>}`.\n * Versions are stored as strings because Redis values are bytes and\n * bigints can exceed JSON-safe-integer range.\n */\ninterface StoredKV {\n    v: unknown;\n    ver: string;\n}\n\nexport class VersionMismatchError extends Error {\n    constructor(\n        public readonly key: string,\n        public readonly expected: bigint,\n        public readonly actual: bigint,\n    ) {\n        super(\n            `KV version mismatch on \"${key}\": expected v${expected}, found v${actual}`,\n        );\n        this.name = 'VersionMismatchError';\n    }\n}\n\nexport interface RedisKVOptions {\n    client: Redis;\n    keyPrefix?: string;\n}\n\n/**\n * Redis-backed coordination KV with optimistic concurrency via WATCH/MULTI.\n *\n * Each `set()` performs:\n *   1. WATCH key\n *   2. GET key            → read current version\n *   3. compare to ifVersion (if provided)\n *   4. MULTI / SET / [PEXPIRE] / EXEC\n *\n * If a competing writer modifies the key between WATCH and EXEC the\n * transaction aborts and we throw `VersionMismatchError`, matching\n * memory driver semantics.\n *\n * **Not** a cache — uses small JSON envelopes and per-key versioning.\n * Use service-cache for high-throughput caching.\n */\nexport class RedisKV implements IKV {\n    private readonly client: Redis;\n    private readonly keyPrefix: string;\n    private closed = false;\n\n    constructor(opts: RedisKVOptions) {\n        this.client = opts.client;\n        this.keyPrefix = opts.keyPrefix ?? 'os:';\n    }\n\n    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {\n        const raw = await this.client.get(this.kvKey(key));\n        if (raw === null) return undefined;\n        const parsed = this.parse(raw);\n        if (!parsed) return undefined;\n        const pttl = await this.client.pttl(this.kvKey(key));\n        const expiresAt = pttl > 0 ? Date.now() + pttl : undefined;\n        return {\n            key,\n            value: parsed.v as T,\n            version: BigInt(parsed.ver),\n            expiresAt,\n        };\n    }\n\n    async set<T = unknown>(\n        key: string,\n        value: T,\n        opts: KVSetOptions = {},\n    ): Promise<KVEntry<T>> {\n        if (this.closed) throw new Error('RedisKV is closed');\n        const physical = this.kvKey(key);\n        const ttlMs = opts.ttl && opts.ttl > 0 ? opts.ttl * 1000 : undefined;\n\n        // Optimistic-concurrency loop — Redis WATCH aborts the MULTI on\n        // any intervening write.\n        // eslint-disable-next-line no-constant-condition\n        while (true) {\n            await this.client.watch(physical);\n            const raw = await this.client.get(physical);\n            const existing = raw ? this.parse(raw) : undefined;\n            const existingVersion = existing ? BigInt(existing.ver) : 0n;\n\n            if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {\n                await this.client.unwatch();\n                throw new VersionMismatchError(key, opts.ifVersion, existingVersion);\n            }\n\n            const newVersion = existingVersion + 1n;\n            const payload: StoredKV = { v: value, ver: newVersion.toString() };\n            const encoded = JSON.stringify(payload);\n\n            const multi = this.client.multi();\n            if (ttlMs) {\n                multi.set(physical, encoded, 'PX', ttlMs);\n            } else {\n                multi.set(physical, encoded);\n            }\n            const result = await multi.exec();\n            // exec() returns null when WATCH detected a concurrent change.\n            if (result === null) continue;\n\n            return {\n                key,\n                value,\n                version: newVersion,\n                expiresAt: ttlMs ? Date.now() + ttlMs : undefined,\n            };\n        }\n    }\n\n    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {\n        if (this.closed) throw new Error('RedisKV is closed');\n        const physical = this.kvKey(key);\n\n        if (opts.ifVersion === undefined) {\n            const removed = await this.client.del(physical);\n            return removed > 0;\n        }\n\n        // eslint-disable-next-line no-constant-condition\n        while (true) {\n            await this.client.watch(physical);\n            const raw = await this.client.get(physical);\n            if (!raw) {\n                await this.client.unwatch();\n                return false;\n            }\n            const parsed = this.parse(raw);\n            if (!parsed) {\n                await this.client.unwatch();\n                return false;\n            }\n            const currentVersion = BigInt(parsed.ver);\n            if (opts.ifVersion !== currentVersion) {\n                await this.client.unwatch();\n                throw new VersionMismatchError(key, opts.ifVersion, currentVersion);\n            }\n            const multi = this.client.multi();\n            multi.del(physical);\n            const result = await multi.exec();\n            if (result === null) continue;\n            return (result[0]?.[1] as number) > 0;\n        }\n    }\n\n    async cas<T = unknown>(\n        key: string,\n        expectedVersion: bigint,\n        next: T,\n        opts: Omit<KVSetOptions, 'ifVersion'> = {},\n    ): Promise<KVEntry<T> | undefined> {\n        try {\n            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });\n        } catch (err) {\n            if (err instanceof VersionMismatchError) return undefined;\n            throw err;\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n    }\n\n    private kvKey(key: string): string {\n        return `${this.keyPrefix}kv:${key}`;\n    }\n\n    private parse(raw: string): StoredKV | undefined {\n        try {\n            const obj = JSON.parse(raw) as StoredKV;\n            if (typeof obj.ver !== 'string') return undefined;\n            return obj;\n        } catch {\n            return undefined;\n        }\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Redis } from 'ioredis';\nimport type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';\n\nexport interface RedisCounterOptions {\n    client: Redis;\n    keyPrefix?: string;\n}\n\n/**\n * Redis-backed monotonic counter using INCRBY. Each counter key lives at\n * `{prefix}ctr:{key}` so the same Redis instance can host multiple\n * tenants without collision.\n *\n * Values are stored as ASCII decimals (Redis convention). We surface\n * them as `bigint` to match the contract — INCRBY accepts up to a\n * signed 64-bit range, well beyond Number.MAX_SAFE_INTEGER.\n */\nexport class RedisCounter implements ICounter {\n    private readonly client: Redis;\n    private readonly keyPrefix: string;\n    private closed = false;\n\n    constructor(opts: RedisCounterOptions) {\n        this.client = opts.client;\n        this.keyPrefix = opts.keyPrefix ?? 'os:';\n    }\n\n    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {\n        if (this.closed) throw new Error('RedisCounter is closed');\n        const by = opts.by ?? 1;\n        const next = await this.client.incrby(this.ctrKey(key), by);\n        return BigInt(next);\n    }\n\n    async peek(key: string): Promise<bigint> {\n        const raw = await this.client.get(this.ctrKey(key));\n        if (raw === null) return 0n;\n        try {\n            return BigInt(raw);\n        } catch {\n            return 0n;\n        }\n    }\n\n    async reset(key: string, value: bigint = 0n): Promise<void> {\n        if (this.closed) throw new Error('RedisCounter is closed');\n        if (value === 0n) {\n            await this.client.del(this.ctrKey(key));\n            return;\n        }\n        await this.client.set(this.ctrKey(key), value.toString());\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n    }\n\n    private ctrKey(key: string): string {\n        return `${this.keyPrefix}ctr:${key}`;\n    }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,248 @@
+import { RedisOptions, Redis } from 'ioredis';
+import { IPubSub, PublishOptions, PubSubHandler, SubscribeOptions, Unsubscribe, ILock, LockAcquireOptions, LockHandle, IKV, KVEntry, KVSetOptions, ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';
+
+/**
+ * Options accepted by {@link createRedisClient}.
+ *
+ * Either pass `url` (e.g. `redis://user:pass@host:6379/0`) or a full
+ * ioredis `options` bag. The two are merged with `options` taking
+ * precedence so callers can override individual fields parsed from the
+ * URL.
+ *
+ * This factory is intended to be the single Redis-client construction
+ * point across ObjectStack — `service-cluster-redis` uses it for the
+ * driver, and `service-cache` will eventually share the same connection
+ * pool via {@link CreateRedisOptions.existing}.
+ */
+interface CreateRedisOptions {
+    /** Connection URL. Ignored when `existing` is provided. */
+    url?: string;
+    /** Extra ioredis options merged on top of `url`. */
+    options?: RedisOptions;
+    /**
+     * Bring-your-own client. When provided, this exact instance is
+     * returned and `url`/`options` are ignored — useful for sharing one
+     * pool across cluster + cache.
+     */
+    existing?: Redis;
+    /**
+     * If true, the returned client is created in lazyConnect mode so the
+     * TCP connection happens on first command rather than at construction.
+     * Default: true (matches ObjectStack's "fail at usage, not boot" stance).
+     */
+    lazyConnect?: boolean;
+}
+/**
+ * Construct (or reuse) an ioredis client with ObjectStack defaults.
+ *
+ * Defaults applied when `existing` is absent:
+ *   - `lazyConnect: true` — don't crash boot if Redis is briefly down
+ *   - `maxRetriesPerRequest: 3` — bound the failure window before surfacing
+ *   - `enableAutoPipelining: true` — modest throughput boost for batch workloads
+ *
+ * @example
+ *   const client = createRedisClient({ url: 'redis://localhost:6379' });
+ *
+ * @example reuse one pool across services
+ *   const shared = createRedisClient({ url });
+ *   const clusterClient = createRedisClient({ existing: shared });
+ *   const cacheClient   = createRedisClient({ existing: shared });
+ */
+declare function createRedisClient(opts?: CreateRedisOptions): Redis;
+/**
+ * Duplicate a Redis client so that pub/sub commands (which monopolize
+ * the connection) don't block regular commands. Mirrors the standard
+ * ioredis "two clients" pattern.
+ */
+declare function duplicateForPubSub(client: Redis): Redis;
+
+interface RedisPubSubOptions {
+    /** Already-connected client used for PUBLISH. */
+    client: Redis;
+    /** Optional node id surfaced as `fromNode` on every delivered message. */
+    nodeId?: string;
+    /** Key namespace prefix applied to every channel (default: 'os:'). */
+    keyPrefix?: string;
+    /** Error sink for subscriber handler exceptions. */
+    onError?: (err: unknown, channel: string) => void;
+}
+/**
+ * Redis pub/sub implementation of {@link IPubSub}.
+ *
+ * Uses two ioredis clients under the hood:
+ *   - `publisher` (caller-provided) — runs PUBLISH commands
+ *   - `subscriber` (auto-duplicated) — held in subscribe mode, can't run
+ *     regular commands per Redis protocol
+ *
+ * Delivery semantics match Redis pub/sub: at-most-once, fire-and-forget,
+ * no persistence. For at-least-once + replay use the planned `streams`
+ * adapter (separate driver).
+ *
+ * Channel names are prefixed with `keyPrefix` before being sent to
+ * Redis, so the same Redis instance can host multiple isolated
+ * ObjectStack deployments.
+ */
+declare class RedisPubSub implements IPubSub {
+    private readonly publisher;
+    private readonly subscriber;
+    private readonly nodeId?;
+    private readonly keyPrefix;
+    private readonly onError;
+    private readonly subs;
+    private closed;
+    constructor(opts: RedisPubSubOptions);
+    publish<T = unknown>(channel: string, payload: T, _opts?: PublishOptions): Promise<void>;
+    subscribe<T = unknown>(channel: string, handler: PubSubHandler<T>, _opts?: SubscribeOptions): Unsubscribe;
+    close(): Promise<void>;
+    private prefixed;
+    private dispatch;
+}
+
+interface RedisLockOptions {
+    client: Redis;
+    /** Counter client for fencing-token allocation. Same Redis is fine. */
+    counterClient?: Redis;
+    keyPrefix?: string;
+    defaultTtlMs?: number;
+    /** Stable node id baked into lock values for debugging. */
+    nodeId?: string;
+}
+/**
+ * Redis-backed distributed lock with TTL fencing.
+ *
+ * Algorithm (single-instance Redis, NOT Redlock — adequate for
+ * typical ObjectStack deployments with one Redis primary):
+ *
+ *   acquire = SET key {nodeId}:{token} NX PX ttl
+ *   release = Lua: GET == expected ? DEL : 0
+ *   renew   = Lua: GET == expected ? PEXPIRE : 0
+ *
+ * Fencing tokens come from a Redis counter (INCR on `{prefix}fence:{key}`)
+ * so that two clients in a split-brain see strictly increasing tokens
+ * downstream.
+ *
+ * For multi-master Redis (Sentinel failover, etc.) consider switching to
+ * a Redlock variant — not implemented yet.
+ */
+declare class RedisLock implements ILock {
+    private readonly client;
+    private readonly counterClient;
+    private readonly keyPrefix;
+    private readonly defaultTtlMs;
+    private readonly nodeId;
+    private closed;
+    constructor(opts: RedisLockOptions);
+    acquire(key: string, opts?: LockAcquireOptions): Promise<LockHandle | null>;
+    withLock<T>(key: string, fn: (h: LockHandle) => Promise<T>, opts?: LockAcquireOptions): Promise<T | null>;
+    close(): Promise<void>;
+    private trySet;
+    private makeHandle;
+    private lockKey;
+    private fenceKey;
+}
+
+declare class VersionMismatchError extends Error {
+    readonly key: string;
+    readonly expected: bigint;
+    readonly actual: bigint;
+    constructor(key: string, expected: bigint, actual: bigint);
+}
+interface RedisKVOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed coordination KV with optimistic concurrency via WATCH/MULTI.
+ *
+ * Each `set()` performs:
+ *   1. WATCH key
+ *   2. GET key            → read current version
+ *   3. compare to ifVersion (if provided)
+ *   4. MULTI / SET / [PEXPIRE] / EXEC
+ *
+ * If a competing writer modifies the key between WATCH and EXEC the
+ * transaction aborts and we throw `VersionMismatchError`, matching
+ * memory driver semantics.
+ *
+ * **Not** a cache — uses small JSON envelopes and per-key versioning.
+ * Use service-cache for high-throughput caching.
+ */
+declare class RedisKV implements IKV {
+    private readonly client;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts: RedisKVOptions);
+    get<T = unknown>(key: string): Promise<KVEntry<T> | undefined>;
+    set<T = unknown>(key: string, value: T, opts?: KVSetOptions): Promise<KVEntry<T>>;
+    delete(key: string, opts?: {
+        ifVersion?: bigint;
+    }): Promise<boolean>;
+    cas<T = unknown>(key: string, expectedVersion: bigint, next: T, opts?: Omit<KVSetOptions, 'ifVersion'>): Promise<KVEntry<T> | undefined>;
+    close(): Promise<void>;
+    private kvKey;
+    private parse;
+}
+
+interface RedisCounterOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed monotonic counter using INCRBY. Each counter key lives at
+ * `{prefix}ctr:{key}` so the same Redis instance can host multiple
+ * tenants without collision.
+ *
+ * Values are stored as ASCII decimals (Redis convention). We surface
+ * them as `bigint` to match the contract — INCRBY accepts up to a
+ * signed 64-bit range, well beyond Number.MAX_SAFE_INTEGER.
+ */
+declare class RedisCounter implements ICounter {
+    private readonly client;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts: RedisCounterOptions);
+    incr(key: string, opts?: CounterIncrOptions): Promise<bigint>;
+    peek(key: string): Promise<bigint>;
+    reset(key: string, value?: bigint): Promise<void>;
+    close(): Promise<void>;
+    private ctrKey;
+}
+
+/**
+ * @objectstack/service-cluster-redis
+ *
+ * Redis driver for `@objectstack/service-cluster`. Import this package
+ * once at process start to register the `'redis'` driver:
+ *
+ * ```ts
+ * import '@objectstack/service-cluster-redis';
+ * import { defineCluster } from '@objectstack/service-cluster';
+ *
+ * const cluster = defineCluster({
+ *     driver: 'redis',
+ *     url: 'redis://localhost:6379',
+ *     nodeId: 'web-1',
+ * });
+ * ```
+ *
+ * The driver also exports raw constructors so callers who already own
+ * an ioredis client can compose primitives by hand.
+ */
+
+/**
+ * Driver-specific options accepted under `driverOptions` in
+ * `ClusterCapabilityConfig`. All are optional — supply a `client` to
+ * share a Redis pool with other services (e.g. `service-cache`).
+ */
+interface RedisDriverOptions {
+    /** Pre-built ioredis client. When provided, `url` is ignored. */
+    client?: Redis;
+    /** Key prefix applied to every Redis key (default: 'os:'). */
+    keyPrefix?: string;
+    /** Default lock TTL in ms. Overridden by `LockAcquireOptions.ttlMs`. */
+    lockTtlMs?: number;
+    /** Pub/sub subscriber error sink. */
+    onError?: (err: unknown, channel: string) => void;
+}
+
+export { type CreateRedisOptions, RedisCounter, type RedisCounterOptions, type RedisDriverOptions, RedisKV, type RedisKVOptions, RedisLock, type RedisLockOptions, RedisPubSub, type RedisPubSubOptions, VersionMismatchError, createRedisClient, duplicateForPubSub };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { RedisOptions, Redis } from 'ioredis';
+import { IPubSub, PublishOptions, PubSubHandler, SubscribeOptions, Unsubscribe, ILock, LockAcquireOptions, LockHandle, IKV, KVEntry, KVSetOptions, ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';
+
+/**
+ * Options accepted by {@link createRedisClient}.
+ *
+ * Either pass `url` (e.g. `redis://user:pass@host:6379/0`) or a full
+ * ioredis `options` bag. The two are merged with `options` taking
+ * precedence so callers can override individual fields parsed from the
+ * URL.
+ *
+ * This factory is intended to be the single Redis-client construction
+ * point across ObjectStack — `service-cluster-redis` uses it for the
+ * driver, and `service-cache` will eventually share the same connection
+ * pool via {@link CreateRedisOptions.existing}.
+ */
+interface CreateRedisOptions {
+    /** Connection URL. Ignored when `existing` is provided. */
+    url?: string;
+    /** Extra ioredis options merged on top of `url`. */
+    options?: RedisOptions;
+    /**
+     * Bring-your-own client. When provided, this exact instance is
+     * returned and `url`/`options` are ignored — useful for sharing one
+     * pool across cluster + cache.
+     */
+    existing?: Redis;
+    /**
+     * If true, the returned client is created in lazyConnect mode so the
+     * TCP connection happens on first command rather than at construction.
+     * Default: true (matches ObjectStack's "fail at usage, not boot" stance).
+     */
+    lazyConnect?: boolean;
+}
+/**
+ * Construct (or reuse) an ioredis client with ObjectStack defaults.
+ *
+ * Defaults applied when `existing` is absent:
+ *   - `lazyConnect: true` — don't crash boot if Redis is briefly down
+ *   - `maxRetriesPerRequest: 3` — bound the failure window before surfacing
+ *   - `enableAutoPipelining: true` — modest throughput boost for batch workloads
+ *
+ * @example
+ *   const client = createRedisClient({ url: 'redis://localhost:6379' });
+ *
+ * @example reuse one pool across services
+ *   const shared = createRedisClient({ url });
+ *   const clusterClient = createRedisClient({ existing: shared });
+ *   const cacheClient   = createRedisClient({ existing: shared });
+ */
+declare function createRedisClient(opts?: CreateRedisOptions): Redis;
+/**
+ * Duplicate a Redis client so that pub/sub commands (which monopolize
+ * the connection) don't block regular commands. Mirrors the standard
+ * ioredis "two clients" pattern.
+ */
+declare function duplicateForPubSub(client: Redis): Redis;
+
+interface RedisPubSubOptions {
+    /** Already-connected client used for PUBLISH. */
+    client: Redis;
+    /** Optional node id surfaced as `fromNode` on every delivered message. */
+    nodeId?: string;
+    /** Key namespace prefix applied to every channel (default: 'os:'). */
+    keyPrefix?: string;
+    /** Error sink for subscriber handler exceptions. */
+    onError?: (err: unknown, channel: string) => void;
+}
+/**
+ * Redis pub/sub implementation of {@link IPubSub}.
+ *
+ * Uses two ioredis clients under the hood:
+ *   - `publisher` (caller-provided) — runs PUBLISH commands
+ *   - `subscriber` (auto-duplicated) — held in subscribe mode, can't run
+ *     regular commands per Redis protocol
+ *
+ * Delivery semantics match Redis pub/sub: at-most-once, fire-and-forget,
+ * no persistence. For at-least-once + replay use the planned `streams`
+ * adapter (separate driver).
+ *
+ * Channel names are prefixed with `keyPrefix` before being sent to
+ * Redis, so the same Redis instance can host multiple isolated
+ * ObjectStack deployments.
+ */
+declare class RedisPubSub implements IPubSub {
+    private readonly publisher;
+    private readonly subscriber;
+    private readonly nodeId?;
+    private readonly keyPrefix;
+    private readonly onError;
+    private readonly subs;
+    private closed;
+    constructor(opts: RedisPubSubOptions);
+    publish<T = unknown>(channel: string, payload: T, _opts?: PublishOptions): Promise<void>;
+    subscribe<T = unknown>(channel: string, handler: PubSubHandler<T>, _opts?: SubscribeOptions): Unsubscribe;
+    close(): Promise<void>;
+    private prefixed;
+    private dispatch;
+}
+
+interface RedisLockOptions {
+    client: Redis;
+    /** Counter client for fencing-token allocation. Same Redis is fine. */
+    counterClient?: Redis;
+    keyPrefix?: string;
+    defaultTtlMs?: number;
+    /** Stable node id baked into lock values for debugging. */
+    nodeId?: string;
+}
+/**
+ * Redis-backed distributed lock with TTL fencing.
+ *
+ * Algorithm (single-instance Redis, NOT Redlock — adequate for
+ * typical ObjectStack deployments with one Redis primary):
+ *
+ *   acquire = SET key {nodeId}:{token} NX PX ttl
+ *   release = Lua: GET == expected ? DEL : 0
+ *   renew   = Lua: GET == expected ? PEXPIRE : 0
+ *
+ * Fencing tokens come from a Redis counter (INCR on `{prefix}fence:{key}`)
+ * so that two clients in a split-brain see strictly increasing tokens
+ * downstream.
+ *
+ * For multi-master Redis (Sentinel failover, etc.) consider switching to
+ * a Redlock variant — not implemented yet.
+ */
+declare class RedisLock implements ILock {
+    private readonly client;
+    private readonly counterClient;
+    private readonly keyPrefix;
+    private readonly defaultTtlMs;
+    private readonly nodeId;
+    private closed;
+    constructor(opts: RedisLockOptions);
+    acquire(key: string, opts?: LockAcquireOptions): Promise<LockHandle | null>;
+    withLock<T>(key: string, fn: (h: LockHandle) => Promise<T>, opts?: LockAcquireOptions): Promise<T | null>;
+    close(): Promise<void>;
+    private trySet;
+    private makeHandle;
+    private lockKey;
+    private fenceKey;
+}
+
+declare class VersionMismatchError extends Error {
+    readonly key: string;
+    readonly expected: bigint;
+    readonly actual: bigint;
+    constructor(key: string, expected: bigint, actual: bigint);
+}
+interface RedisKVOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed coordination KV with optimistic concurrency via WATCH/MULTI.
+ *
+ * Each `set()` performs:
+ *   1. WATCH key
+ *   2. GET key            → read current version
+ *   3. compare to ifVersion (if provided)
+ *   4. MULTI / SET / [PEXPIRE] / EXEC
+ *
+ * If a competing writer modifies the key between WATCH and EXEC the
+ * transaction aborts and we throw `VersionMismatchError`, matching
+ * memory driver semantics.
+ *
+ * **Not** a cache — uses small JSON envelopes and per-key versioning.
+ * Use service-cache for high-throughput caching.
+ */
+declare class RedisKV implements IKV {
+    private readonly client;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts: RedisKVOptions);
+    get<T = unknown>(key: string): Promise<KVEntry<T> | undefined>;
+    set<T = unknown>(key: string, value: T, opts?: KVSetOptions): Promise<KVEntry<T>>;
+    delete(key: string, opts?: {
+        ifVersion?: bigint;
+    }): Promise<boolean>;
+    cas<T = unknown>(key: string, expectedVersion: bigint, next: T, opts?: Omit<KVSetOptions, 'ifVersion'>): Promise<KVEntry<T> | undefined>;
+    close(): Promise<void>;
+    private kvKey;
+    private parse;
+}
+
+interface RedisCounterOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed monotonic counter using INCRBY. Each counter key lives at
+ * `{prefix}ctr:{key}` so the same Redis instance can host multiple
+ * tenants without collision.
+ *
+ * Values are stored as ASCII decimals (Redis convention). We surface
+ * them as `bigint` to match the contract — INCRBY accepts up to a
+ * signed 64-bit range, well beyond Number.MAX_SAFE_INTEGER.
+ */
+declare class RedisCounter implements ICounter {
+    private readonly client;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts: RedisCounterOptions);
+    incr(key: string, opts?: CounterIncrOptions): Promise<bigint>;
+    peek(key: string): Promise<bigint>;
+    reset(key: string, value?: bigint): Promise<void>;
+    close(): Promise<void>;
+    private ctrKey;
+}
+
+/**
+ * @objectstack/service-cluster-redis
+ *
+ * Redis driver for `@objectstack/service-cluster`. Import this package
+ * once at process start to register the `'redis'` driver:
+ *
+ * ```ts
+ * import '@objectstack/service-cluster-redis';
+ * import { defineCluster } from '@objectstack/service-cluster';
+ *
+ * const cluster = defineCluster({
+ *     driver: 'redis',
+ *     url: 'redis://localhost:6379',
+ *     nodeId: 'web-1',
+ * });
+ * ```
+ *
+ * The driver also exports raw constructors so callers who already own
+ * an ioredis client can compose primitives by hand.
+ */
+
+/**
+ * Driver-specific options accepted under `driverOptions` in
+ * `ClusterCapabilityConfig`. All are optional — supply a `client` to
+ * share a Redis pool with other services (e.g. `service-cache`).
+ */
+interface RedisDriverOptions {
+    /** Pre-built ioredis client. When provided, `url` is ignored. */
+    client?: Redis;
+    /** Key prefix applied to every Redis key (default: 'os:'). */
+    keyPrefix?: string;
+    /** Default lock TTL in ms. Overridden by `LockAcquireOptions.ttlMs`. */
+    lockTtlMs?: number;
+    /** Pub/sub subscriber error sink. */
+    onError?: (err: unknown, channel: string) => void;
+}
+
+export { type CreateRedisOptions, RedisCounter, type RedisCounterOptions, type RedisDriverOptions, RedisKV, type RedisKVOptions, RedisLock, type RedisLockOptions, RedisPubSub, type RedisPubSubOptions, VersionMismatchError, createRedisClient, duplicateForPubSub };