@bymax-one/nest-core 1.6.7 → 1.6.8

package/dist/health/index.d.cts

@@ -49,8 +49,9 @@ interface HealthIndicatorResult {
     /** Whether the checked dependency is reachable and healthy. */
     status: 'up' | 'down';
     /**
-     * Optional diagnostic detail. Must never include secrets, connection
-     * strings, credentials, or a raw internal error object: only safe,
+     * Optional diagnostic detail, served in the readiness response only when
+     * `health.exposeIndicatorErrors` is on. Must never include secrets,
+     * connection strings, credentials, or a raw internal error object: only safe,
      * human-readable fields belong here.
      */
     details?: Record<string, unknown>;
@@ -66,11 +67,13 @@ interface IHealthIndicator {
     /**
      * Perform the check.
      *
+     * @param signal - Aborted when the aggregator stops waiting for this check. An indicator that
+     *   can cancel its query should pass it on; one that cannot may ignore it.
      * @returns The indicator's outcome.
      * @throws Any error; a rejection is converted to a `down` entry by the
      *   aggregator and never propagates to the caller.
      */
-    check(): Promise<HealthIndicatorResult>;
+    check(signal?: AbortSignal): Promise<HealthIndicatorResult>;
 }
 /**
  * One entry in a {@link HealthResponse.checks} array: an indicator's result,

package/dist/health/index.d.ts

@@ -49,8 +49,9 @@ interface HealthIndicatorResult {
     /** Whether the checked dependency is reachable and healthy. */
     status: 'up' | 'down';
     /**
-     * Optional diagnostic detail. Must never include secrets, connection
-     * strings, credentials, or a raw internal error object: only safe,
+     * Optional diagnostic detail, served in the readiness response only when
+     * `health.exposeIndicatorErrors` is on. Must never include secrets,
+     * connection strings, credentials, or a raw internal error object: only safe,
      * human-readable fields belong here.
      */
     details?: Record<string, unknown>;
@@ -66,11 +67,13 @@ interface IHealthIndicator {
     /**
      * Perform the check.
      *
+     * @param signal - Aborted when the aggregator stops waiting for this check. An indicator that
+     *   can cancel its query should pass it on; one that cannot may ignore it.
      * @returns The indicator's outcome.
      * @throws Any error; a rejection is converted to a `down` entry by the
      *   aggregator and never propagates to the caller.
      */
-    check(): Promise<HealthIndicatorResult>;
+    check(signal?: AbortSignal): Promise<HealthIndicatorResult>;
 }
 /**
  * One entry in a {@link HealthResponse.checks} array: an indicator's result,

package/dist/http/index.cjs

@@ -29,6 +29,21 @@ function assertPositiveInteger(name, value) {
     throw new Error(`${name} must be a positive integer, received ${String(value)}`);
   }
 }
+function assertBootstrapState(express) {
+  if (express.getHttpAdapter().getType?.() !== "express") {
+    throw new Error("applyHttpFloors supports the Express adapter only");
+  }
+  const server = express.getHttpServer();
+  if (server.listening) {
+    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
+  }
+  if (express.isInitialized === true) {
+    throw new Error(
+      "applyHttpFloors must run before app.init(): the application is already initialised"
+    );
+  }
+  return server;
+}
 async function applyHttpFloors(app, options = {}) {
   const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
   const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -42,13 +57,7 @@ async function applyHttpFloors(app, options = {}) {
   const checkingIntervalMs = options.connectionsCheckingIntervalMs ?? Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs);
   assertPositiveInteger("connectionsCheckingIntervalMs", checkingIntervalMs);
   const express = app;
-  if (express.getHttpAdapter().getType?.() !== "express") {
-    throw new Error("applyHttpFloors supports the Express adapter only");
-  }
-  const server = express.getHttpServer();
-  if (server.listening) {
-    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
-  }
+  const server = assertBootstrapState(express);
   const given = options.helmet ?? {};
   if (given !== false) {
     const helmet = await loadHelmet();

package/dist/http/index.d.cts

@@ -5,7 +5,7 @@ import { INestApplication } from '@nestjs/common';
  * tune per deployment: security headers without HSTS, compressed request bodies refused, and
  * timeouts that bound how long a client may hold a socket, enforced to within a second.
  *
- * Order is part of the contract. Call it right after the access log is installed
+ * Order is part of the contract. Call it before `app.init()`, right after the access log is installed
  * (`applyAccessLog` from `@bymax-one/nest-logger`) and before anything that reads the request:
  * helmet is mounted first so even a request the body parsers refuse carries the headers, and the
  * parsers are registered here so Nest's defaults (which accept gzip) are not. Cookie parsing, the

package/dist/http/index.d.ts

@@ -5,7 +5,7 @@ import { INestApplication } from '@nestjs/common';
  * tune per deployment: security headers without HSTS, compressed request bodies refused, and
  * timeouts that bound how long a client may hold a socket, enforced to within a second.
  *
- * Order is part of the contract. Call it right after the access log is installed
+ * Order is part of the contract. Call it before `app.init()`, right after the access log is installed
  * (`applyAccessLog` from `@bymax-one/nest-logger`) and before anything that reads the request:
  * helmet is mounted first so even a request the body parsers refuse carries the headers, and the
  * parsers are registered here so Nest's defaults (which accept gzip) are not. Cookie parsing, the

package/dist/http/index.mjs

@@ -27,6 +27,21 @@ function assertPositiveInteger(name, value) {
     throw new Error(`${name} must be a positive integer, received ${String(value)}`);
   }
 }
+function assertBootstrapState(express) {
+  if (express.getHttpAdapter().getType?.() !== "express") {
+    throw new Error("applyHttpFloors supports the Express adapter only");
+  }
+  const server = express.getHttpServer();
+  if (server.listening) {
+    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
+  }
+  if (express.isInitialized === true) {
+    throw new Error(
+      "applyHttpFloors must run before app.init(): the application is already initialised"
+    );
+  }
+  return server;
+}
 async function applyHttpFloors(app, options = {}) {
   const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
   const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -40,13 +55,7 @@ async function applyHttpFloors(app, options = {}) {
   const checkingIntervalMs = options.connectionsCheckingIntervalMs ?? Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs);
   assertPositiveInteger("connectionsCheckingIntervalMs", checkingIntervalMs);
   const express = app;
-  if (express.getHttpAdapter().getType?.() !== "express") {
-    throw new Error("applyHttpFloors supports the Express adapter only");
-  }
-  const server = express.getHttpServer();
-  if (server.listening) {
-    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
-  }
+  const server = assertBootstrapState(express);
   const given = options.helmet ?? {};
   if (given !== false) {
     const helmet = await loadHelmet();

package/dist/index.cjs

@@ -86,12 +86,19 @@ function codeForStatus(status) {
 
 // src/body-depth/body-depth.middleware.ts
 var BODY_TOO_DEEP_MESSAGE = "Request body is nested too deeply";
+function isContainer(node) {
+  if (typeof node !== "object" || node === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(node);
+  return Array.isArray(node) || proto === Object.prototype || proto === null;
+}
 function exceedsDepth(value, maxDepth) {
   let level = [value];
   for (let depth = 0; level.length > 0; depth += 1) {
     const next = [];
     for (const node of level) {
-      if (typeof node === "object" && node !== null) {
+      if (isContainer(node)) {
         if (depth >= maxDepth) {
           return true;
         }
@@ -148,6 +155,8 @@ function runtimeEnvironmentName(declared) {
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
+var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+var DEFAULT_READINESS_CACHE_MS = 1e3;
 var DEFAULT_OPENAPI_PATH = "docs";
 var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
 var DEFAULT_OPENAPI_TITLE = "API";
@@ -167,27 +176,48 @@ function resolveEnvelope(raw) {
     exposeInternals: raw?.exposeInternals ?? false
   };
 }
+function positiveSafeInteger(name, value, max) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive safe integer, received ${String(value)}`);
+  }
+  if (max !== void 0 && value > max) {
+    throw new Error(`${name} must be a positive integer of at most ${max}, received ${value}`);
+  }
+  return value;
+}
 function resolveTiming(raw) {
   const enabled = raw?.enabled ?? true;
   const threshold = raw?.slowRequestThresholdMs;
-  return threshold === void 0 ? { enabled } : { enabled, slowRequestThresholdMs: threshold };
+  return threshold === void 0 ? { enabled } : {
+    enabled,
+    slowRequestThresholdMs: positiveSafeInteger("timing.slowRequestThresholdMs", threshold)
+  };
 }
 var DEFAULT_MAX_BODY_DEPTH = 32;
 function resolveBodyDepth(raw) {
-  const maxDepth = raw?.maxDepth ?? DEFAULT_MAX_BODY_DEPTH;
-  if (!Number.isSafeInteger(maxDepth) || maxDepth < 1) {
-    throw new Error(
-      `bodyDepth.maxDepth must be a positive safe integer, received ${String(maxDepth)}`
-    );
-  }
+  const maxDepth = positiveSafeInteger(
+    "bodyDepth.maxDepth",
+    raw?.maxDepth ?? DEFAULT_MAX_BODY_DEPTH
+  );
   return { enabled: raw?.enabled ?? false, maxDepth };
 }
 function resolveHealth(raw) {
+  const readinessCacheMs = raw?.readinessCacheMs ?? DEFAULT_READINESS_CACHE_MS;
+  if (!Number.isSafeInteger(readinessCacheMs) || readinessCacheMs < 0) {
+    throw new Error(
+      `health.readinessCacheMs must be a non-negative safe integer, received ${String(readinessCacheMs)}`
+    );
+  }
   return {
+    readinessCacheMs,
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
     exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
-    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+    indicatorTimeoutMs: positiveSafeInteger(
+      "health.indicatorTimeoutMs",
+      raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+      MAX_TIMER_DELAY_MS
+    ),
     autoDiscover: raw?.autoDiscover ?? false
   };
 }
@@ -846,10 +876,12 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs, exposeErrors) {
+function startTimeout(indicator, timeoutMs) {
+  const controller = new AbortController();
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
+      controller.abort();
       resolve({
         entry: { name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } },
         isUp: false,
@@ -857,8 +889,12 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
       });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => {
-    const entry = { ...result, name: indicator.name };
+  return { signal: controller.signal, timedOut, clear: () => clearTimeout(timer) };
+}
+async function runIndicator(indicator, timeoutMs, exposeErrors) {
+  const { signal, timedOut, clear } = startTimeout(indicator, timeoutMs);
+  const checked = Promise.resolve().then(() => indicator.check(signal)).then((result) => {
+    const entry = exposeErrors ? { ...result, name: indicator.name } : { name: indicator.name, status: result.status };
     return result.status === "up" ? { entry, isUp: true } : { entry, isUp: false, cause: { kind: "reported-down" } };
   }).catch((reason) => {
     const message = summarizeRejection(reason);
@@ -871,7 +907,7 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
-    clearTimeout(timer);
+    clear();
   }
 }
 function describeCause(cause) {
@@ -931,6 +967,8 @@ var HealthService = class {
      * Comparing states alone would then let the stale observation win.
      */
     this.probeSequence = 0;
+    /** Set once shutdown begins, after which readiness answers not ready without running anything. */
+    this.draining = false;
   }
   /**
    * Report one check's current state, emitting only when it differs from the
@@ -1103,6 +1141,14 @@ var HealthService = class {
     );
     return this.effectiveIndicators;
   }
+  /**
+   * Stop reporting ready the moment shutdown begins, so a load balancer stops routing here while
+   * the process drains. Nothing cached or in progress is consulted again: every later probe is answered
+   * before either is read.
+   */
+  beforeApplicationShutdown() {
+    this.draining = true;
+  }
   /**
    * Liveness check: the process is up and able to respond. Runs no
    * indicators, so it never depends on the health of anything else.
@@ -1117,9 +1163,33 @@ var HealthService = class {
    * aggregate the results. `status` is `'ok'` only when every indicator
    * reports `up`; an empty indicator list is vacuously `'ok'`.
    *
+   * Probes share the work: one that arrives while a run is in progress awaits it, and for
+   * `health.readinessCacheMs` after it ends the answer is returned without running anything.
+   * The endpoint is usually unauthenticated, so probe volume must not set dependency volume.
+   * Once shutdown has begun the answer is always not ready. The returned object is shared between
+   * callers and must not be mutated.
+   *
    * @returns The aggregated health response.
    */
-  async checkReadiness() {
+  checkReadiness() {
+    if (this.draining) {
+      return Promise.resolve({ status: "error", checks: [{ name: "shutdown", status: "down" }] });
+    }
+    const cached = this.cached;
+    if (cached !== void 0 && performance.now() - cached.at < this.options.health.readinessCacheMs) {
+      return Promise.resolve(cached.response);
+    }
+    this.inflight ??= this.runReadiness().finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  /**
+   * Run every indicator once and record the answer.
+   *
+   * @returns The aggregated health response.
+   */
+  async runReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
     const exposeErrors = this.options.health.exposeIndicatorErrors;
     const seq = ++this.probeSequence;
@@ -1131,7 +1201,9 @@ var HealthService = class {
     }
     const checks = outcomes.map((outcome) => outcome.entry);
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
-    return { status, checks };
+    const response = { status, checks };
+    this.cached = { at: performance.now(), response };
+    return response;
   }
 };
 HealthService = __decorateClass([

package/dist/index.d.cts

@@ -19,7 +19,7 @@ interface EnvelopeOptions {
 interface TimingOptions {
     /** Register the request-timing middleware (`BymaxTimingMiddleware`). Default: `true`. */
     enabled?: boolean;
-    /** Samples above this threshold are flagged as slow. No default (unset). */
+    /** Samples above this threshold are flagged as slow. Positive integer. No default (unset). */
     slowRequestThresholdMs?: number;
 }
 /** Request-body nesting limit, applied before the application's own validation runs. */
@@ -47,8 +47,17 @@ interface HealthOptions {
     enabled?: boolean;
     /** Route prefix for the health endpoints. Default: `'health'`. */
     path?: string;
-    /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
+    /** Per-indicator timeout before a check is reported as down. Positive integer up to 2147483647. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * How long a finished readiness answer is reused, in milliseconds. `0` turns the cache off.
+     * Default: `1000`.
+     *
+     * Readiness is usually reachable without credentials, and every probe would otherwise reach
+     * every dependency. Probes that arrive while one is running always share it, whatever this is set to;
+     * this is only how long its answer outlives it.
+     */
+    readinessCacheMs?: number;
     /**
      * Aggregate every provider marked with `@BymaxHealthIndicator()`, anywhere in
      * the application, in addition to those registered under
@@ -62,15 +71,16 @@ interface HealthOptions {
      */
     autoDiscover?: boolean;
     /**
-     * Include the failing indicator's message in the readiness response under
-     * `details.error`. Never enable in production. Default: `false`.
+     * Serve what an indicator returned in `details`, and the failing indicator's
+     * message under `details.error`, in the readiness response. Never enable in
+     * production. Default: `false`.
      *
      * Readiness is typically unauthenticated and reachable by whatever probes it,
      * and an indicator usually does not author its own failure message — it lets a
      * driver's error propagate, and driver errors carry hosts, ports and sometimes
-     * credentials. With this off, the response names which indicator is down and
-     * nothing else; the message goes to the logger, where access is already
-     * controlled.
+     * credentials. With this off, the response carries each indicator's name and
+     * status and nothing else, except the timeout the aggregator itself reports;
+     * the message goes to the logger, where access is already controlled.
      */
     exposeIndicatorErrors?: boolean;
 }
@@ -339,6 +349,7 @@ interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    readinessCacheMs: number;
     exposeIndicatorErrors: boolean;
     autoDiscover: boolean;
 }

package/dist/index.d.ts

@@ -19,7 +19,7 @@ interface EnvelopeOptions {
 interface TimingOptions {
     /** Register the request-timing middleware (`BymaxTimingMiddleware`). Default: `true`. */
     enabled?: boolean;
-    /** Samples above this threshold are flagged as slow. No default (unset). */
+    /** Samples above this threshold are flagged as slow. Positive integer. No default (unset). */
     slowRequestThresholdMs?: number;
 }
 /** Request-body nesting limit, applied before the application's own validation runs. */
@@ -47,8 +47,17 @@ interface HealthOptions {
     enabled?: boolean;
     /** Route prefix for the health endpoints. Default: `'health'`. */
     path?: string;
-    /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
+    /** Per-indicator timeout before a check is reported as down. Positive integer up to 2147483647. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * How long a finished readiness answer is reused, in milliseconds. `0` turns the cache off.
+     * Default: `1000`.
+     *
+     * Readiness is usually reachable without credentials, and every probe would otherwise reach
+     * every dependency. Probes that arrive while one is running always share it, whatever this is set to;
+     * this is only how long its answer outlives it.
+     */
+    readinessCacheMs?: number;
     /**
      * Aggregate every provider marked with `@BymaxHealthIndicator()`, anywhere in
      * the application, in addition to those registered under
@@ -62,15 +71,16 @@ interface HealthOptions {
      */
     autoDiscover?: boolean;
     /**
-     * Include the failing indicator's message in the readiness response under
-     * `details.error`. Never enable in production. Default: `false`.
+     * Serve what an indicator returned in `details`, and the failing indicator's
+     * message under `details.error`, in the readiness response. Never enable in
+     * production. Default: `false`.
      *
      * Readiness is typically unauthenticated and reachable by whatever probes it,
      * and an indicator usually does not author its own failure message — it lets a
      * driver's error propagate, and driver errors carry hosts, ports and sometimes
-     * credentials. With this off, the response names which indicator is down and
-     * nothing else; the message goes to the logger, where access is already
-     * controlled.
+     * credentials. With this off, the response carries each indicator's name and
+     * status and nothing else, except the timeout the aggregator itself reports;
+     * the message goes to the logger, where access is already controlled.
      */
     exposeIndicatorErrors?: boolean;
 }
@@ -339,6 +349,7 @@ interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    readinessCacheMs: number;
     exposeIndicatorErrors: boolean;
     autoDiscover: boolean;
 }

package/dist/index.mjs

@@ -84,12 +84,19 @@ function codeForStatus(status) {
 
 // src/body-depth/body-depth.middleware.ts
 var BODY_TOO_DEEP_MESSAGE = "Request body is nested too deeply";
+function isContainer(node) {
+  if (typeof node !== "object" || node === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(node);
+  return Array.isArray(node) || proto === Object.prototype || proto === null;
+}
 function exceedsDepth(value, maxDepth) {
   let level = [value];
   for (let depth = 0; level.length > 0; depth += 1) {
     const next = [];
     for (const node of level) {
-      if (typeof node === "object" && node !== null) {
+      if (isContainer(node)) {
         if (depth >= maxDepth) {
           return true;
         }
@@ -146,6 +153,8 @@ function runtimeEnvironmentName(declared) {
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
+var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+var DEFAULT_READINESS_CACHE_MS = 1e3;
 var DEFAULT_OPENAPI_PATH = "docs";
 var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
 var DEFAULT_OPENAPI_TITLE = "API";
@@ -165,27 +174,48 @@ function resolveEnvelope(raw) {
     exposeInternals: raw?.exposeInternals ?? false
   };
 }
+function positiveSafeInteger(name, value, max) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive safe integer, received ${String(value)}`);
+  }
+  if (max !== void 0 && value > max) {
+    throw new Error(`${name} must be a positive integer of at most ${max}, received ${value}`);
+  }
+  return value;
+}
 function resolveTiming(raw) {
   const enabled = raw?.enabled ?? true;
   const threshold = raw?.slowRequestThresholdMs;
-  return threshold === void 0 ? { enabled } : { enabled, slowRequestThresholdMs: threshold };
+  return threshold === void 0 ? { enabled } : {
+    enabled,
+    slowRequestThresholdMs: positiveSafeInteger("timing.slowRequestThresholdMs", threshold)
+  };
 }
 var DEFAULT_MAX_BODY_DEPTH = 32;
 function resolveBodyDepth(raw) {
-  const maxDepth = raw?.maxDepth ?? DEFAULT_MAX_BODY_DEPTH;
-  if (!Number.isSafeInteger(maxDepth) || maxDepth < 1) {
-    throw new Error(
-      `bodyDepth.maxDepth must be a positive safe integer, received ${String(maxDepth)}`
-    );
-  }
+  const maxDepth = positiveSafeInteger(
+    "bodyDepth.maxDepth",
+    raw?.maxDepth ?? DEFAULT_MAX_BODY_DEPTH
+  );
   return { enabled: raw?.enabled ?? false, maxDepth };
 }
 function resolveHealth(raw) {
+  const readinessCacheMs = raw?.readinessCacheMs ?? DEFAULT_READINESS_CACHE_MS;
+  if (!Number.isSafeInteger(readinessCacheMs) || readinessCacheMs < 0) {
+    throw new Error(
+      `health.readinessCacheMs must be a non-negative safe integer, received ${String(readinessCacheMs)}`
+    );
+  }
   return {
+    readinessCacheMs,
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
     exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
-    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+    indicatorTimeoutMs: positiveSafeInteger(
+      "health.indicatorTimeoutMs",
+      raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+      MAX_TIMER_DELAY_MS
+    ),
     autoDiscover: raw?.autoDiscover ?? false
   };
 }
@@ -844,10 +874,12 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs, exposeErrors) {
+function startTimeout(indicator, timeoutMs) {
+  const controller = new AbortController();
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
+      controller.abort();
       resolve({
         entry: { name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } },
         isUp: false,
@@ -855,8 +887,12 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
       });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => {
-    const entry = { ...result, name: indicator.name };
+  return { signal: controller.signal, timedOut, clear: () => clearTimeout(timer) };
+}
+async function runIndicator(indicator, timeoutMs, exposeErrors) {
+  const { signal, timedOut, clear } = startTimeout(indicator, timeoutMs);
+  const checked = Promise.resolve().then(() => indicator.check(signal)).then((result) => {
+    const entry = exposeErrors ? { ...result, name: indicator.name } : { name: indicator.name, status: result.status };
     return result.status === "up" ? { entry, isUp: true } : { entry, isUp: false, cause: { kind: "reported-down" } };
   }).catch((reason) => {
     const message = summarizeRejection(reason);
@@ -869,7 +905,7 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
-    clearTimeout(timer);
+    clear();
   }
 }
 function describeCause(cause) {
@@ -929,6 +965,8 @@ var HealthService = class {
      * Comparing states alone would then let the stale observation win.
      */
     this.probeSequence = 0;
+    /** Set once shutdown begins, after which readiness answers not ready without running anything. */
+    this.draining = false;
   }
   /**
    * Report one check's current state, emitting only when it differs from the
@@ -1101,6 +1139,14 @@ var HealthService = class {
     );
     return this.effectiveIndicators;
   }
+  /**
+   * Stop reporting ready the moment shutdown begins, so a load balancer stops routing here while
+   * the process drains. Nothing cached or in progress is consulted again: every later probe is answered
+   * before either is read.
+   */
+  beforeApplicationShutdown() {
+    this.draining = true;
+  }
   /**
    * Liveness check: the process is up and able to respond. Runs no
    * indicators, so it never depends on the health of anything else.
@@ -1115,9 +1161,33 @@ var HealthService = class {
    * aggregate the results. `status` is `'ok'` only when every indicator
    * reports `up`; an empty indicator list is vacuously `'ok'`.
    *
+   * Probes share the work: one that arrives while a run is in progress awaits it, and for
+   * `health.readinessCacheMs` after it ends the answer is returned without running anything.
+   * The endpoint is usually unauthenticated, so probe volume must not set dependency volume.
+   * Once shutdown has begun the answer is always not ready. The returned object is shared between
+   * callers and must not be mutated.
+   *
    * @returns The aggregated health response.
    */
-  async checkReadiness() {
+  checkReadiness() {
+    if (this.draining) {
+      return Promise.resolve({ status: "error", checks: [{ name: "shutdown", status: "down" }] });
+    }
+    const cached = this.cached;
+    if (cached !== void 0 && performance.now() - cached.at < this.options.health.readinessCacheMs) {
+      return Promise.resolve(cached.response);
+    }
+    this.inflight ??= this.runReadiness().finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  /**
+   * Run every indicator once and record the answer.
+   *
+   * @returns The aggregated health response.
+   */
+  async runReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
     const exposeErrors = this.options.health.exposeIndicatorErrors;
     const seq = ++this.probeSequence;
@@ -1129,7 +1199,9 @@ var HealthService = class {
     }
     const checks = outcomes.map((outcome) => outcome.entry);
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
-    return { status, checks };
+    const response = { status, checks };
+    this.cached = { at: performance.now(), response };
+    return response;
   }
 };
 HealthService = __decorateClass([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.6.7",
+  "version": "1.6.8",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing middleware, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",