@bymax-one/nest-core 1.0.0

package/dist/index.mjs

@@ -0,0 +1,960 @@
+import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Get, Res, Controller, HttpStatus } from '@nestjs/common';
+import { HttpAdapterHost, BaseExceptionFilter, APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
+import { tap, catchError, throwError } from 'rxjs';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/core.options.ts
+var DEFAULT_HEALTH_PATH = "health";
+var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
+var DEFAULT_METRICS_PATH = "metrics";
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+  }
+  return value;
+}
+function resolveEnvelope(raw) {
+  return {
+    enabled: raw?.enabled ?? true,
+    exposeInternals: raw?.exposeInternals ?? false
+  };
+}
+function resolveTiming(raw) {
+  const enabled = raw?.enabled ?? true;
+  const threshold = raw?.slowRequestThresholdMs;
+  return threshold === void 0 ? { enabled } : { enabled, slowRequestThresholdMs: threshold };
+}
+function resolveHealth(raw) {
+  return {
+    enabled: raw?.enabled ?? true,
+    path: raw?.path ?? DEFAULT_HEALTH_PATH,
+    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS
+  };
+}
+function resolveMetrics(raw) {
+  return {
+    enabled: raw?.enabled ?? false,
+    path: raw?.path ?? DEFAULT_METRICS_PATH,
+    collectDefaultMetrics: raw?.collectDefaultMetrics ?? true,
+    defaultLabels: { ...raw?.defaultLabels ?? {} }
+  };
+}
+function normalizeCoreOptions(raw) {
+  return deepFreeze({
+    envelope: resolveEnvelope(raw?.envelope),
+    timing: resolveTiming(raw?.timing),
+    health: resolveHealth(raw?.health),
+    metrics: resolveMetrics(raw?.metrics)
+  });
+}
+normalizeCoreOptions();
+
+// src/core.tokens.ts
+var BYMAX_CORE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_CORE_OPTIONS");
+var BYMAX_CORRELATION_PROVIDER = /* @__PURE__ */ Symbol("BYMAX_CORRELATION_PROVIDER");
+var BYMAX_TIMING_SINK = /* @__PURE__ */ Symbol("BYMAX_TIMING_SINK");
+var BYMAX_HEALTH_INDICATORS = /* @__PURE__ */ Symbol("BYMAX_HEALTH_INDICATORS");
+var BYMAX_METRICS_REGISTRY = /* @__PURE__ */ Symbol("BYMAX_METRICS_REGISTRY");
+
+// src/timing/timing.clock.ts
+var DEFAULT_MONOTONIC_CLOCK = {
+  now: () => performance.now()
+};
+var BYMAX_TIMING_CLOCK = /* @__PURE__ */ Symbol("BYMAX_TIMING_CLOCK");
+
+// src/defaults.providers.ts
+var NoopCorrelationIdProvider = class {
+  /**
+   * Resolve no correlation id.
+   *
+   * @returns Always `undefined`.
+   */
+  getCorrelationId() {
+    return void 0;
+  }
+};
+var NoopTimingSink = class {
+  /**
+   * Discard the sample.
+   *
+   * @param _sample - The sample to discard.
+   */
+  record(_sample) {
+  }
+};
+function buildDefaultProviders() {
+  return [{ provide: BYMAX_TIMING_CLOCK, useValue: DEFAULT_MONOTONIC_CLOCK }];
+}
+
+// src/envelope/error-codes.ts
+var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
+var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
+var BYMAX_UNAUTHORIZED = "BYMAX_UNAUTHORIZED";
+var BYMAX_FORBIDDEN = "BYMAX_FORBIDDEN";
+var BYMAX_NOT_FOUND = "BYMAX_NOT_FOUND";
+var BYMAX_CONFLICT = "BYMAX_CONFLICT";
+var BYMAX_PAYLOAD_TOO_LARGE = "BYMAX_PAYLOAD_TOO_LARGE";
+var BYMAX_UNSUPPORTED_MEDIA_TYPE = "BYMAX_UNSUPPORTED_MEDIA_TYPE";
+var BYMAX_UNPROCESSABLE_ENTITY = "BYMAX_UNPROCESSABLE_ENTITY";
+var BYMAX_TOO_MANY_REQUESTS = "BYMAX_TOO_MANY_REQUESTS";
+var BYMAX_CLIENT_ERROR = "BYMAX_CLIENT_ERROR";
+var BYMAX_INTERNAL_ERROR = "BYMAX_INTERNAL_ERROR";
+var BYMAX_NOT_IMPLEMENTED = "BYMAX_NOT_IMPLEMENTED";
+var BYMAX_BAD_GATEWAY = "BYMAX_BAD_GATEWAY";
+var BYMAX_SERVICE_UNAVAILABLE = "BYMAX_SERVICE_UNAVAILABLE";
+var BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
+var STATUS_CODES = /* @__PURE__ */ new Map([
+  [400, BYMAX_BAD_REQUEST],
+  [401, BYMAX_UNAUTHORIZED],
+  [403, BYMAX_FORBIDDEN],
+  [404, BYMAX_NOT_FOUND],
+  [409, BYMAX_CONFLICT],
+  [413, BYMAX_PAYLOAD_TOO_LARGE],
+  [415, BYMAX_UNSUPPORTED_MEDIA_TYPE],
+  [422, BYMAX_UNPROCESSABLE_ENTITY],
+  [429, BYMAX_TOO_MANY_REQUESTS],
+  [500, BYMAX_INTERNAL_ERROR],
+  [501, BYMAX_NOT_IMPLEMENTED],
+  [502, BYMAX_BAD_GATEWAY],
+  [503, BYMAX_SERVICE_UNAVAILABLE],
+  [504, BYMAX_GATEWAY_TIMEOUT]
+]);
+var CLIENT_ERROR_MIN = 400;
+var CLIENT_ERROR_MAX = 500;
+function codeForStatus(status) {
+  const catalogued = STATUS_CODES.get(status);
+  if (catalogued !== void 0) {
+    return catalogued;
+  }
+  if (status >= CLIENT_ERROR_MIN && status < CLIENT_ERROR_MAX) {
+    return BYMAX_CLIENT_ERROR;
+  }
+  return BYMAX_INTERNAL_ERROR;
+}
+
+// src/envelope/error-envelope.ts
+function buildErrorEnvelope(input) {
+  const base = {
+    statusCode: input.statusCode,
+    code: input.code,
+    message: input.message,
+    timestamp: input.now().toISOString(),
+    path: input.path
+  };
+  return {
+    ...base,
+    ...input.details !== void 0 ? { details: input.details } : {},
+    ...input.correlationId !== void 0 ? { correlationId: input.correlationId } : {}
+  };
+}
+
+// src/envelope/exception.filter.ts
+var INTERNAL_ERROR_STATUS = 500;
+var INTERNAL_ERROR_MESSAGE = "Internal server error";
+var VALIDATION_FAILED_MESSAGE = "Validation failed";
+function extractExplicitCode(response) {
+  if (typeof response !== "object" || response === null || !("code" in response)) {
+    return void 0;
+  }
+  const code = response.code;
+  return typeof code === "string" ? code : void 0;
+}
+function isValidationResponse(response) {
+  return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
+}
+function toValidationDetails(violations) {
+  return violations.map(
+    (violation) => typeof violation === "string" ? { issue: violation } : violation
+  );
+}
+function extractHttpMessage(response, exception) {
+  if (typeof response === "string") {
+    return response;
+  }
+  if (typeof response === "object" && response !== null && "message" in response) {
+    const message = response.message;
+    if (typeof message === "string") {
+      return message;
+    }
+  }
+  return exception.message;
+}
+function buildInternalDetails(exception) {
+  if (exception instanceof Error) {
+    return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+  }
+  return { message: String(exception) };
+}
+var BymaxExceptionFilter = class {
+  /**
+   * @param options - Resolved core options; drives the `exposeInternals` switch.
+   * @param correlation - Provider resolving the current request's correlation id.
+   *   Injected with `@Optional()`: `BymaxCoreModule` binds no local default for
+   *   this token, so a consumer's own `BYMAX_CORRELATION_PROVIDER` binding
+   *   (from their own, globally-visible module) is not shadowed by one; when
+   *   nothing is bound, this falls back to a no-op that omits `correlationId`.
+   * @param adapterHost - Host of the live HTTP adapter, resolved lazily per catch.
+   */
+  constructor(options, correlation, adapterHost) {
+    this.options = options;
+    this.adapterHost = adapterHost;
+    /** Clock used to stamp the envelope timestamp; overridable in tests via fake timers. */
+    this.now = () => /* @__PURE__ */ new Date();
+    this.correlation = correlation ?? new NoopCorrelationIdProvider();
+  }
+  /**
+   * Format the exception into the stable envelope and reply with it.
+   *
+   * Non-HTTP execution contexts (GraphQL, RPC) are out of scope and are
+   * rethrown untouched so their own error handling applies.
+   *
+   * @param exception - The error that escaped the handler.
+   * @param host - The arguments host for the current execution context.
+   */
+  catch(exception, host) {
+    if (host.getType() !== "http") {
+      throw exception;
+    }
+    const { httpAdapter } = this.adapterHost;
+    const ctx = host.switchToHttp();
+    const request = ctx.getRequest();
+    const response = ctx.getResponse();
+    const correlationId = this.correlation.getCorrelationId();
+    const context = {
+      method: String(httpAdapter.getRequestMethod(request)),
+      path: String(httpAdapter.getRequestUrl(request)),
+      ...correlationId !== void 0 ? { correlationId } : {}
+    };
+    const envelope = this.buildEnvelope(exception, context);
+    httpAdapter.reply(response, envelope, envelope.statusCode);
+  }
+  /**
+   * Select the mapping rule for the exception and build its envelope. An
+   * unknown error is handed to the observability seam before it collapses, so
+   * an integration can record the original error with the request context.
+   *
+   * @param exception - The error that escaped the handler.
+   * @param context - The neutral request context.
+   * @returns The formatted envelope.
+   */
+  buildEnvelope(exception, context) {
+    if (exception instanceof HttpException) {
+      return this.mapHttpException(exception, context);
+    }
+    try {
+      this.onUnexpectedError(exception, context);
+    } catch {
+    }
+    return this.mapUnknown(exception, context);
+  }
+  /**
+   * Map an `HttpException` to the envelope. Explicit domain codes pass through;
+   * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
+   * details; everything else derives its code from the status.
+   *
+   * @param exception - The HTTP exception to format.
+   * @param context - The neutral request context.
+   * @returns The formatted envelope.
+   */
+  mapHttpException(exception, context) {
+    const status = exception.getStatus();
+    const response = exception.getResponse();
+    const explicitCode = extractExplicitCode(response);
+    if (explicitCode !== void 0) {
+      return this.toEnvelope(status, explicitCode, extractHttpMessage(response, exception), context);
+    }
+    if (isValidationResponse(response)) {
+      return this.toEnvelope(
+        status,
+        BYMAX_VALIDATION_FAILED,
+        VALIDATION_FAILED_MESSAGE,
+        context,
+        toValidationDetails(response.message)
+      );
+    }
+    return this.toEnvelope(
+      status,
+      codeForStatus(status),
+      extractHttpMessage(response, exception),
+      context
+    );
+  }
+  /**
+   * Collapse an unknown error to the fixed, production-safe 500. The original
+   * error is never serialized unless `exposeInternals` is on, in which case its
+   * message and stack are attached to `details` (development only).
+   *
+   * @param exception - The original thrown value.
+   * @param context - The neutral request context.
+   * @returns The generic internal-error envelope.
+   */
+  mapUnknown(exception, context) {
+    const details = this.options.envelope.exposeInternals ? buildInternalDetails(exception) : void 0;
+    return this.toEnvelope(
+      INTERNAL_ERROR_STATUS,
+      BYMAX_INTERNAL_ERROR,
+      INTERNAL_ERROR_MESSAGE,
+      context,
+      details
+    );
+  }
+  /**
+   * Assemble the envelope through the pure builder, threading the shared clock
+   * and omitting absent optional details.
+   *
+   * @param statusCode - HTTP status for the envelope.
+   * @param code - Stable machine-readable code.
+   * @param message - Human-readable, end-user-safe message.
+   * @param context - The neutral request context.
+   * @param details - Optional structured context; omitted when absent.
+   * @returns The formatted envelope.
+   */
+  toEnvelope(statusCode, code, message, context, details) {
+    return buildErrorEnvelope({
+      statusCode,
+      code,
+      message,
+      path: context.path,
+      now: this.now,
+      ...details !== void 0 ? { details } : {},
+      ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {}
+    });
+  }
+  /**
+   * Observability seam invoked for every unexpected (non-`HttpException`) error
+   * before it collapses to the generic 500. The base implementation is a no-op:
+   * this library owns no logger. An integration (for example
+   * `@bymax-one/nest-logger`) subclasses the filter and overrides this to record
+   * the original error with the current request context and correlation id.
+   * Overrides must never throw and must never write to the response.
+   *
+   * @param _error - The original thrown value.
+   * @param _context - The neutral request context.
+   */
+  onUnexpectedError(_error, _context) {
+  }
+};
+BymaxExceptionFilter = __decorateClass([
+  Catch(),
+  __decorateParam(0, Inject(BYMAX_CORE_OPTIONS)),
+  __decorateParam(1, Optional()),
+  __decorateParam(1, Inject(BYMAX_CORRELATION_PROVIDER)),
+  __decorateParam(2, Inject(HttpAdapterHost))
+], BymaxExceptionFilter);
+
+// src/timing/request-info.accessor.ts
+function stripQueryString(rawUrl) {
+  const queryIndex = rawUrl.indexOf("?");
+  return queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+}
+function readExpressTemplate(request) {
+  const path = request.route?.path;
+  return path === void 0 ? void 0 : `${request.baseUrl ?? ""}${path}`;
+}
+function readFastifyTemplate(request) {
+  return request.routeOptions?.url;
+}
+function extractRequestInfo(context) {
+  const request = context.switchToHttp().getRequest();
+  const template = readExpressTemplate(request) ?? readFastifyTemplate(request);
+  const rawUrl = request.originalUrl ?? request.url ?? "";
+  return { method: request.method ?? "", route: template ?? stripQueryString(rawUrl) };
+}
+
+// src/timing/timing.interceptor.ts
+var DEFAULT_SUCCESS_STATUS = 200;
+var UNKNOWN_ERROR_STATUS = 500;
+var TimingInterceptor = class {
+  /**
+   * @param options - Resolved core options; supplies `slowRequestThresholdMs`.
+   * @param sink - The bound timing sink; its `record` failures are swallowed.
+   *   Injected with `@Optional()`: `BymaxCoreModule` binds no local default for
+   *   this token on the sync path when the metrics bridge is not registered, so
+   *   a consumer's own `BYMAX_TIMING_SINK` binding is not shadowed by one; when
+   *   nothing resolves, this falls back to a no-op sink.
+   * @param clock - Monotonic clock seam; defaults to `performance.now()`, and
+   *   is bound explicitly through {@link BYMAX_TIMING_CLOCK} so tests inject a
+   *   stub advancing by controlled amounts.
+   */
+  constructor(options, sink, clock = DEFAULT_MONOTONIC_CLOCK) {
+    this.options = options;
+    this.clock = clock;
+    this.sink = sink ?? new NoopTimingSink();
+  }
+  /**
+   * Measure the handler chain and record exactly one sample per completed
+   * request, on the success path and on the error path alike.
+   *
+   * @param context - The execution context of the current request.
+   * @param next - The next handler in the chain.
+   * @returns The downstream response stream, unmodified beyond the measurement.
+   */
+  intercept(context, next) {
+    if (context.getType() !== "http") {
+      return next.handle();
+    }
+    const start = this.clock.now();
+    const { method, route } = extractRequestInfo(context);
+    return next.handle().pipe(
+      tap({
+        complete: () => {
+          this.recordSample(method, route, this.readSuccessStatus(context), start);
+        }
+      }),
+      catchError((error) => {
+        this.recordSample(method, route, this.readErrorStatus(error), start);
+        return throwError(() => error);
+      })
+    );
+  }
+  /**
+   * Read the final status code from the response object on the success path.
+   *
+   * @param context - The execution context of the current request.
+   * @returns The response's status code, or the default success status when absent.
+   */
+  readSuccessStatus(context) {
+    const response = context.switchToHttp().getResponse();
+    return response.statusCode ?? DEFAULT_SUCCESS_STATUS;
+  }
+  /**
+   * Derive the final status code for an error that escaped the handler.
+   *
+   * @param error - The error propagated by the handler chain.
+   * @returns The `HttpException` status, or the generic 500 for anything else.
+   */
+  readErrorStatus(error) {
+    return error instanceof HttpException ? error.getStatus() : UNKNOWN_ERROR_STATUS;
+  }
+  /**
+   * Build the sample, compute the slow flag, and deliver it to the sink inside
+   * a try/catch that silences any failure: a throwing sink must never affect
+   * the request it is observing.
+   *
+   * @param method - HTTP method of the request.
+   * @param route - Route template of the request.
+   * @param statusCode - Final status code, success or error.
+   * @param start - Monotonic start timestamp captured before the handler ran.
+   */
+  recordSample(method, route, statusCode, start) {
+    const durationMs = this.clock.now() - start;
+    const threshold = this.options.timing.slowRequestThresholdMs;
+    const slow = threshold !== void 0 && durationMs > threshold;
+    const sample = { method, route, statusCode, durationMs, slow };
+    try {
+      this.sink.record(sample);
+    } catch {
+    }
+  }
+};
+TimingInterceptor = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CORE_OPTIONS)),
+  __decorateParam(1, Optional()),
+  __decorateParam(1, Inject(BYMAX_TIMING_SINK)),
+  __decorateParam(2, Inject(BYMAX_TIMING_CLOCK))
+], TimingInterceptor);
+
+// src/passthrough.providers.ts
+var PassThroughExceptionFilter = class {
+  constructor(adapterHost) {
+    this.adapterHost = adapterHost;
+  }
+  /**
+   * Format the exception exactly as Nest's default handler would.
+   *
+   * @param exception - The exception that escaped the handler.
+   * @param host - The arguments host for the current request.
+   */
+  catch(exception, host) {
+    this.delegate ??= new BaseExceptionFilter(this.adapterHost.httpAdapter);
+    this.delegate.catch(exception, host);
+  }
+};
+PassThroughExceptionFilter = __decorateClass([
+  Catch()
+], PassThroughExceptionFilter);
+var PassThroughInterceptor = class {
+  /**
+   * Forward the request to the next handler unchanged.
+   *
+   * @param _context - The execution context; unused by a transparent forwarder.
+   * @param next - The next handler in the chain.
+   * @returns The downstream response stream, unmodified.
+   */
+  intercept(_context, next) {
+    return next.handle();
+  }
+};
+function assertAsyncFeatureEnabled(feature, enabled) {
+  if (!enabled) {
+    throw new Error(
+      `[BymaxCoreModule] The "${feature}" controller was reached while the feature is disabled. On the forRootAsync path this controller is always registered because options resolve after the module is defined; enable "${feature}" in the resolved options, or do not expose this controller while the feature is disabled.`
+    );
+  }
+}
+function selectAsyncExceptionFilter(options, correlation, adapterHost) {
+  return options.envelope.enabled ? new BymaxExceptionFilter(options, correlation, adapterHost) : new PassThroughExceptionFilter(adapterHost);
+}
+function selectAsyncTimingInterceptor(options, sink, clock) {
+  return options.timing.enabled ? new TimingInterceptor(options, sink, clock) : new PassThroughInterceptor();
+}
+var MAX_ERROR_MESSAGE_LENGTH = 300;
+var TRUNCATION_ELLIPSIS = "...";
+function summarizeRejection(reason) {
+  let message;
+  try {
+    message = reason instanceof Error ? reason.message : String(reason);
+  } catch {
+    message = "Unknown error";
+  }
+  if (message.length <= MAX_ERROR_MESSAGE_LENGTH) {
+    return message;
+  }
+  return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
+}
+async function runIndicator(indicator, timeoutMs) {
+  let timer;
+  const timedOut = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      resolve({ name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } });
+    }, timeoutMs);
+  });
+  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => ({
+    name: indicator.name,
+    status: "down",
+    details: { error: summarizeRejection(reason) }
+  }));
+  try {
+    return await Promise.race([checked, timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var HealthService = class {
+  /**
+   * @param indicators - Every registered indicator; empty when none resolve.
+   *   Injected with `@Optional()`: `BymaxCoreModule` binds no local default for
+   *   this token, so a consumer's own `BYMAX_HEALTH_INDICATORS` binding (from
+   *   their own, globally-visible module) is not shadowed by one; when nothing
+   *   is bound, this defaults to an empty array.
+   * @param options - Resolved core options; supplies `indicatorTimeoutMs`.
+   */
+  constructor(indicators = [], options) {
+    this.indicators = indicators;
+    this.options = options;
+  }
+  /**
+   * Liveness check: the process is up and able to respond. Runs no
+   * indicators, so it never depends on the health of anything else.
+   *
+   * @returns The documented liveness shape: `{ status: 'ok', checks: [] }`.
+   */
+  checkLiveness() {
+    return { status: "ok", checks: [] };
+  }
+  /**
+   * Readiness check: run every registered indicator concurrently and
+   * aggregate the results. `status` is `'ok'` only when every indicator
+   * reports `up`; an empty indicator list is vacuously `'ok'`.
+   *
+   * @returns The aggregated health response.
+   */
+  async checkReadiness() {
+    const timeoutMs = this.options.health.indicatorTimeoutMs;
+    const checks = await Promise.all(
+      this.indicators.map((indicator) => runIndicator(indicator, timeoutMs))
+    );
+    const status = checks.every((check) => check.status === "up") ? "ok" : "error";
+    return { status, checks };
+  }
+};
+HealthService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Optional()),
+  __decorateParam(0, Inject(BYMAX_HEALTH_INDICATORS)),
+  __decorateParam(1, Inject(BYMAX_CORE_OPTIONS))
+], HealthService);
+
+// src/health/health.controller.ts
+function assertControllerMatchesOptions(options, registeredPath) {
+  assertAsyncFeatureEnabled("health", options.health.enabled);
+  if (options.health.path !== registeredPath) {
+    throw new Error(
+      `[BymaxCoreModule] The "health" controller is registered at "${registeredPath}" but the resolved options request "${options.health.path}". Route metadata is fixed before forRootAsync's options resolve, so a custom "health.path" is only honored through forRoot(); register synchronously, or keep the default "${DEFAULT_HEALTH_PATH}" prefix on the async path.`
+    );
+  }
+}
+function createHealthController(registeredPath) {
+  let HealthController = class {
+    /**
+     * @param healthService - The readiness and liveness aggregator.
+     * @param options - Resolved core options, used to guard consistency at request time.
+     * @param adapterHost - The live HTTP adapter, used to reply with a dynamic status.
+     */
+    constructor(healthService, options, adapterHost) {
+      this.healthService = healthService;
+      this.options = options;
+      this.adapterHost = adapterHost;
+    }
+    live() {
+      assertControllerMatchesOptions(this.options, registeredPath);
+      return this.healthService.checkLiveness();
+    }
+    async ready(response) {
+      assertControllerMatchesOptions(this.options, registeredPath);
+      const result = await this.healthService.checkReadiness();
+      const status = result.status === "ok" ? HttpStatus.OK : HttpStatus.SERVICE_UNAVAILABLE;
+      this.adapterHost.httpAdapter.reply(response, result, status);
+    }
+  };
+  __decorateClass([
+    Get("live")
+  ], HealthController.prototype, "live", 1);
+  __decorateClass([
+    Get("ready"),
+    __decorateParam(0, Res())
+  ], HealthController.prototype, "ready", 1);
+  HealthController = __decorateClass([
+    Controller(registeredPath),
+    __decorateParam(0, Inject(HealthService)),
+    __decorateParam(1, Inject(BYMAX_CORE_OPTIONS)),
+    __decorateParam(2, Inject(HttpAdapterHost))
+  ], HealthController);
+  return HealthController;
+}
+function assertControllerMatchesOptions2(options, registeredPath) {
+  assertAsyncFeatureEnabled("metrics", options.metrics.enabled);
+  if (options.metrics.path !== registeredPath) {
+    throw new Error(
+      `[BymaxCoreModule] The "metrics" controller is registered at "${registeredPath}" but the resolved options request "${options.metrics.path}". Route metadata is fixed before forRootAsync's options resolve, so a custom "metrics.path" is only honored through forRoot(); register synchronously, or keep the default "metrics" route on the async path.`
+    );
+  }
+}
+function createMetricsController(registeredPath) {
+  let MetricsController = class {
+    /**
+     * @param registry - The dedicated `prom-client` registry to scrape.
+     * @param options - Resolved core options, used to guard consistency at request time.
+     * @param adapterHost - The live HTTP adapter, used to reply with the correct content type.
+     */
+    constructor(registry, options, adapterHost) {
+      this.registry = registry;
+      this.options = options;
+      this.adapterHost = adapterHost;
+    }
+    async scrape(response) {
+      assertControllerMatchesOptions2(this.options, registeredPath);
+      const body = await this.registry.metrics();
+      this.adapterHost.httpAdapter.setHeader(response, "Content-Type", this.registry.contentType);
+      this.adapterHost.httpAdapter.reply(response, body, HttpStatus.OK);
+    }
+  };
+  __decorateClass([
+    Get(),
+    __decorateParam(0, Res())
+  ], MetricsController.prototype, "scrape", 1);
+  MetricsController = __decorateClass([
+    Controller(registeredPath),
+    __decorateParam(0, Inject(BYMAX_METRICS_REGISTRY)),
+    __decorateParam(1, Inject(BYMAX_CORE_OPTIONS)),
+    __decorateParam(2, Inject(HttpAdapterHost))
+  ], MetricsController);
+  return MetricsController;
+}
+
+// src/metrics/metrics.registry.ts
+var MISSING_PEER_MESSAGE = "metrics.enabled is true but the optional peer prom-client is not installed. Run: pnpm add prom-client";
+function isMissingModuleError(cause) {
+  const code = cause.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+async function loadPromClient() {
+  try {
+    return await import('prom-client');
+  } catch (cause) {
+    if (isMissingModuleError(cause)) {
+      throw new Error(MISSING_PEER_MESSAGE, { cause });
+    }
+    throw cause;
+  }
+}
+async function createMetricsRegistry(options) {
+  const promClient = await loadPromClient();
+  const registry = new promClient.Registry();
+  registry.setDefaultLabels(options.metrics.defaultLabels);
+  if (options.metrics.collectDefaultMetrics) {
+    promClient.collectDefaultMetrics({ register: registry });
+  }
+  return registry;
+}
+
+// src/metrics/timing-metrics.sink.ts
+var REQUESTS_TOTAL = "http_requests_total";
+var REQUEST_DURATION_SECONDS = "http_request_duration_seconds";
+var HTTP_METRIC_LABELS = ["method", "route", "status_code"];
+var MILLISECONDS_PER_SECOND = 1e3;
+function getOrCreateCounter(promClient, registry) {
+  const existing = registry.getSingleMetric(REQUESTS_TOTAL);
+  if (existing !== void 0) {
+    if (!(existing instanceof promClient.Counter)) {
+      throw new Error(
+        `A metric named "${REQUESTS_TOTAL}" is already registered on the metrics registry with a different type; the HTTP metrics bridge requires it to be a Counter.`
+      );
+    }
+    return existing;
+  }
+  return new promClient.Counter({
+    name: REQUESTS_TOTAL,
+    help: "Total number of completed HTTP requests, labeled by method, route, and status_code.",
+    labelNames: [...HTTP_METRIC_LABELS],
+    registers: [registry]
+  });
+}
+function getOrCreateHistogram(promClient, registry) {
+  const existing = registry.getSingleMetric(REQUEST_DURATION_SECONDS);
+  if (existing !== void 0) {
+    if (!(existing instanceof promClient.Histogram)) {
+      throw new Error(
+        `A metric named "${REQUEST_DURATION_SECONDS}" is already registered on the metrics registry with a different type; the HTTP metrics bridge requires it to be a Histogram.`
+      );
+    }
+    return existing;
+  }
+  return new promClient.Histogram({
+    name: REQUEST_DURATION_SECONDS,
+    help: "HTTP request duration in seconds, labeled by method, route, and status_code.",
+    labelNames: [...HTTP_METRIC_LABELS],
+    registers: [registry]
+  });
+}
+var TimingMetricsSink = class {
+  /**
+   * @param registry - The dedicated metrics registry the samples feed.
+   * @param promClient - The lazily loaded `prom-client` module supplying the
+   *   `Counter` and `Histogram` constructors, passed in so this bridge never
+   *   imports the optional peer at the top level.
+   */
+  constructor(registry, promClient) {
+    this.counter = getOrCreateCounter(promClient, registry);
+    this.histogram = getOrCreateHistogram(promClient, registry);
+  }
+  /**
+   * Record one completed request: increment the counter once and observe the
+   * duration in seconds, both under the bounded label set. Any failure is
+   * swallowed so a metrics backend problem can never break the request being
+   * observed.
+   *
+   * @param sample - The timing sample for a completed request.
+   */
+  record(sample) {
+    const labels = {
+      method: sample.method,
+      route: sample.route,
+      status_code: String(sample.statusCode)
+    };
+    try {
+      this.counter.inc(labels);
+      this.histogram.observe(labels, sample.durationMs / MILLISECONDS_PER_SECOND);
+    } catch {
+    }
+  }
+};
+
+// src/metrics/metrics.providers.ts
+function createDisabledRegistryPlaceholder() {
+  const throwDisabled = () => {
+    throw new Error(
+      '[BymaxCoreModule] The metrics registry was accessed while metrics are disabled. Enable "metrics" in the resolved options before injecting the registry.'
+    );
+  };
+  return { metrics: throwDisabled };
+}
+async function resolveMetricsRegistry(options) {
+  if (!options.metrics.enabled) {
+    return createDisabledRegistryPlaceholder();
+  }
+  return createMetricsRegistry(options);
+}
+async function resolveTimingSink(options, registry) {
+  if (options.metrics.enabled && options.timing.enabled) {
+    return new TimingMetricsSink(registry, await loadPromClient());
+  }
+  return new NoopTimingSink();
+}
+function buildMetricsRegistryProvider() {
+  return {
+    provide: BYMAX_METRICS_REGISTRY,
+    useFactory: (options) => resolveMetricsRegistry(options),
+    inject: [BYMAX_CORE_OPTIONS]
+  };
+}
+function buildMetricsTimingSinkProvider() {
+  return {
+    provide: BYMAX_TIMING_SINK,
+    useFactory: (options, registry) => resolveTimingSink(options, registry),
+    inject: [BYMAX_CORE_OPTIONS, BYMAX_METRICS_REGISTRY]
+  };
+}
+
+// src/core.module.ts
+var {
+  ConfigurableModuleClass: BymaxCoreModuleBase,
+  MODULE_OPTIONS_TOKEN: BUILDER_OPTIONS_TOKEN,
+  OPTIONS_TYPE,
+  ASYNC_OPTIONS_TYPE
+} = new ConfigurableModuleBuilder().setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  // `setExtras` merges the `{ isGlobal: true }` default first, so `isGlobal`
+  // is always defined; `!== false` keeps "global unless explicitly disabled".
+  global: extras.isGlobal !== false
+})).build();
+function buildSyncProviders(resolved) {
+  const providers = [];
+  if (resolved.envelope.enabled) {
+    providers.push({ provide: APP_FILTER, useClass: BymaxExceptionFilter });
+  }
+  if (resolved.timing.enabled) {
+    providers.push({ provide: APP_INTERCEPTOR, useClass: TimingInterceptor });
+  }
+  if (resolved.health.enabled) {
+    providers.push(HealthService);
+  }
+  if (resolved.metrics.enabled) {
+    providers.push(buildMetricsRegistryProvider());
+    if (resolved.timing.enabled) {
+      providers.push(buildMetricsTimingSinkProvider());
+    }
+  }
+  return providers;
+}
+function buildControllers(resolved) {
+  const controllers = [];
+  if (resolved.health.enabled) {
+    controllers.push(createHealthController(resolved.health.path));
+  }
+  if (resolved.metrics.enabled) {
+    controllers.push(createMetricsController(resolved.metrics.path));
+  }
+  return controllers;
+}
+function buildAsyncSlots() {
+  return [
+    {
+      provide: APP_FILTER,
+      useFactory: (options, correlation, adapterHost) => selectAsyncExceptionFilter(options, correlation, adapterHost),
+      inject: [
+        BYMAX_CORE_OPTIONS,
+        { token: BYMAX_CORRELATION_PROVIDER, optional: true },
+        HttpAdapterHost
+      ]
+    },
+    {
+      provide: APP_INTERCEPTOR,
+      useFactory: (options, sink, clock) => selectAsyncTimingInterceptor(options, sink, clock),
+      inject: [BYMAX_CORE_OPTIONS, BYMAX_TIMING_SINK, BYMAX_TIMING_CLOCK]
+    }
+  ];
+}
+function augmentModule(base, providers, controllers, exportTokens = [BYMAX_CORE_OPTIONS]) {
+  return {
+    ...base,
+    module: BymaxCoreModule,
+    providers: [...base.providers ?? [], ...providers],
+    controllers: [...base.controllers ?? [], ...controllers],
+    exports: [...base.exports ?? [], ...exportTokens]
+  };
+}
+var BymaxCoreModule = class extends BymaxCoreModuleBase {
+  /**
+   * Register the module synchronously. Options are known now, so disabled
+   * features are omitted from the providers and controllers arrays and the
+   * resolved snapshot is provided under {@link BYMAX_CORE_OPTIONS}.
+   *
+   * @param options - Core options plus the optional `isGlobal` extra. Omit for
+   *   all documented defaults.
+   * @returns The configured `DynamicModule`.
+   * @example
+   *   BymaxCoreModule.forRoot({ metrics: { enabled: true } })
+   */
+  static forRoot(options = {}) {
+    const resolved = normalizeCoreOptions(options);
+    const providers = [
+      { provide: BYMAX_CORE_OPTIONS, useValue: resolved },
+      ...buildDefaultProviders(),
+      ...buildSyncProviders(resolved)
+    ];
+    const exportTokens = [BYMAX_CORE_OPTIONS];
+    if (resolved.metrics.enabled) {
+      exportTokens.push(BYMAX_METRICS_REGISTRY);
+      if (resolved.timing.enabled) {
+        exportTokens.push(BYMAX_TIMING_SINK);
+      }
+    }
+    return augmentModule(
+      super.forRoot(options),
+      providers,
+      buildControllers(resolved),
+      exportTokens
+    );
+  }
+  /**
+   * Register the module asynchronously. The resolved options are produced by
+   * the consumer's factory and normalized under {@link BYMAX_CORE_OPTIONS}.
+   * Because those options are unknown when the module is defined, the pipeline
+   * slots register unconditionally and gate at runtime with transparent
+   * pass-throughs. The health controller cannot register conditionally either,
+   * since its route metadata is fixed before the async options resolve: it is
+   * always registered at the default health path, and its handlers guard
+   * every request against the resolved options being disabled or requesting a
+   * different path, throwing a descriptive configuration error in either case.
+   * The metrics controller follows the same mechanism at the default metrics
+   * path; the `BYMAX_METRICS_REGISTRY` factory gates on the resolved options and
+   * resolves to a guarded placeholder when metrics are disabled, so the optional
+   * peer `prom-client` is never loaded unless metrics are actually enabled.
+   *
+   * @param options - Async options (factory + inject + imports, or class).
+   * @returns The configured `DynamicModule`.
+   * @example
+   *   BymaxCoreModule.forRootAsync({ inject: [Config], useFactory: (c) => ({ ... }) })
+   */
+  static forRootAsync(options) {
+    const providers = [
+      {
+        provide: BYMAX_CORE_OPTIONS,
+        useFactory: (raw) => normalizeCoreOptions(raw),
+        inject: [BUILDER_OPTIONS_TOKEN]
+      },
+      ...buildDefaultProviders(),
+      ...buildAsyncSlots(),
+      HealthService,
+      buildMetricsRegistryProvider(),
+      buildMetricsTimingSinkProvider()
+    ];
+    return augmentModule(
+      super.forRootAsync(options),
+      providers,
+      [createHealthController(DEFAULT_HEALTH_PATH), createMetricsController(DEFAULT_METRICS_PATH)],
+      [BYMAX_CORE_OPTIONS, BYMAX_TIMING_SINK, BYMAX_METRICS_REGISTRY]
+    );
+  }
+};
+BymaxCoreModule = __decorateClass([
+  Module({})
+], BymaxCoreModule);
+
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, TimingInterceptor, buildErrorEnvelope, codeForStatus };