@fluojs/terminus 1.0.0-beta.1

package/dist/indicators/utils.d.ts

@@ -0,0 +1,48 @@
+import type { HealthIndicatorResult } from '../types.js';
+/** Timeout settings shared by indicators that call external dependencies. */
+export interface IndicatorTimeoutOptions {
+    timeoutMs?: number;
+}
+/**
+ * Create an `up` indicator result payload.
+ *
+ * @param key Indicator key used in the aggregated report.
+ * @param details Optional structured details to merge into the success state.
+ * @returns A one-entry health indicator result marked as `up`.
+ */
+export declare function createUpResult(key: string, details?: Record<string, unknown>): HealthIndicatorResult;
+/**
+ * Create a `down` indicator result payload.
+ *
+ * @param key Indicator key used in the aggregated report.
+ * @param message Human-readable failure message.
+ * @param details Optional structured details to merge into the failure state.
+ * @returns A one-entry health indicator result marked as `down`.
+ */
+export declare function createDownResult(key: string, message: string, details?: Record<string, unknown>): HealthIndicatorResult;
+/**
+ * Race an indicator promise against a timeout.
+ *
+ * @param promise Indicator promise that should finish within the timeout budget.
+ * @param timeoutMs Timeout budget in milliseconds.
+ * @param indicatorName Indicator name used in the timeout error message.
+ * @returns The original promise result when it finishes in time.
+ */
+export declare function withIndicatorTimeout<T>(promise: Promise<T>, timeoutMs: number, indicatorName: string): Promise<T>;
+/**
+ * Resolve the effective key used in reports for one indicator execution.
+ *
+ * @param fallbackKey Built-in fallback key for the indicator type.
+ * @param key Optional caller-supplied override.
+ * @returns The trimmed override key when present, otherwise the fallback key.
+ */
+export declare function resolveIndicatorKey(fallbackKey: string, key: string | undefined): string;
+/**
+ * Throw a `HealthCheckError` with a structured cause payload.
+ *
+ * @param message Human-readable error message.
+ * @param causes Structured indicator result payload to preserve in the exception.
+ * @throws {HealthCheckError} Always throws with the provided message and causes.
+ */
+export declare function throwHealthCheckError(message: string, causes: HealthIndicatorResult): never;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +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"}

package/dist/indicators/utils.js

@@ -0,0 +1,82 @@
+import { HealthCheckError } from '../errors.js';
+
+/** Timeout settings shared by indicators that call external dependencies. */
+
+/**
+ * Create an `up` indicator result payload.
+ *
+ * @param key Indicator key used in the aggregated report.
+ * @param details Optional structured details to merge into the success state.
+ * @returns A one-entry health indicator result marked as `up`.
+ */
+export function createUpResult(key, details = {}) {
+  return {
+    [key]: {
+      ...details,
+      status: 'up'
+    }
+  };
+}
+
+/**
+ * Create a `down` indicator result payload.
+ *
+ * @param key Indicator key used in the aggregated report.
+ * @param message Human-readable failure message.
+ * @param details Optional structured details to merge into the failure state.
+ * @returns A one-entry health indicator result marked as `down`.
+ */
+export function createDownResult(key, message, details = {}) {
+  return {
+    [key]: {
+      ...details,
+      message,
+      status: 'down'
+    }
+  };
+}
+
+/**
+ * Race an indicator promise against a timeout.
+ *
+ * @param promise Indicator promise that should finish within the timeout budget.
+ * @param timeoutMs Timeout budget in milliseconds.
+ * @param indicatorName Indicator name used in the timeout error message.
+ * @returns The original promise result when it finishes in time.
+ */
+export function withIndicatorTimeout(promise, timeoutMs, indicatorName) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${indicatorName} health indicator timed out after ${String(timeoutMs)}ms.`));
+    }, timeoutMs);
+    promise.then(value => {
+      clearTimeout(timer);
+      resolve(value);
+    }, error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Resolve the effective key used in reports for one indicator execution.
+ *
+ * @param fallbackKey Built-in fallback key for the indicator type.
+ * @param key Optional caller-supplied override.
+ * @returns The trimmed override key when present, otherwise the fallback key.
+ */
+export function resolveIndicatorKey(fallbackKey, key) {
+  return key && key.trim().length > 0 ? key : fallbackKey;
+}
+
+/**
+ * Throw a `HealthCheckError` with a structured cause payload.
+ *
+ * @param message Human-readable error message.
+ * @param causes Structured indicator result payload to preserve in the exception.
+ * @throws {HealthCheckError} Always throws with the provided message and causes.
+ */
+export function throwHealthCheckError(message, causes) {
+  throw new HealthCheckError(message, causes);
+}

package/dist/module.d.ts

@@ -0,0 +1,20 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { TerminusModuleOptions } from './types.js';
+/** Module entry point that wires Terminus indicators into runtime health endpoints. */
+export declare class TerminusModule {
+    /**
+     * Register Terminus health indicators and readiness hooks.
+     *
+     * @example
+     * ```ts
+     * TerminusModule.forRoot({
+     *   indicators: [new MemoryHealthIndicator({ key: 'memory' })],
+     * });
+     * ```
+     *
+     * @param options Terminus health indicator and readiness configuration.
+     * @returns A runtime module exposing health endpoints and `TerminusHealthService`.
+     */
+    static forRoot(options?: TerminusModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAgLzE,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}

package/dist/module.js

@@ -0,0 +1,138 @@
+import { createHealthModule, defineModule } from '@fluojs/runtime';
+import { PLATFORM_SHELL, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { TerminusHealthService } from './health-check.js';
+import { TERMINUS_HEALTH_INDICATORS, TERMINUS_INDICATOR_PROVIDER_TOKENS } from './tokens.js';
+const TERMINUS_OPTIONS = Symbol.for('fluo.terminus.options');
+function copyIndicators(indicators) {
+  return [...(indicators ?? [])];
+}
+function copyProviders(providers) {
+  return [...(providers ?? [])];
+}
+function providerToken(provider) {
+  if (typeof provider === 'function') {
+    return provider;
+  }
+  if ('provide' in provider) {
+    return provider.provide;
+  }
+  return undefined;
+}
+function createTerminusProviders(options = {}) {
+  const normalizedOptions = {
+    ...options,
+    execution: {
+      ...(options.execution ?? {})
+    },
+    indicators: copyIndicators(options.indicators),
+    indicatorProviders: copyProviders(options.indicatorProviders),
+    readinessChecks: [...(options.readinessChecks ?? [])]
+  };
+  const indicatorProviders = copyProviders(normalizedOptions.indicatorProviders);
+  const indicatorProviderTokens = indicatorProviders.map(provider => providerToken(provider)).filter(token => token !== undefined);
+  return [{
+    provide: TERMINUS_OPTIONS,
+    useValue: normalizedOptions
+  }, {
+    provide: TERMINUS_INDICATOR_PROVIDER_TOKENS,
+    useValue: indicatorProviderTokens
+  }, {
+    inject: [TERMINUS_OPTIONS, TERMINUS_INDICATOR_PROVIDER_TOKENS, RUNTIME_CONTAINER],
+    provide: TERMINUS_HEALTH_INDICATORS,
+    useFactory: async (resolvedOptions, registeredTokens, runtimeContainer) => {
+      const resolvedIndicators = [];
+      if (typeof resolvedOptions === 'object' && resolvedOptions !== null && 'indicators' in resolvedOptions) {
+        const indicators = resolvedOptions.indicators;
+        resolvedIndicators.push(...copyIndicators(indicators));
+      }
+      if (runtimeContainer && typeof runtimeContainer === 'object' && runtimeContainer !== null && 'resolve' in runtimeContainer && typeof runtimeContainer.resolve === 'function' && Array.isArray(registeredTokens)) {
+        for (const token of registeredTokens) {
+          resolvedIndicators.push(await runtimeContainer.resolve(token));
+        }
+      }
+      return resolvedIndicators;
+    }
+  }, ...indicatorProviders, {
+    inject: [TERMINUS_HEALTH_INDICATORS, TERMINUS_OPTIONS],
+    provide: TerminusHealthService,
+    useFactory: (resolvedIndicators, resolvedOptions) => {
+      const indicators = Array.isArray(resolvedIndicators) ? resolvedIndicators : [];
+      const execution = typeof resolvedOptions === 'object' && resolvedOptions !== null && 'execution' in resolvedOptions && typeof resolvedOptions.execution === 'object' && resolvedOptions.execution !== null ? resolvedOptions.execution ?? {} : {};
+      return new TerminusHealthService(indicators, execution);
+    }
+  }];
+}
+function createTerminusRuntimeModule(options = {}) {
+  const readinessChecks = [...(options.readinessChecks ?? [])];
+  const healthModule = createHealthModule({
+    healthCheck: async ctx => {
+      const healthService = await ctx.container.resolve(TerminusHealthService);
+      const platformShell = await ctx.container.resolve(PLATFORM_SHELL);
+      const [report, readiness, health] = await Promise.all([healthService.check(), platformShell.ready(), platformShell.health()]);
+      const status = report.status === 'ok' && health.status === 'healthy' && readiness.status === 'ready' ? 'ok' : 'error';
+      return {
+        body: {
+          ...report,
+          platform: {
+            health,
+            readiness
+          },
+          status
+        },
+        statusCode: status === 'ok' ? 200 : 503
+      };
+    },
+    path: options.path
+  });
+  for (const check of readinessChecks) {
+    healthModule.addReadinessCheck(check);
+  }
+  const TERMINUS_READINESS_REGISTRAR = Symbol('fluo.terminus.readiness-registrar');
+  class TerminusRuntimeModule {}
+  return defineModule(TerminusRuntimeModule, {
+    exports: [TERMINUS_HEALTH_INDICATORS, TerminusHealthService],
+    imports: [healthModule],
+    providers: [...createTerminusProviders({
+      execution: options.execution,
+      indicatorProviders: options.indicatorProviders,
+      indicators: options.indicators,
+      path: options.path,
+      readinessChecks
+    }), {
+      inject: [TerminusHealthService, RUNTIME_CONTAINER],
+      provide: TERMINUS_READINESS_REGISTRAR,
+      useFactory: (...deps) => {
+        const [healthService, runtimeContainer] = deps;
+        return {
+          onApplicationBootstrap() {
+            healthModule.addReadinessCheck(async () => {
+              const platformShell = await runtimeContainer.resolve(PLATFORM_SHELL);
+              const [indicatorHealthy, readiness] = await Promise.all([healthService.isHealthy(), platformShell.ready()]);
+              return indicatorHealthy && readiness.status === 'ready';
+            });
+          }
+        };
+      }
+    }]
+  });
+}
+
+/** Module entry point that wires Terminus indicators into runtime health endpoints. */
+export class TerminusModule {
+  /**
+   * Register Terminus health indicators and readiness hooks.
+   *
+   * @example
+   * ```ts
+   * TerminusModule.forRoot({
+   *   indicators: [new MemoryHealthIndicator({ key: 'memory' })],
+   * });
+   * ```
+   *
+   * @param options Terminus health indicator and readiness configuration.
+   * @returns A runtime module exposing health endpoints and `TerminusHealthService`.
+   */
+  static forRoot(options = {}) {
+    return createTerminusRuntimeModule(options);
+  }
+}

package/dist/redis.d.ts

@@ -0,0 +1,2 @@
+export * from './indicators/redis.js';
+//# sourceMappingURL=redis.d.ts.map

package/dist/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../src/redis.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/redis.js

@@ -0,0 +1 @@
+export * from './indicators/redis.js';

package/dist/tokens.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Injection token for the list of health indicators registered in Terminus.
+ */
+export declare const TERMINUS_HEALTH_INDICATORS: unique symbol;
+/**
+ * Injection token for the provider tokens of indicators to be resolved from the DI container.
+ */
+export declare const TERMINUS_INDICATOR_PROVIDER_TOKENS: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,0BAA0B,eAAgD,CAAC;AAExF;;GAEG;AACH,eAAO,MAAM,kCAAkC,eAAwD,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,9 @@
+/**
+ * Injection token for the list of health indicators registered in Terminus.
+ */
+export const TERMINUS_HEALTH_INDICATORS = Symbol.for('fluo.terminus.health-indicators');
+
+/**
+ * Injection token for the provider tokens of indicators to be resolved from the DI container.
+ */
+export const TERMINUS_INDICATOR_PROVIDER_TOKENS = Symbol.for('fluo.terminus.indicator-provider-tokens');

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import type { Provider } from '@fluojs/di';
+import type { 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. */
+export type HealthIndicatorState = {
+    status: HealthIndicatorStatus;
+} & Record<string, unknown>;
+/** Map of indicator keys to their state payloads. */
+export type HealthIndicatorResult = {
+    [key: string]: HealthIndicatorState;
+};
+/** Contract implemented by dependency health probes registered with Terminus. */
+export interface HealthIndicator {
+    check(key: string): Promise<HealthIndicatorResult>;
+    key?: string;
+}
+/** Structured health report returned by Terminus aggregation helpers. */
+export interface HealthCheckReport {
+    checkedAt: string;
+    contributors: {
+        down: string[];
+        up: string[];
+    };
+    details: Record<string, HealthIndicatorState>;
+    error: Record<string, HealthIndicatorState>;
+    info: Record<string, HealthIndicatorState>;
+    platform?: {
+        health: PlatformHealthReport;
+        readiness: PlatformReadinessReport;
+    };
+    status: 'ok' | 'error';
+}
+/** Optional execution guardrails applied while Terminus runs health indicators. */
+export interface HealthCheckExecutionOptions {
+    /**
+     * Maximum time in milliseconds allowed for a single indicator execution before
+     * Terminus marks it as `down`.
+     */
+    indicatorTimeoutMs?: number;
+}
+/**
+ * Module options for registering health indicators, providers, and readiness hooks.
+ */
+export interface TerminusModuleOptions {
+    execution?: HealthCheckExecutionOptions;
+    indicators?: readonly HealthIndicator[];
+    indicatorProviders?: readonly Provider[];
+    path?: string;
+    readinessChecks?: readonly ReadinessCheck[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,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"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@fluojs/terminus",
+  "description": "Health indicator composition and enriched runtime health aggregation for Fluo applications.",
+  "keywords": [
+    "fluo",
+    "terminus",
+    "health",
+    "readiness",
+    "liveness",
+    "health-check"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/terminus"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "@fluojs/redis": "^1.0.0-beta.1",
+    "@fluojs/drizzle": "^1.0.0-beta.1",
+    "@fluojs/prisma": "^1.0.0-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "@fluojs/drizzle": {
+      "optional": true
+    },
+    "@fluojs/prisma": {
+      "optional": true
+    },
+    "@fluojs/redis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}