@fluojs/redis 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,157 @@
+# @fluojs/redis
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 공유 Redis 연결 계층입니다. 애플리케이션 수명 주기에 따라 관리되는 단일 `ioredis` 클라이언트를 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [일반적인 패턴](#일반적인-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/redis ioredis
+```
+
+## 사용 시점
+
+- 캐싱, 큐, 전송률 제한(Throttler) 등 여러 모듈에서 공유할 Redis 연결이 필요할 때.
+- 애플리케이션 시작 시 자동 연결, 종료 시 안전한 연결 해제 기능을 원할 때.
+- JSON 데이터를 다루기 편한 고수준의 Redis 파사드(Facade)가 필요할 때.
+
+## 빠른 시작
+
+### 모듈 등록
+
+`RedisModule.forRoot(options)`는 기본 Redis 클라이언트와 `RedisService` 파사드를 등록하는 지원되는 root entrypoint입니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { RedisModule } from '@fluojs/redis';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({
+      host: 'localhost',
+      port: 6379,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Redis 서비스 사용
+
+`RedisService`를 주입받아 고수준 작업을 수행하거나, `REDIS_CLIENT`를 통해 원시 `ioredis` 인스턴스를 직접 사용할 수 있습니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { RedisService } from '@fluojs/redis';
+
+@Inject(RedisService)
+export class CacheRepository {
+  constructor(private readonly redis: RedisService) {}
+
+  async saveUser(id: string, user: object) {
+    await this.redis.set(`user:${id}`, user, 3600);
+  }
+
+  async getUser(id: string) {
+    return await this.redis.get(`user:${id}`);
+  }
+}
+```
+
+## 일반적인 패턴
+
+### 이름 있는 클라이언트
+
+하나의 애플리케이션에서 여러 Redis 연결이 필요하면 `RedisModule.forRootNamed(name, options)`를 사용하세요. `RedisModule.forRoot(options)`는 기본 `REDIS_CLIENT`와 `RedisService` 별칭을 제공하고, 이름 있는 등록은 `getRedisClientToken(name)`과 `getRedisServiceToken(name)`으로 해석합니다.
+
+- `name`을 생략하면 기본 별칭인 `REDIS_CLIENT` / `RedisService`를 사용합니다.
+- `name`을 지정하면 `getRedisClientToken(name)` / `getRedisServiceToken(name)`으로 이름 있는 바인딩을 가져옵니다.
+
+```typescript
+import { Module, Inject } from '@fluojs/core';
+import type Redis from 'ioredis';
+import {
+  getRedisClientToken,
+  getRedisServiceToken,
+  RedisModule,
+  RedisService,
+} from '@fluojs/redis';
+
+const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+const ANALYTICS_REDIS_CLIENT = getRedisClientToken('analytics');
+
+@Module({
+  imports: [
+    RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+    RedisModule.forRootNamed('analytics', { host: 'localhost', port: 6380 }),
+  ],
+})
+export class AppModule {}
+
+@Inject(RedisService, ANALYTICS_REDIS, ANALYTICS_REDIS_CLIENT)
+export class AnalyticsStore {
+  constructor(
+    private readonly defaultRedis: RedisService,
+    private readonly analyticsRedis: RedisService,
+    private readonly analyticsClient: Redis,
+  ) {}
+}
+```
+
+### 원시 클라이언트 접근 (Raw Client Access)
+
+파이프라인, Lua 스크립트, Pub/Sub 등 복잡한 Redis 명령이 필요한 경우 원시 클라이언트를 직접 주입받아 사용합니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { REDIS_CLIENT } from '@fluojs/redis';
+import type Redis from 'ioredis';
+
+@Inject(REDIS_CLIENT)
+export class AdvancedService {
+  constructor(private readonly client: Redis) {}
+
+  async executeComplex() {
+    return await this.client.pipeline().set('foo', 'bar').get('foo').exec();
+  }
+}
+```
+
+## 공개 API 개요
+
+### 핵심 구성 요소
+- `RedisModule`: 전역 Redis 클라이언트 등록 및 수명 주기 훅을 관리합니다.
+- `RedisModule.forRoot(options)`: 기본 Redis 클라이언트와 `RedisService` 파사드를 위한 지원되는 root entrypoint입니다.
+- `RedisModule.forRootNamed(name, options)`: 기본 별칭을 유지한 채 추가 Redis 클라이언트를 등록합니다.
+- `RedisService`: JSON 코덱 지원 및 `get`/`set`/`del` 메서드를 제공하는 파사드입니다.
+- `REDIS_CLIENT`: 내부 `ioredis` 인스턴스에 접근하기 위한 DI 토큰입니다.
+- `getRedisClientToken(name)`: 이름 있는 raw client 토큰 헬퍼입니다. `name`을 생략하면 기본 `REDIS_CLIENT` 토큰을 돌려줍니다.
+- `getRedisServiceToken(name)`: 이름 있는 `RedisService` 토큰 헬퍼입니다. `name`을 생략하면 기본 `RedisService` 토큰을 돌려줍니다.
+- `getRedisComponentId(name)`: Redis 소비 패키지들이 사용하는 상태/의존성 식별자 헬퍼입니다 (`redis.default`, `redis.cache` 등).
+- `createRedisPlatformStatusSnapshot(input)`: Redis 연결 상태를 Fluo 플랫폼 health/readiness 스냅샷으로 변환합니다.
+
+### 타입
+- `RedisModuleOptions`: `ioredis` 생성자에 전달되는 설정 옵션입니다.
+
+## 관련 패키지
+
+- `@fluojs/cache-manager`: Redis를 백엔드로 사용하는 캐싱 패키지입니다.
+- `@fluojs/queue`: Redis 기반의 분산 작업 큐 패키지입니다.
+- `@fluojs/throttler`: Redis 기반의 분산 전송률 제한 패키지입니다.
+
+## 예제 소스
+
+- `packages/redis/src/module.test.ts`: 모듈 수명 주기 및 DI 연결 예제.
+- `packages/redis/src/public-api.test.ts`: 문서화된 Redis 공개 export를 검증하는 테스트입니다.
+- `packages/redis/src/redis-service.ts`: 파사드 구현 및 코덱 로직.

package/README.md

@@ -0,0 +1,157 @@
+# @fluojs/redis
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Shared Redis connection layer for fluo. It provides a singleton `ioredis` client managed by the application lifecycle.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/redis ioredis
+```
+
+## When to Use
+
+- When you need a shared Redis connection across multiple modules (caching, queues, throttlers).
+- When you want automatic connection management (connect on bootstrap, quit on shutdown).
+- When you need a JSON-aware facade for common key-value operations.
+
+## Quick Start
+
+### Register the Module
+
+Use `RedisModule.forRoot(options)` to register the default Redis client and `RedisService` facade.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { RedisModule } from '@fluojs/redis';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({
+      host: 'localhost',
+      port: 6379,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Use the Redis Service
+
+Inject `RedisService` for high-level operations or `REDIS_CLIENT` for the raw `ioredis` instance.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { RedisService } from '@fluojs/redis';
+
+@Inject(RedisService)
+export class CacheRepository {
+  constructor(private readonly redis: RedisService) {}
+
+  async saveUser(id: string, user: object) {
+    await this.redis.set(`user:${id}`, user, 3600);
+  }
+
+  async getUser(id: string) {
+    return await this.redis.get(`user:${id}`);
+  }
+}
+```
+
+## Common Patterns
+
+### Named Clients
+
+Use `RedisModule.forRootNamed(name, options)` when one application needs more than one Redis connection. `RedisModule.forRoot(options)` provides the default `REDIS_CLIENT` and `RedisService` aliases, and named registrations are resolved with `getRedisClientToken(name)` and `getRedisServiceToken(name)`.
+
+- Omit `name` when you want the default aliases: `REDIS_CLIENT` / `RedisService`.
+- Pass `name` when you want the named helpers: `getRedisClientToken(name)` / `getRedisServiceToken(name)`.
+
+```typescript
+import { Module, Inject } from '@fluojs/core';
+import type Redis from 'ioredis';
+import {
+  getRedisClientToken,
+  getRedisServiceToken,
+  RedisModule,
+  RedisService,
+} from '@fluojs/redis';
+
+const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+const ANALYTICS_REDIS_CLIENT = getRedisClientToken('analytics');
+
+@Module({
+  imports: [
+    RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+    RedisModule.forRootNamed('analytics', { host: 'localhost', port: 6380 }),
+  ],
+})
+export class AppModule {}
+
+@Inject(RedisService, ANALYTICS_REDIS, ANALYTICS_REDIS_CLIENT)
+export class AnalyticsStore {
+  constructor(
+    private readonly defaultRedis: RedisService,
+    private readonly analyticsRedis: RedisService,
+    private readonly analyticsClient: Redis,
+  ) {}
+}
+```
+
+### Raw Client Access
+
+If you need advanced Redis commands (pipelines, lua scripts, pub/sub), inject the raw client directly.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { REDIS_CLIENT } from '@fluojs/redis';
+import type Redis from 'ioredis';
+
+@Inject(REDIS_CLIENT)
+export class AdvancedService {
+  constructor(private readonly client: Redis) {}
+
+  async executeComplex() {
+    return await this.client.pipeline().set('foo', 'bar').get('foo').exec();
+  }
+}
+```
+
+## Public API Overview
+
+### Core
+- `RedisModule`: Registers the global Redis client and lifecycle hooks.
+- `RedisModule.forRoot(options)`: Registers the default Redis client plus `RedisService` facade.
+- `RedisModule.forRootNamed(name, options)`: Registers an additional named Redis client without replacing the default aliases.
+- `RedisService`: Facade with JSON codec support and `get`/`set`/`del` methods.
+- `REDIS_CLIENT`: DI token for the underlying `ioredis` instance.
+- `getRedisClientToken(name)`: DI token helper for a named raw client. Omitting `name` returns the default `REDIS_CLIENT` token.
+- `getRedisServiceToken(name)`: DI token helper for a named `RedisService` facade. Omitting `name` returns the default `RedisService` token.
+- `getRedisComponentId(name)`: Status/dependency id helper used by Redis-consuming packages (`redis.default`, `redis.cache`, etc.).
+- `createRedisPlatformStatusSnapshot(input)`: Adapts Redis connection state into Fluo's platform health/readiness snapshot contract.
+
+### Types
+- `RedisModuleOptions`: Configuration options passed directly to the `ioredis` constructor.
+
+## Related Packages
+
+- `@fluojs/cache-manager`: Uses this package for Redis-backed caching.
+- `@fluojs/queue`: Uses this package for distributed job processing.
+- `@fluojs/throttler`: Uses this package for distributed rate limiting.
+
+## Example Sources
+
+- `packages/redis/src/module.test.ts`: Module lifecycle and DI wiring.
+- `packages/redis/src/public-api.test.ts`: Root-barrel export guard for the documented Redis surface.
+- `packages/redis/src/redis-service.ts`: Facade implementation and codec logic.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { RedisModule } from './module.js';
+export * from './redis-service.js';
+export * from './status.js';
+export * from './tokens.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { RedisModule } from './module.js';
+export * from './redis-service.js';
+export * from './status.js';
+export * from './tokens.js';
+export * from './types.js';

package/dist/module.d.ts

@@ -0,0 +1,71 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { RedisModuleOptions } from './types.js';
+/** Runtime module entrypoint for the shared Redis client integration. */
+export declare class RedisModule {
+    /**
+     * Registers a global Redis client and exports the facade used across Fluo packages.
+     *
+     * @param options Redis client options used to construct the shared connection.
+     * @returns A module definition that exports {@link REDIS_CLIENT} and {@link RedisService}.
+     *
+     * @see RedisModule.forRootNamed
+     * @see getRedisClientToken
+     * @see getRedisServiceToken
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import { RedisModule } from '@fluojs/redis';
+     *
+     * @Module({
+     *   imports: [RedisModule.forRoot({ host: 'localhost', port: 6379 })],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(options: RedisModuleOptions): ModuleType;
+    /**
+     * Registers one additional named Redis client without changing the default aliases.
+     *
+     * @param name Stable Redis client name used to derive named raw-client and facade tokens.
+     * @param options Redis client options used to construct the named connection.
+     * @returns A module definition that exports the named raw-client token and named `RedisService` token.
+     *
+     * @see getRedisClientToken
+     * @see getRedisServiceToken
+     *
+     * @example
+     * ```ts
+     * import { Module, Inject } from '@fluojs/core';
+     * import type Redis from 'ioredis';
+     * import {
+     *   getRedisClientToken,
+     *   getRedisServiceToken,
+     *   RedisModule,
+     *   RedisService,
+     * } from '@fluojs/redis';
+     *
+     * const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+     * const ANALYTICS_REDIS_CLIENT = getRedisClientToken('analytics');
+     *
+     * @Module({
+     *   imports: [
+     *     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+     *     RedisModule.forRootNamed('analytics', { host: 'localhost', port: 6380 }),
+     *   ],
+     * })
+     * export class AppModule {}
+     *
+     * @Inject(RedisService, ANALYTICS_REDIS, ANALYTICS_REDIS_CLIENT)
+     * export class AnalyticsStore {
+     *   constructor(
+     *     private readonly defaultRedis: RedisService,
+     *     private readonly analyticsRedis: RedisService,
+     *     private readonly analyticsClient: Redis,
+     *   ) {}
+     * }
+     * ```
+     */
+    static forRootNamed(name: string, options: RedisModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMhE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA6ErD,yEAAyE;AACzE,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,UAAU;CAW3E"}

package/dist/module.js

@@ -0,0 +1,150 @@
+import { defineModule } from '@fluojs/runtime';
+import Redis from 'ioredis';
+import { getRedisServiceToken, RedisService } from './redis-service.js';
+import { RedisLifecycleService } from './service.js';
+import { getRedisClientToken, REDIS_CLIENT } from './tokens.js';
+const redisLifecycleTokens = new Map();
+function getRedisLifecycleToken(name) {
+  const existing = redisLifecycleTokens.get(name);
+  if (existing) {
+    return existing;
+  }
+  const created = Symbol(`fluo.redis.lifecycle:${name}`);
+  redisLifecycleTokens.set(name, created);
+  return created;
+}
+
+/**
+ * Creates the providers that back Fluo's shared Redis integration.
+ *
+ * @param options Redis constructor options forwarded to `ioredis` with `lazyConnect` forced on.
+ * @param name Optional Redis client name for additional named registrations.
+ * @returns Providers for the raw client token, the JSON-aware facade, and lifecycle hooks.
+ */
+function createRedisProviders(options, name) {
+  const clientToken = getRedisClientToken(name);
+  if (clientToken === REDIS_CLIENT) {
+    return [{
+      scope: 'singleton',
+      provide: REDIS_CLIENT,
+      useFactory: () => new Redis({
+        ...options,
+        lazyConnect: true
+      })
+    }, RedisService, RedisLifecycleService];
+  }
+  if (name === undefined) {
+    throw new Error('Redis client name must be defined for named provider creation.');
+  }
+  const serviceToken = getRedisServiceToken(name);
+  return [{
+    scope: 'singleton',
+    provide: clientToken,
+    useFactory: () => new Redis({
+      ...options,
+      lazyConnect: true
+    })
+  }, {
+    inject: [clientToken],
+    provide: serviceToken,
+    scope: 'singleton',
+    useFactory: (...deps) => {
+      const [client] = deps;
+      return new RedisService(client);
+    }
+  }, {
+    inject: [clientToken],
+    provide: getRedisLifecycleToken(name),
+    scope: 'singleton',
+    useFactory: (...deps) => {
+      const [client] = deps;
+      return new RedisLifecycleService(client, name);
+    }
+  }];
+}
+
+/** Runtime module entrypoint for the shared Redis client integration. */
+export class RedisModule {
+  /**
+   * Registers a global Redis client and exports the facade used across Fluo packages.
+   *
+   * @param options Redis client options used to construct the shared connection.
+   * @returns A module definition that exports {@link REDIS_CLIENT} and {@link RedisService}.
+   *
+   * @see RedisModule.forRootNamed
+   * @see getRedisClientToken
+   * @see getRedisServiceToken
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import { RedisModule } from '@fluojs/redis';
+   *
+   * @Module({
+   *   imports: [RedisModule.forRoot({ host: 'localhost', port: 6379 })],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(options) {
+    class RedisModuleDefinition {}
+    return defineModule(RedisModuleDefinition, {
+      global: true,
+      exports: [REDIS_CLIENT, RedisService],
+      providers: createRedisProviders(options)
+    });
+  }
+
+  /**
+   * Registers one additional named Redis client without changing the default aliases.
+   *
+   * @param name Stable Redis client name used to derive named raw-client and facade tokens.
+   * @param options Redis client options used to construct the named connection.
+   * @returns A module definition that exports the named raw-client token and named `RedisService` token.
+   *
+   * @see getRedisClientToken
+   * @see getRedisServiceToken
+   *
+   * @example
+   * ```ts
+   * import { Module, Inject } from '@fluojs/core';
+   * import type Redis from 'ioredis';
+   * import {
+   *   getRedisClientToken,
+   *   getRedisServiceToken,
+   *   RedisModule,
+   *   RedisService,
+   * } from '@fluojs/redis';
+   *
+   * const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+   * const ANALYTICS_REDIS_CLIENT = getRedisClientToken('analytics');
+   *
+   * @Module({
+   *   imports: [
+   *     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+   *     RedisModule.forRootNamed('analytics', { host: 'localhost', port: 6380 }),
+   *   ],
+   * })
+   * export class AppModule {}
+   *
+   * @Inject(RedisService, ANALYTICS_REDIS, ANALYTICS_REDIS_CLIENT)
+   * export class AnalyticsStore {
+   *   constructor(
+   *     private readonly defaultRedis: RedisService,
+   *     private readonly analyticsRedis: RedisService,
+   *     private readonly analyticsClient: Redis,
+   *   ) {}
+   * }
+   * ```
+   */
+  static forRootNamed(name, options) {
+    const clientToken = getRedisClientToken(name);
+    const serviceToken = getRedisServiceToken(name);
+    class NamedRedisModuleDefinition {}
+    return defineModule(NamedRedisModuleDefinition, {
+      global: true,
+      exports: [clientToken, serviceToken],
+      providers: createRedisProviders(options, name)
+    });
+  }
+}

package/dist/redis-service.d.ts

@@ -0,0 +1,79 @@
+import { type Token } from '@fluojs/core';
+import type Redis from 'ioredis';
+/**
+ * JSON-aware facade over the shared Redis client.
+ *
+ * Use this service for common key-value access when you want Fluo to handle
+ * JSON serialization and lifecycle-managed connection reuse.
+ *
+ * @example
+ * ```ts
+ * import { Inject } from '@fluojs/core';
+ * import { RedisService } from '@fluojs/redis';
+ *
+ * @Inject(RedisService)
+ * export class SessionStore {
+ *   constructor(private readonly redis: RedisService) {}
+ *
+ *   async save(sessionId: string, value: object) {
+ *     await this.redis.set(`session:${sessionId}`, value, 300);
+ *   }
+ * }
+ * ```
+ *
+ * @see getRedisServiceToken For resolving a named `RedisService` binding.
+ */
+export declare class RedisService {
+    private readonly client;
+    constructor(client: Redis);
+    /**
+     * Reads one Redis value and attempts to decode JSON payloads automatically.
+     *
+     * @param key Redis key to fetch from the shared client.
+     * @returns The parsed JSON value, the raw string payload, or `null` when the key is missing.
+     */
+    get<T>(key: string): Promise<T | string | null>;
+    /**
+     * Stores one value after JSON serialization.
+     *
+     * @param key Redis key to write.
+     * @param value Serializable value stored as JSON.
+     * @param ttlSeconds Optional TTL in seconds. Omit or pass a non-positive value for a persistent key.
+     * @returns A promise that resolves after Redis acknowledges the write.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Deletes one key from Redis.
+     *
+     * @param key Redis key to remove.
+     * @returns A promise that resolves once the delete command completes.
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Returns the underlying `ioredis` client for advanced commands.
+     *
+     * @returns The lifecycle-managed raw Redis client instance.
+     */
+    getRawClient(): Redis;
+}
+/**
+ * Resolves the facade token for the default or a named `RedisService` binding.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns `RedisService` for the default client path, otherwise a stable named service token.
+ *
+ * @example
+ * ```ts
+ * const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+ *
+ * @Inject(ANALYTICS_REDIS)
+ * export class AnalyticsStore {
+ *   constructor(private readonly redis: RedisService) {}
+ * }
+ * ```
+ *
+ * @see RedisModule.forRootNamed
+ * @see getRedisClientToken
+ */
+export declare function getRedisServiceToken(name?: string): Token<RedisService>;
+//# sourceMappingURL=redis-service.d.ts.map

package/dist/redis-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-service.d.ts","sourceRoot":"","sources":["../src/redis-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AA0BjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,KAAK;IAE1C;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IASrD;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvE;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;;;OAIG;IACH,YAAY,IAAI,KAAK;CAGtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,CAMvE"}

package/dist/redis-service.js

@@ -0,0 +1,138 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { REDIS_CLIENT, getRedisClientToken } from './tokens.js';
+const namedRedisServiceTokens = new Map();
+function getOrCreateNamedRedisServiceToken(name) {
+  const existing = namedRedisServiceTokens.get(name);
+  if (existing) {
+    return existing;
+  }
+  const created = Symbol(`fluo.redis.service:${name}`);
+  namedRedisServiceTokens.set(name, created);
+  return created;
+}
+function decodeRedisValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * JSON-aware facade over the shared Redis client.
+ *
+ * Use this service for common key-value access when you want Fluo to handle
+ * JSON serialization and lifecycle-managed connection reuse.
+ *
+ * @example
+ * ```ts
+ * import { Inject } from '@fluojs/core';
+ * import { RedisService } from '@fluojs/redis';
+ *
+ * @Inject(RedisService)
+ * export class SessionStore {
+ *   constructor(private readonly redis: RedisService) {}
+ *
+ *   async save(sessionId: string, value: object) {
+ *     await this.redis.set(`session:${sessionId}`, value, 300);
+ *   }
+ * }
+ * ```
+ *
+ * @see getRedisServiceToken For resolving a named `RedisService` binding.
+ */
+let _RedisService;
+class RedisService {
+  static {
+    [_RedisService, _initClass] = _applyDecs(this, [Inject(REDIS_CLIENT)], []).c;
+  }
+  constructor(client) {
+    this.client = client;
+  }
+
+  /**
+   * Reads one Redis value and attempts to decode JSON payloads automatically.
+   *
+   * @param key Redis key to fetch from the shared client.
+   * @returns The parsed JSON value, the raw string payload, or `null` when the key is missing.
+   */
+  async get(key) {
+    const raw = await this.client.get(key);
+    if (raw === null) {
+      return null;
+    }
+    return decodeRedisValue(raw);
+  }
+
+  /**
+   * Stores one value after JSON serialization.
+   *
+   * @param key Redis key to write.
+   * @param value Serializable value stored as JSON.
+   * @param ttlSeconds Optional TTL in seconds. Omit or pass a non-positive value for a persistent key.
+   * @returns A promise that resolves after Redis acknowledges the write.
+   */
+  async set(key, value, ttlSeconds) {
+    const serialized = JSON.stringify(value);
+    if (ttlSeconds !== undefined && ttlSeconds > 0) {
+      await this.client.set(key, serialized, 'EX', ttlSeconds);
+    } else {
+      await this.client.set(key, serialized);
+    }
+  }
+
+  /**
+   * Deletes one key from Redis.
+   *
+   * @param key Redis key to remove.
+   * @returns A promise that resolves once the delete command completes.
+   */
+  async del(key) {
+    await this.client.del(key);
+  }
+
+  /**
+   * Returns the underlying `ioredis` client for advanced commands.
+   *
+   * @returns The lifecycle-managed raw Redis client instance.
+   */
+  getRawClient() {
+    return this.client;
+  }
+  static {
+    _initClass();
+  }
+}
+
+/**
+ * Resolves the facade token for the default or a named `RedisService` binding.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns `RedisService` for the default client path, otherwise a stable named service token.
+ *
+ * @example
+ * ```ts
+ * const ANALYTICS_REDIS = getRedisServiceToken('analytics');
+ *
+ * @Inject(ANALYTICS_REDIS)
+ * export class AnalyticsStore {
+ *   constructor(private readonly redis: RedisService) {}
+ * }
+ * ```
+ *
+ * @see RedisModule.forRootNamed
+ * @see getRedisClientToken
+ */
+export { _RedisService as RedisService };
+export function getRedisServiceToken(name) {
+  if (getRedisClientToken(name) === REDIS_CLIENT) {
+    return _RedisService;
+  }
+  return getOrCreateNamedRedisServiceToken(name?.trim() ?? '');
+}

package/dist/service.d.ts

@@ -0,0 +1,17 @@
+import type Redis from 'ioredis';
+import type { OnApplicationShutdown, OnModuleInit } from '@fluojs/runtime';
+/**
+ * Manages Redis client startup and shutdown as part of the application lifecycle.
+ */
+export declare class RedisLifecycleService implements OnModuleInit, OnApplicationShutdown {
+    private readonly client;
+    private readonly clientName?;
+    constructor(client: Redis, clientName?: string | undefined);
+    onModuleInit(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    createPlatformStatusSnapshot(): import("./status.js").PersistencePlatformStatusSnapshot;
+    private shouldConnectOnInit;
+    private disconnectIfPossible;
+    private quitWithDisconnectFallback;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAwB3E;;GAEG;AACH,qBACa,qBAAsB,YAAW,YAAY,EAAE,qBAAqB;IAE7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;gBADX,MAAM,EAAE,KAAK,EACb,UAAU,CAAC,EAAE,MAAM,YAAA;IAGhC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5C,4BAA4B;IAO5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,oBAAoB;YAMd,0BAA0B;CAYzC"}

package/dist/service.js

@@ -0,0 +1,83 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { createRedisPlatformStatusSnapshot } from './status.js';
+import { getRedisComponentId, REDIS_CLIENT } from './tokens.js';
+const QUITTABLE_STATUSES = new Set(['connect', 'connecting', 'ready', 'reconnecting']);
+const DISCONNECTABLE_STATUSES = new Set(['close', 'connect', 'connecting', 'ready', 'reconnecting', 'wait']);
+function isClosed(status) {
+  return status === 'end';
+}
+function isConnectable(status) {
+  return status === 'wait';
+}
+function isQuittable(status) {
+  return QUITTABLE_STATUSES.has(status);
+}
+function isDisconnectable(status) {
+  return DISCONNECTABLE_STATUSES.has(status);
+}
+
+/**
+ * Manages Redis client startup and shutdown as part of the application lifecycle.
+ */
+let _RedisLifecycleServic;
+class RedisLifecycleService {
+  static {
+    [_RedisLifecycleServic, _initClass] = _applyDecs(this, [Inject(REDIS_CLIENT)], []).c;
+  }
+  constructor(client, clientName) {
+    this.client = client;
+    this.clientName = clientName;
+  }
+  async onModuleInit() {
+    if (!this.shouldConnectOnInit()) {
+      return;
+    }
+    await this.client.connect();
+  }
+  async onApplicationShutdown() {
+    const status = this.client.status;
+    if (isClosed(status)) {
+      return;
+    }
+    if (!isQuittable(status)) {
+      this.disconnectIfPossible(status);
+      return;
+    }
+    await this.quitWithDisconnectFallback();
+  }
+  createPlatformStatusSnapshot() {
+    return createRedisPlatformStatusSnapshot({
+      componentId: getRedisComponentId(this.clientName),
+      status: this.client.status
+    });
+  }
+  shouldConnectOnInit() {
+    return isConnectable(this.client.status);
+  }
+  disconnectIfPossible(status) {
+    if (isDisconnectable(status)) {
+      this.client.disconnect();
+    }
+  }
+  async quitWithDisconnectFallback() {
+    try {
+      await this.client.quit();
+      return;
+    } catch (error) {
+      this.disconnectIfPossible(this.client.status);
+      if (!isClosed(this.client.status)) {
+        throw error;
+      }
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _RedisLifecycleServic as RedisLifecycleService };

package/dist/status.d.ts

@@ -0,0 +1,22 @@
+import type Redis from 'ioredis';
+import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/** Normalized Redis platform snapshot shape used by health/readiness integrations. */
+export interface PersistencePlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/** Input consumed by the Redis status adapter when translating runtime state. */
+export interface RedisStatusAdapterInput {
+    componentId?: string;
+    status: Redis['status'];
+}
+/**
+ * Adapts one Redis client status into Fluo's platform snapshot contract.
+ *
+ * @param input Redis client status and optional component identity.
+ * @returns A normalized snapshot describing readiness, health, ownership, and details.
+ */
+export declare function createRedisPlatformStatusSnapshot(input: RedisStatusAdapterInput): PersistencePlatformStatusSnapshot;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,sFAAsF;AACtF,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CACzB;AAwDD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,iCAAiC,CAcnH"}

package/dist/status.js

@@ -0,0 +1,72 @@
+/** Normalized Redis platform snapshot shape used by health/readiness integrations. */
+
+/** Input consumed by the Redis status adapter when translating runtime state. */
+
+const DEGRADATION_STATUSES = new Set(['wait', 'connecting', 'connect', 'reconnecting']);
+const UNHEALTHY_STATUSES = new Set(['close', 'end']);
+function createReadiness(input) {
+  if (input.status === 'ready') {
+    return {
+      critical: true,
+      status: 'ready'
+    };
+  }
+  if (input.status === 'wait') {
+    return {
+      critical: true,
+      reason: 'Redis client is still in lazyConnect wait state.',
+      status: 'not-ready'
+    };
+  }
+  if (input.status === 'connect' || input.status === 'connecting' || input.status === 'reconnecting') {
+    return {
+      critical: true,
+      reason: `Redis client is ${input.status}.`,
+      status: 'degraded'
+    };
+  }
+  return {
+    critical: true,
+    reason: `Redis client is ${input.status}.`,
+    status: 'not-ready'
+  };
+}
+function createHealth(input) {
+  if (UNHEALTHY_STATUSES.has(input.status)) {
+    return {
+      reason: `Redis client is ${input.status}.`,
+      status: 'unhealthy'
+    };
+  }
+  if (DEGRADATION_STATUSES.has(input.status)) {
+    return {
+      reason: `Redis client is ${input.status}.`,
+      status: 'degraded'
+    };
+  }
+  return {
+    status: 'healthy'
+  };
+}
+
+/**
+ * Adapts one Redis client status into Fluo's platform snapshot contract.
+ *
+ * @param input Redis client status and optional component identity.
+ * @returns A normalized snapshot describing readiness, health, ownership, and details.
+ */
+export function createRedisPlatformStatusSnapshot(input) {
+  return {
+    details: {
+      componentId: input.componentId,
+      connectionState: input.status,
+      lazyConnect: true
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: false,
+      ownsResources: true
+    },
+    readiness: createReadiness(input)
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Injection token for the shared default `ioredis` client managed by {@link RedisModule}.
+ *
+ * @see getRedisClientToken For resolving the default or a named raw-client token through one helper.
+ */
+export declare const REDIS_CLIENT: unique symbol;
+/** Stable name used when callers request the default Redis client contract. */
+export declare const DEFAULT_REDIS_CLIENT_NAME = "default";
+/**
+ * Resolves the DI token for the default or a named Redis client.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns The default `REDIS_CLIENT` token when `name` is omitted, otherwise a stable named token.
+ *
+ * @example
+ * ```ts
+ * const CACHE_REDIS = getRedisClientToken('cache');
+ *
+ * @Inject(CACHE_REDIS)
+ * export class CacheInspector {
+ *   constructor(private readonly redis: Redis) {}
+ * }
+ * ```
+ *
+ * @see RedisModule.forRootNamed
+ * @see getRedisServiceToken
+ */
+export declare function getRedisClientToken(name?: string): symbol;
+/**
+ * Builds the stable component/dependency id used by platform status snapshots.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns A stable component id such as `redis.default` or `redis.jobs`.
+ *
+ * @see getRedisClientToken
+ */
+export declare function getRedisComponentId(name?: string): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAA8B,CAAC;AAExD,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,YAAY,CAAC;AA8BnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/tokens.js

@@ -0,0 +1,68 @@
+/**
+ * Injection token for the shared default `ioredis` client managed by {@link RedisModule}.
+ *
+ * @see getRedisClientToken For resolving the default or a named raw-client token through one helper.
+ */
+export const REDIS_CLIENT = Symbol('fluo.redis.client');
+
+/** Stable name used when callers request the default Redis client contract. */
+export const DEFAULT_REDIS_CLIENT_NAME = 'default';
+function normalizeRedisClientName(name) {
+  if (name === undefined) {
+    return undefined;
+  }
+  const normalized = name.trim();
+  if (normalized.length === 0) {
+    throw new Error('Redis client name must be a non-empty string.');
+  }
+  return normalized;
+}
+const namedRedisClientTokens = new Map();
+function getOrCreateNamedRedisClientToken(name) {
+  const existing = namedRedisClientTokens.get(name);
+  if (existing) {
+    return existing;
+  }
+  const created = Symbol(`fluo.redis.client:${name}`);
+  namedRedisClientTokens.set(name, created);
+  return created;
+}
+
+/**
+ * Resolves the DI token for the default or a named Redis client.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns The default `REDIS_CLIENT` token when `name` is omitted, otherwise a stable named token.
+ *
+ * @example
+ * ```ts
+ * const CACHE_REDIS = getRedisClientToken('cache');
+ *
+ * @Inject(CACHE_REDIS)
+ * export class CacheInspector {
+ *   constructor(private readonly redis: Redis) {}
+ * }
+ * ```
+ *
+ * @see RedisModule.forRootNamed
+ * @see getRedisServiceToken
+ */
+export function getRedisClientToken(name) {
+  const normalizedName = normalizeRedisClientName(name);
+  if (normalizedName === undefined) {
+    return REDIS_CLIENT;
+  }
+  return getOrCreateNamedRedisClientToken(normalizedName);
+}
+
+/**
+ * Builds the stable component/dependency id used by platform status snapshots.
+ *
+ * @param name Optional Redis client name registered through `RedisModule.forRootNamed(...)`.
+ * @returns A stable component id such as `redis.default` or `redis.jobs`.
+ *
+ * @see getRedisClientToken
+ */
+export function getRedisComponentId(name) {
+  return `redis.${normalizeRedisClientName(name) ?? DEFAULT_REDIS_CLIENT_NAME}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+import type { RedisOptions } from 'ioredis';
+/**
+ * Options accepted by {@link RedisModule.forRoot}.
+ *
+ * Fluo always enables `lazyConnect` internally so the client connects during
+ * application bootstrap instead of import time.
+ */
+export type RedisModuleOptions = Omit<RedisOptions, 'lazyConnect'>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@fluojs/redis",
+  "description": "App-scoped Redis lifecycle management, raw client injection, and RedisService facade for Fluo.",
+  "keywords": [
+    "fluo",
+    "redis",
+    "ioredis",
+    "cache",
+    "connection",
+    "lifecycle"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/redis"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ioredis": "^5.10.0",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/core": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}