@fluojs/terminus 1.0.5 → 2.0.0

package/dist/indicators/prisma.js

@@ -1,5 +1,7 @@
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
+import { optional } from '@fluojs/di';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError, waitForIndicatorProbeSettlement, withIndicatorTimeout } from './utils.js';
 const PRISMA_CLIENT = Symbol.for('fluo.prisma.client');
+const PRISMA_SERVICE = Symbol.for('fluo.prisma.service');
 
 /** Options for probing Prisma-backed database connectivity. */
 
@@ -9,7 +11,7 @@ async function runPrismaPing(options) {
     await options.ping();
     return;
   }
-  const client = options.client;
+  const client = resolveCurrentPrismaClient(options.service) ?? options.client;
   if (!client) {
     throw new Error('Prisma indicator requires either a client or ping callback.');
   }
@@ -31,50 +33,138 @@ async function runPrismaPing(options) {
   }
   throw new Error('Prisma indicator requires a client with query/execute capabilities or a ping callback.');
 }
+function normalizePrismaRegistrationName(name) {
+  if (name === undefined) {
+    return undefined;
+  }
+  const normalizedName = name.trim();
+  if (normalizedName.length === 0) {
+    throw new Error('Prisma health indicator registration name must be a non-empty string when provided.');
+  }
+  return normalizedName;
+}
+function getPrismaClientToken(name) {
+  const normalizedName = normalizePrismaRegistrationName(name);
+  return normalizedName === undefined ? PRISMA_CLIENT : Symbol.for(`fluo.prisma.client:${normalizedName}`);
+}
+function getPrismaServiceToken(name) {
+  const normalizedName = normalizePrismaRegistrationName(name);
+  return normalizedName === undefined ? PRISMA_SERVICE : Symbol.for(`fluo.prisma.service:${normalizedName}`);
+}
+function resolveCurrentPrismaClient(service) {
+  if (!service || typeof service.current !== 'function') {
+    return undefined;
+  }
+  return service.current();
+}
+function createPrismaLifecycleSnapshot(service) {
+  if (!service || typeof service.createPlatformStatusSnapshot !== 'function') {
+    return undefined;
+  }
+  return service.createPlatformStatusSnapshot();
+}
+function createPrismaLifecycleDownResult(indicatorKey, snapshot) {
+  const healthStatus = snapshot.health.status;
+  const readinessStatus = snapshot.readiness.status;
+  if (healthStatus === 'healthy' && readinessStatus === 'ready') {
+    return undefined;
+  }
+  const message = snapshot.readiness.reason ?? snapshot.health.reason ?? `Prisma lifecycle reported health=${healthStatus} readiness=${readinessStatus}.`;
+  return createDownResult(indicatorKey, message, {
+    details: snapshot.details,
+    healthStatus,
+    readinessStatus
+  });
+}
+function createPrismaLifecycleUpDetails(snapshot) {
+  if (!snapshot) {
+    return {};
+  }
+  return {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  };
+}
+function toPrismaService(value) {
+  return typeof value === 'object' && value !== null ? value : undefined;
+}
 
 /**
  * Create a Prisma health indicator.
  *
- * @param options Optional Prisma client, ping callback, timeout, and key override.
- * @returns A health indicator that executes a lightweight Prisma round trip.
+ * @param options Optional lifecycle-aware service facade, Prisma client, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Prisma lifecycle state before executing a lightweight round trip.
  */
 export function createPrismaHealthIndicator(options = {}) {
   return new PrismaHealthIndicator(options);
 }
 
 /**
- * Create a Terminus indicator provider collection entry that resolves a Prisma client from DI.
+ * Create a Terminus indicator provider collection entry that resolves Prisma from DI.
+ *
+ * The provider prefers `getPrismaServiceToken(options.name)` so `@fluojs/prisma`
+ * lifecycle snapshots participate in health/readiness diagnostics. It falls back
+ * to the matching raw client token for compatibility with manual provider graphs.
+ * Explicit `serviceToken` and `clientToken` values override the name-derived tokens.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * @param options Optional name hint, explicit tokens, timeout, key override, or custom ping callback.
  * @returns A factory provider with a unique internal DI token for `TerminusModule` indicatorProviders.
  */
 export function createPrismaHealthIndicatorProvider(options = {}) {
   const indicatorProviderToken = Symbol('fluo.terminus.prisma-health-indicator');
+  const hasExplicitServiceToken = options.serviceToken !== undefined;
+  const hasExplicitClientToken = options.clientToken !== undefined;
+  const serviceToken = hasExplicitServiceToken || !hasExplicitClientToken ? options.serviceToken ?? getPrismaServiceToken(options.name) : undefined;
+  const clientToken = hasExplicitClientToken || !hasExplicitServiceToken ? options.clientToken ?? getPrismaClientToken(options.name) : undefined;
+  const inject = [...(serviceToken === undefined ? [] : [optional(serviceToken)]), ...(clientToken === undefined ? [] : [optional(clientToken)])];
   return {
-    inject: [PRISMA_CLIENT],
+    inject,
     provide: indicatorProviderToken,
-    useFactory: client => new PrismaHealthIndicator({
-      ...options,
-      client: client
-    })
+    useFactory: (...resolvedDependencies) => {
+      const resolvedService = serviceToken === undefined ? undefined : resolvedDependencies[0];
+      const resolvedClientIndex = serviceToken === undefined ? 0 : 1;
+      const resolvedClient = clientToken === undefined ? undefined : resolvedDependencies[resolvedClientIndex];
+      return new PrismaHealthIndicator({
+        ...options,
+        client: resolvedClient,
+        service: toPrismaService(resolvedService)
+      });
+    }
   };
 }
 
-/** Health indicator that probes Prisma connectivity with a trivial query. */
+/** Health indicator that maps Prisma lifecycle status and probes connectivity with a trivial query. */
 export class PrismaHealthIndicator {
   key;
+  readiness;
+  pendingProbeSettlement;
   constructor(options = {}) {
     this.options = options;
     this.key = options.key;
+    this.readiness = options.readiness;
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('prisma', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_PRISMA_TIMEOUT_MS;
     try {
-      await withIndicatorTimeout(runPrismaPing(this.options), timeoutMs, indicatorKey);
-      return createUpResult(indicatorKey);
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_PRISMA_TIMEOUT_MS, indicatorKey);
+      const snapshot = createPrismaLifecycleSnapshot(this.options.service);
+      const lifecycleDownResult = snapshot ? createPrismaLifecycleDownResult(indicatorKey, snapshot) : undefined;
+      if (lifecycleDownResult) {
+        throwHealthCheckError('Prisma health check failed.', lifecycleDownResult);
+      }
+      const probe = runPrismaPing(this.options);
+      this.pendingProbeSettlement = waitForIndicatorProbeSettlement(probe);
+      await withIndicatorTimeout(probe, timeoutMs, indicatorKey);
+      return createUpResult(indicatorKey, createPrismaLifecycleUpDetails(snapshot));
     } catch (error) {
+      if (error instanceof Error && error.name === 'HealthCheckError') {
+        throw error;
+      }
       throwHealthCheckError('Prisma health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : 'Prisma health check failed.'));
     }
   }
+  getPendingHealthCheckSettlement() {
+    return this.pendingProbeSettlement;
+  }
 }

package/dist/indicators/redis.d.ts

@@ -22,6 +22,8 @@ export interface RedisHealthIndicatorOptions {
     key?: string;
     /** Custom ping callback for manual probes or tests. Lifecycle state is only mapped when `client.status` is available. */
     ping?: () => Promise<unknown> | unknown;
+    /** Whether this indicator participates in `/ready`. Defaults to `true`. */
+    readiness?: boolean;
     /** Maximum time to wait for the ping operation. Defaults to `2_000` ms. */
     timeoutMs?: number;
 }
@@ -39,6 +41,10 @@ export declare function createRedisHealthIndicator(options?: RedisHealthIndicato
  * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
  * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
  *
+ * The Redis client token is a required dependency of the indicator, so it must be visible in
+ * the Terminus module scope. Pass the owning module through `TerminusModule.forRoot({ imports })`;
+ * a missing registration fails at bootstrap rather than degrading `/health` and `/ready` afterwards.
+ *
  * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
@@ -47,8 +53,11 @@ export declare function createRedisHealthIndicatorProvider(options?: Omit<RedisH
 export declare class RedisHealthIndicator implements HealthIndicator {
     private readonly options;
     readonly key: string | undefined;
+    readonly readiness: boolean | undefined;
+    private pendingProbeSettlement;
     constructor(options?: RedisHealthIndicatorOptions);
     check(key: string): Promise<HealthIndicatorResult>;
+    getPendingHealthCheckSettlement(): Promise<void> | undefined;
 }
 export {};
 //# sourceMappingURL=redis.d.ts.map

package/dist/indicators/redis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAA+E,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAG1I,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oGAAoG;IACpG,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,4GAA4G;AAC5G,qBAAa,oBAAqB,YAAW,eAAe;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,2BAAgC;IAIhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAwBzD"}
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAA+E,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE1I,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oGAAoG;IACpG,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,4GAA4G;AAC5G,qBAAa,oBAAqB,YAAW,eAAe;IAK9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,OAAO,CAAC,sBAAsB,CAA4B;gBAE7B,OAAO,GAAE,2BAAgC;IAKhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA2BxD,+BAA+B,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;CAG7D"}

package/dist/indicators/redis.js

@@ -1,5 +1,5 @@
 import { createRedisPlatformStatusSnapshot, getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError, waitForIndicatorProbeSettlement, withIndicatorTimeout } from './utils.js';
 
 /**
  * Options for probing Redis connectivity.
@@ -74,6 +74,10 @@ export function createRedisHealthIndicator(options = {}) {
  * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
  * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
  *
+ * The Redis client token is a required dependency of the indicator, so it must be visible in
+ * the Terminus module scope. Pass the owning module through `TerminusModule.forRoot({ imports })`;
+ * a missing registration fails at bootstrap rather than degrading `/health` and `/ready` afterwards.
+ *
  * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
@@ -92,19 +96,24 @@ export function createRedisHealthIndicatorProvider(options = {}) {
 /** Health indicator that maps Redis lifecycle status and checks reachability with a ping-like operation. */
 export class RedisHealthIndicator {
   key;
+  readiness;
+  pendingProbeSettlement;
   constructor(options = {}) {
     this.options = options;
     this.key = options.key;
+    this.readiness = options.readiness;
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('redis', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_REDIS_TIMEOUT_MS;
     try {
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_REDIS_TIMEOUT_MS, indicatorKey);
       const lifecycleDownResult = createRedisLifecycleDownResult(indicatorKey, this.options);
       if (lifecycleDownResult) {
         throwHealthCheckError('Redis health check failed.', lifecycleDownResult);
       }
-      await withIndicatorTimeout(runRedisPing(this.options), timeoutMs, indicatorKey);
+      const probe = runRedisPing(this.options);
+      this.pendingProbeSettlement = waitForIndicatorProbeSettlement(probe);
+      await withIndicatorTimeout(probe, timeoutMs, indicatorKey);
       return createUpResult(indicatorKey, createRedisLifecycleUpDetails(this.options));
     } catch (error) {
       if (error instanceof Error && error.name === 'HealthCheckError') {
@@ -113,4 +122,7 @@ export class RedisHealthIndicator {
       throwHealthCheckError('Redis health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : 'Redis health check failed.'));
     }
   }
+  getPendingHealthCheckSettlement() {
+    return this.pendingProbeSettlement;
+  }
 }

package/dist/indicators/utils.d.ts

@@ -3,6 +3,16 @@ import type { HealthIndicatorResult } from '../types.js';
 export interface IndicatorTimeoutOptions {
     timeoutMs?: number;
 }
+/**
+ * Resolve an indicator timeout budget before it reaches timeout scheduling.
+ *
+ * @param timeoutMs Caller-provided timeout budget in milliseconds.
+ * @param defaultTimeoutMs Default timeout budget used when `timeoutMs` is omitted.
+ * @param indicatorName Indicator name used in timeout validation errors.
+ * @returns A positive integer timeout budget in milliseconds.
+ * @throws {Error} When the resolved timeout is zero, negative, `NaN`, or infinite.
+ */
+export declare function resolveIndicatorTimeoutMs(timeoutMs: number | undefined, defaultTimeoutMs: number, indicatorName: string): number;
 /**
  * Create an `up` indicator result payload.
  *
@@ -29,6 +39,13 @@ export declare function createDownResult(key: string, message: string, details?:
  * @returns The original promise result when it finishes in time.
  */
 export declare function withIndicatorTimeout<T>(promise: Promise<T>, timeoutMs: number, indicatorName: string): Promise<T>;
+/**
+ * Convert a probe promise into a settlement signal that never rejects.
+ *
+ * @param promise Probe promise whose completion releases its execution ownership.
+ * @returns A promise that resolves after the probe either fulfills or rejects.
+ */
+export declare function waitForIndicatorProbeSettlement(promise: Promise<unknown>): Promise<void>;
 /**
  * Resolve the effective key used in reports for one indicator execution.
  *

package/dist/indicators/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/indicators/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,qBAAqB,CAOxG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,qBAAqB,CAQvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,KAAK,CAE3F"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/indicators/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,qBAAqB,CAOxG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,qBAAqB,CAQvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,KAAK,CAE3F"}

package/dist/indicators/utils.js

@@ -2,6 +2,26 @@ import { HealthCheckError } from '../errors.js';
 
 /** Timeout settings shared by indicators that call external dependencies. */
 
+function normalizePositiveFiniteTimeoutMs(timeoutMs, indicatorName) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`${indicatorName} health indicator timeoutMs must be a positive finite number.`);
+  }
+  return Math.max(1, Math.floor(timeoutMs));
+}
+
+/**
+ * Resolve an indicator timeout budget before it reaches timeout scheduling.
+ *
+ * @param timeoutMs Caller-provided timeout budget in milliseconds.
+ * @param defaultTimeoutMs Default timeout budget used when `timeoutMs` is omitted.
+ * @param indicatorName Indicator name used in timeout validation errors.
+ * @returns A positive integer timeout budget in milliseconds.
+ * @throws {Error} When the resolved timeout is zero, negative, `NaN`, or infinite.
+ */
+export function resolveIndicatorTimeoutMs(timeoutMs, defaultTimeoutMs, indicatorName) {
+  return normalizePositiveFiniteTimeoutMs(timeoutMs ?? defaultTimeoutMs, indicatorName);
+}
+
 /**
  * Create an `up` indicator result payload.
  *
@@ -45,10 +65,16 @@ export function createDownResult(key, message, details = {}) {
  * @returns The original promise result when it finishes in time.
  */
 export function withIndicatorTimeout(promise, timeoutMs, indicatorName) {
+  let normalizedTimeoutMs;
+  try {
+    normalizedTimeoutMs = normalizePositiveFiniteTimeoutMs(timeoutMs, indicatorName);
+  } catch (error) {
+    return Promise.reject(error);
+  }
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      reject(new Error(`${indicatorName} health indicator timed out after ${String(timeoutMs)}ms.`));
-    }, timeoutMs);
+      reject(new Error(`${indicatorName} health indicator timed out after ${String(normalizedTimeoutMs)}ms.`));
+    }, normalizedTimeoutMs);
     promise.then(value => {
       clearTimeout(timer);
       resolve(value);
@@ -59,6 +85,16 @@ export function withIndicatorTimeout(promise, timeoutMs, indicatorName) {
   });
 }
 
+/**
+ * Convert a probe promise into a settlement signal that never rejects.
+ *
+ * @param promise Probe promise whose completion releases its execution ownership.
+ * @returns A promise that resolves after the probe either fulfills or rejects.
+ */
+export function waitForIndicatorProbeSettlement(promise) {
+  return promise.then(() => undefined, () => undefined);
+}
+
 /**
  * Resolve the effective key used in reports for one indicator execution.
  *

package/dist/module.d.ts

@@ -5,6 +5,13 @@ export declare class TerminusModule {
     /**
      * Register Terminus health indicators and readiness hooks.
      *
+     * DI-backed indicator providers resolve inside the Terminus module scope. A named Redis token
+     * is required, so its owner module must be listed in `imports`; otherwise bootstrap fails with
+     * `MODULE_VISIBILITY_ERROR`. Prisma and Drizzle owner tokens are optional only when absent from
+     * the bootstrap graph: omitting their modules then lets the application bootstrap and their
+     * indicators report `down` on health checks. Existing sibling owner tokens still require
+     * `imports`; optional injection never bypasses module visibility.
+     *
      * @example
      * ```ts
      * import { MemoryHealthIndicator } from '@fluojs/terminus/node';
@@ -14,7 +21,17 @@ export declare class TerminusModule {
      * });
      * ```
      *
-     * @param options Terminus health indicator and readiness configuration.
+     * @example
+     * ```ts
+     * const prismaModule = PrismaModule.forRoot({ client });
+     *
+     * TerminusModule.forRoot({
+     *   imports: [prismaModule],
+     *   indicatorProviders: [createPrismaHealthIndicatorProvider({ key: 'prisma' })],
+     * });
+     * ```
+     *
+     * @param options Terminus health indicator, dependency import, and readiness configuration.
      * @returns A runtime module exposing health endpoints and `TerminusHealthService`.
      */
     static forRoot(options?: TerminusModuleOptions): ModuleType;

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiSlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAKhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAkSlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}

package/dist/module.js

@@ -23,6 +23,7 @@ function createTerminusProviders(options = {}) {
     execution: {
       ...(options.execution ?? {})
     },
+    imports: [...(options.imports ?? [])],
     indicators: copyIndicators(options.indicators),
     indicatorProviders: copyProviders(options.indicatorProviders),
     readinessChecks: [...(options.readinessChecks ?? [])]
@@ -149,7 +150,9 @@ function withPlatformDiagnostics(report, health, readiness) {
 }
 function createTerminusRuntimeModule(options = {}) {
   const readinessChecks = [...(options.readinessChecks ?? [])];
+  const terminusImports = [...(options.imports ?? [])];
   const healthModule = HealthModule.forRoot({
+    endpointMiddleware: options.endpointMiddleware,
     healthCheck: async ctx => {
       const healthService = await ctx.container.resolve(TerminusHealthService);
       const platformShell = await ctx.container.resolve(PLATFORM_SHELL);
@@ -168,10 +171,12 @@ function createTerminusRuntimeModule(options = {}) {
   const TERMINUS_READINESS_REGISTRAR = Symbol('fluo.terminus.readiness-registrar');
   class TerminusRuntimeModule {}
   return defineModule(TerminusRuntimeModule, {
-    exports: [TERMINUS_HEALTH_INDICATORS, TerminusHealthService],
-    imports: [healthModule],
+    exports: [TERMINUS_HEALTH_INDICATORS, TERMINUS_INDICATOR_PROVIDER_TOKENS, TerminusHealthService],
+    imports: [healthModule, ...terminusImports],
     providers: [...createTerminusProviders({
       execution: options.execution,
+      endpointMiddleware: options.endpointMiddleware,
+      imports: terminusImports,
       indicatorProviders: options.indicatorProviders,
       indicators: options.indicators,
       path: options.path,
@@ -185,7 +190,7 @@ function createTerminusRuntimeModule(options = {}) {
           onApplicationBootstrap() {
             healthModule.addReadinessCheck(async ctx => {
               const platformShell = await ctx.container.resolve(PLATFORM_SHELL);
-              const [indicatorHealthy, readiness] = await Promise.all([healthService.isHealthy(), platformShell.ready()]);
+              const [indicatorHealthy, readiness] = await Promise.all([healthService.isReady(), platformShell.ready()]);
               return indicatorHealthy && readiness.status === 'ready';
             });
           }
@@ -200,6 +205,13 @@ export class TerminusModule {
   /**
    * Register Terminus health indicators and readiness hooks.
    *
+   * DI-backed indicator providers resolve inside the Terminus module scope. A named Redis token
+   * is required, so its owner module must be listed in `imports`; otherwise bootstrap fails with
+   * `MODULE_VISIBILITY_ERROR`. Prisma and Drizzle owner tokens are optional only when absent from
+   * the bootstrap graph: omitting their modules then lets the application bootstrap and their
+   * indicators report `down` on health checks. Existing sibling owner tokens still require
+   * `imports`; optional injection never bypasses module visibility.
+   *
    * @example
    * ```ts
    * import { MemoryHealthIndicator } from '@fluojs/terminus/node';
@@ -209,7 +221,17 @@ export class TerminusModule {
    * });
    * ```
    *
-   * @param options Terminus health indicator and readiness configuration.
+   * @example
+   * ```ts
+   * const prismaModule = PrismaModule.forRoot({ client });
+   *
+   * TerminusModule.forRoot({
+   *   imports: [prismaModule],
+   *   indicatorProviders: [createPrismaHealthIndicatorProvider({ key: 'prisma' })],
+   * });
+   * ```
+   *
+   * @param options Terminus health indicator, dependency import, and readiness configuration.
    * @returns A runtime module exposing health endpoints and `TerminusHealthService`.
    */
   static forRoot(options = {}) {

package/dist/node-runtime.d.ts

@@ -5,7 +5,11 @@ interface NodeMemoryUsageSnapshot {
     heapUsed: number;
     rss: number;
 }
-/** Read Node.js process memory usage through the Terminus Node runtime seam. */
+/**
+ * Read Node.js process memory usage through the Terminus Node runtime seam.
+ *
+ * @returns A snapshot of the current Node.js process memory usage.
+ */
 export declare function readNodeMemoryUsage(): NodeMemoryUsageSnapshot;
 export {};
 //# sourceMappingURL=node-runtime.d.ts.map

package/dist/node-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-runtime.d.ts","sourceRoot":"","sources":["../src/node-runtime.ts"],"names":[],"mappings":"AAAA,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAkBD,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,uBAAuB,CAQ7D"}
+{"version":3,"file":"node-runtime.d.ts","sourceRoot":"","sources":["../src/node-runtime.ts"],"names":[],"mappings":"AAAA,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAkBD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,uBAAuB,CAQ7D"}

package/dist/node-runtime.js

@@ -3,7 +3,11 @@ function resolveNodeProcess() {
   return runtimeGlobal.process;
 }
 
-/** Read Node.js process memory usage through the Terminus Node runtime seam. */
+/**
+ * Read Node.js process memory usage through the Terminus Node runtime seam.
+ *
+ * @returns A snapshot of the current Node.js process memory usage.
+ */
 export function readNodeMemoryUsage() {
   const memoryUsage = resolveNodeProcess()?.memoryUsage;
   if (typeof memoryUsage !== 'function') {

package/dist/types.d.ts

@@ -1,5 +1,7 @@
+import type { Constructor } from '@fluojs/core';
 import type { Provider } from '@fluojs/di';
-import type { PlatformHealthReport, PlatformReadinessReport, ReadinessCheck } from '@fluojs/runtime';
+import type { Middleware } from '@fluojs/http';
+import type { ModuleType, PlatformHealthReport, PlatformReadinessReport, ReadinessCheck } from '@fluojs/runtime';
 /** Status values returned by one health indicator execution. */
 export type HealthIndicatorStatus = 'up' | 'down';
 /** One indicator state payload stored under its resolved key. */
@@ -14,6 +16,8 @@ export type HealthIndicatorResult = {
 export interface HealthIndicator {
     check(key: string): Promise<HealthIndicatorResult>;
     key?: string;
+    /** Whether this indicator participates in `/ready`. Defaults to `true`. */
+    readiness?: boolean;
 }
 /** Structured health report returned by Terminus aggregation helpers. */
 export interface HealthCheckReport {
@@ -44,6 +48,18 @@ export interface HealthCheckExecutionOptions {
  */
 export interface TerminusModuleOptions {
     execution?: HealthCheckExecutionOptions;
+    /** Class-based middleware applied only to the generated `/health` and `/ready` endpoints. */
+    endpointMiddleware?: readonly Constructor<Middleware>[];
+    /**
+     * Modules whose exported tokens must be visible to `indicatorProviders`.
+     *
+     * Terminus registers `indicatorProviders` inside its own module scope, so a
+     * dependency-owning module such as `PrismaModule`, `DrizzleModule`, or a named
+     * `RedisModule` registration must be imported here for its exported tokens to
+     * resolve. Importing the module into the parent application module alone does
+     * not make its exports visible to Terminus.
+     */
+    imports?: readonly ModuleType[];
     indicators?: readonly HealthIndicator[];
     indicatorProviders?: readonly Provider[];
     path?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErG,gEAAgE;AAChE,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAAC;AAElD,iEAAiE;AACjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,qBAAqB,CAAC;CAC/B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAAC;CACrC,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,EAAE,EAAE,MAAM,EAAE,CAAC;KACd,CAAC;IACF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,oBAAoB,CAAC;QAC7B,SAAS,EAAE,uBAAuB,CAAC;KACpC,CAAC;IACF,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACxC,kBAAkB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjH,gEAAgE;AAChE,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAAC;AAElD,iEAAiE;AACjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,qBAAqB,CAAC;CAC/B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAAC;CACrC,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,EAAE,EAAE,MAAM,EAAE,CAAC;KACd,CAAC;IACF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,oBAAoB,CAAC;QAC7B,SAAS,EAAE,uBAAuB,CAAC;KACpC,CAAC;IACF,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,SAAS,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;IACxD;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACxC,kBAAkB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C"}

package/package.json

@@ -9,7 +9,7 @@
     "liveness",
     "health-check"
   ],
-  "version": "1.0.5",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/terminus"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -44,15 +44,15 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/di": "^1.1.0",
-    "@fluojs/http": "^1.1.2",
-    "@fluojs/runtime": "^1.1.8"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/di": "^3.0.0",
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "peerDependencies": {
-    "@fluojs/drizzle": "^1.1.0",
-    "@fluojs/prisma": "^1.1.0",
-    "@fluojs/redis": "^1.0.2"
+    "@fluojs/drizzle": "^2.0.0",
+    "@fluojs/prisma": "^2.0.0",
+    "@fluojs/redis": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@fluojs/drizzle": {
@@ -66,8 +66,8 @@
     }
   },
   "devDependencies": {
-    "vitest": "^3.2.4",
-    "@fluojs/testing": "^1.0.6"
+    "vitest": "^4.1.11",
+    "@fluojs/testing": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",