@fluojs/terminus 1.0.0-beta.1

package/LICENSE

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

package/README.ko.md

@@ -0,0 +1,148 @@
+# @fluojs/terminus
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴킷입니다. `@fluojs/terminus`는 런타임의 기본 health/readiness 엔드포인트 위에 의존성 인식 상태 보고 기능을 추가합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [공통 패턴](#공통-패턴)
+  - [내장 인디케이터](#내장-인디케이터)
+  - [DI 기반 인디케이터](#di-기반-인디케이터)
+  - [실패 시맨틱](#실패-시맨틱)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+pnpm add @fluojs/terminus
+```
+
+## 사용 시점
+
+- 외부 의존성(데이터베이스, Redis, API 등)의 상태를 애플리케이션 헬스 체크 결과에 포함해야 할 때.
+- 표준 모니터링 패턴에 맞는 구조화된 JSON 헬스 보고서가 필요할 때.
+- 핵심 하위 서비스에 접속할 수 없는 경우 `/ready` 체크가 실패하도록 설정해야 할 때.
+
+## 빠른 시작
+
+`TerminusModule.forRoot()`를 통해 헬스 인디케이터를 등록합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { HttpHealthIndicator, MemoryHealthIndicator, TerminusModule } from '@fluojs/terminus';
+
+@Module({
+  imports: [
+    TerminusModule.forRoot({
+      indicators: [
+        new HttpHealthIndicator({ key: 'upstream-api', url: 'https://example.com/health' }),
+        new MemoryHealthIndicator({ key: 'memory', heapUsedThresholdRatio: 0.9 }),
+      ],
+    }),
+  ],
+})
+class AppModule {}
+```
+
+## 공통 패턴
+
+### 내장 인디케이터
+
+패키지에서 기본으로 제공하는 인디케이터들은 다음과 같습니다.
+
+- `PrismaHealthIndicator` / `DrizzleHealthIndicator`
+- `RedisHealthIndicator` (`@fluojs/terminus/redis`에서 제공)
+- `HttpHealthIndicator`
+- `MemoryHealthIndicator`
+- `DiskHealthIndicator`
+
+### DI 기반 인디케이터
+
+Redis나 DB 클라이언트와 같이 DI 컨테이너의 의존성이 필요한 인디케이터를 사용할 때는, 모듈 로드 시점에 피어 의존성을 import하지 않도록 제공되는 provider 팩토리를 사용하세요.
+
+```typescript
+import { TerminusModule } from '@fluojs/terminus';
+import { createRedisHealthIndicatorProvider } from '@fluojs/terminus/redis';
+
+TerminusModule.forRoot({
+  indicatorProviders: [
+    createRedisHealthIndicatorProvider({ key: 'redis' })
+  ],
+});
+```
+
+`clientName`을 생략하면 기본 Redis 클라이언트를 계속 점검합니다. 이름 있는 Redis 연결을 점검하려면 `clientName`을 전달해 기본 클라이언트 대신 해당 named token을 해석하게 하세요.
+
+```typescript
+TerminusModule.forRoot({
+  indicatorProviders: [
+    createRedisHealthIndicatorProvider({ key: 'redis' }),
+    createRedisHealthIndicatorProvider({ clientName: 'cache', key: 'cache-redis' }),
+  ],
+});
+```
+
+### 실행 가드레일
+
+커스텀 인디케이터가 멈추거나 느린 하위 서비스에 의존할 수 있다면 `execution.indicatorTimeoutMs`를 사용하세요. probe가 설정된 시간을 넘기면 Terminus는 무기한 대기하지 않고 해당 인디케이터를 `down`으로 표시합니다.
+
+```typescript
+TerminusModule.forRoot({
+  execution: {
+    indicatorTimeoutMs: 1_500,
+  },
+  indicators: [
+    new HttpHealthIndicator({ key: 'upstream-api', url: 'https://example.com/health' }),
+  ],
+});
+```
+
+### 실패 시맨틱
+
+인디케이터가 실패하면 `HealthCheckError`를 던집니다. `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
+
+- 하나 이상의 인디케이터가 실패하면 `/health`는 HTTP `503`을 반환합니다.
+- 준비 상태(readiness)와 관련된 인디케이터가 실패하면 `/ready`는 HTTP `503`을 반환합니다.
+- 응답 본문은 `status`, `contributors`, `info`, `error`, `details`를 포함한 구조화된 JSON 객체입니다.
+- 하나의 인디케이터가 여러 keyed entry를 반환할 수도 있으며, 이 경우 `/health`는 모든 entry를 `details`와 `contributors.up` / `contributors.down` 요약에 그대로 반영합니다.
+- 같은 실행에서 이미 보고된 key를 다른 인디케이터가 다시 사용하면, Terminus는 먼저 기록된 entry를 유지하고 데이터를 조용히 덮어쓰는 대신 결정적인 `*-duplicate-key-error` contributor를 추가합니다.
+
+## 공개 API 개요
+
+### `TerminusModule`
+
+- `static forRoot(options: TerminusModuleOptions): ModuleType`
+  - 인디케이터 및 provider 등록을 위한 메인 엔트리 포인트입니다.
+
+### `TerminusHealthService`
+
+- `check(): Promise<HealthCheckReport>`
+  - 현재 등록된 인디케이터를 실행해 집계된 보고서를 반환합니다.
+- `isHealthy(): Promise<boolean>`
+  - 현재 집계 결과가 완전히 healthy 상태인지 반환합니다.
+
+### `@fluojs/terminus/redis`
+
+- `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
+  - Redis 전용 인디케이터 헬퍼는 선택적 Redis 피어가 설치되지 않은 환경에서도 루트 패키지 import가 안전하도록 전용 subpath에서 export됩니다.
+
+
+### `HealthCheckError`
+
+- 커스텀 인디케이터 내부에서 "down" 상태를 알리기 위해 이 에러를 발생시킵니다.
+
+## 관련 패키지
+
+- `@fluojs/metrics`: 가시성(Observability) 확보를 위해 자주 함께 사용됩니다.
+- `@fluojs/prisma` / `@fluojs/drizzle` / `@fluojs/redis`: 특정 인디케이터를 위한 피어 의존성입니다.
+
+## 예제 소스
+
+- `examples/ops-metrics-terminus/src/app.ts`: 헬스 체크와 메트릭의 엔드투엔드 통합 예제.
+- `packages/terminus/src/health-check.test.ts`: 집계 및 단언(assertion) 흐름 예제.

package/README.md

@@ -0,0 +1,148 @@
+# @fluojs/terminus
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Health indicator toolkit for fluo applications. `@fluojs/terminus` layers on top of runtime health/readiness endpoints to provide dependency-aware status reporting.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+  - [Built-in Indicators](#built-in-indicators)
+  - [DI-Backed Indicators](#di-backed-indicators)
+  - [Failure Semantics](#failure-semantics)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+pnpm add @fluojs/terminus
+```
+
+## When to Use
+
+- When you need to monitor external dependencies (databases, Redis, APIs) as part of your application's health status.
+- When you want a structured JSON health report that aligns with standard monitoring patterns.
+- When you need your `/ready` check to fail if critical downstream services are unreachable.
+
+## Quick Start
+
+Import `TerminusModule.forRoot()` to register health indicators.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { HttpHealthIndicator, MemoryHealthIndicator, TerminusModule } from '@fluojs/terminus';
+
+@Module({
+  imports: [
+    TerminusModule.forRoot({
+      indicators: [
+        new HttpHealthIndicator({ key: 'upstream-api', url: 'https://example.com/health' }),
+        new MemoryHealthIndicator({ key: 'memory', heapUsedThresholdRatio: 0.9 }),
+      ],
+    }),
+  ],
+})
+class AppModule {}
+```
+
+## Common Patterns
+
+### Built-in Indicators
+
+The package provides several indicators out of the box:
+
+- `PrismaHealthIndicator` / `DrizzleHealthIndicator`
+- `RedisHealthIndicator` (from `@fluojs/terminus/redis`)
+- `HttpHealthIndicator`
+- `MemoryHealthIndicator`
+- `DiskHealthIndicator`
+
+### DI-Backed Indicators
+
+To use indicators that require dependencies from the DI container (like Redis or Database clients) without importing peer dependencies at module load time, use the provider factories.
+
+```typescript
+import { TerminusModule } from '@fluojs/terminus';
+import { createRedisHealthIndicatorProvider } from '@fluojs/terminus/redis';
+
+TerminusModule.forRoot({
+  indicatorProviders: [
+    createRedisHealthIndicatorProvider({ key: 'redis' })
+  ],
+});
+```
+
+Omit `clientName` to keep probing the default Redis client. If the indicator should use a named Redis connection, pass `clientName` so the provider resolves that named client token instead of the default one.
+
+```typescript
+TerminusModule.forRoot({
+  indicatorProviders: [
+    createRedisHealthIndicatorProvider({ key: 'redis' }),
+    createRedisHealthIndicatorProvider({ clientName: 'cache', key: 'cache-redis' }),
+  ],
+});
+```
+
+### Execution Guardrails
+
+Use `execution.indicatorTimeoutMs` when custom indicators might hang or depend on slow downstreams. When a probe exceeds the configured timeout, Terminus marks that indicator as `down` instead of waiting forever.
+
+```typescript
+TerminusModule.forRoot({
+  execution: {
+    indicatorTimeoutMs: 1_500,
+  },
+  indicators: [
+    new HttpHealthIndicator({ key: 'upstream-api', url: 'https://example.com/health' }),
+  ],
+});
+```
+
+### Failure Semantics
+
+When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthService` aggregates these failures into a report:
+
+- `/health` returns HTTP `503` if any indicator fails.
+- `/ready` returns HTTP `503` if any indicator associated with readiness fails.
+- The response body contains a structured JSON object with `status`, `contributors`, `info`, `error`, and `details`.
+- Indicators may emit multiple keyed entries in a single check result; `/health` preserves every keyed entry in `details` and in the `contributors.up` / `contributors.down` summaries.
+- If an indicator reuses a key that was already reported earlier in the same run, Terminus keeps the first entry and adds a deterministic `*-duplicate-key-error` contributor instead of silently overwriting data.
+
+## Public API Overview
+
+### `TerminusModule`
+
+- `static forRoot(options: TerminusModuleOptions): ModuleType`
+  - Main entry point for registering indicators and providers.
+
+### `TerminusHealthService`
+
+- `check(): Promise<HealthCheckReport>`
+  - Runs the currently registered indicators and returns the aggregated report.
+- `isHealthy(): Promise<boolean>`
+  - Returns whether the current aggregated report is fully healthy.
+
+### `@fluojs/terminus/redis`
+
+- `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
+  - Redis-specific indicator helpers are exported from the dedicated subpath so the root package stays import-safe without the optional Redis peer installed.
+
+
+### `HealthCheckError`
+
+- Throw this error within custom indicators to signal a "down" state.
+
+## Related Packages
+
+- `@fluojs/metrics`: Often used together for observability.
+- `@fluojs/prisma` / `@fluojs/drizzle` / `@fluojs/redis`: Peer dependencies for specific indicators.
+
+## Example Sources
+
+- `examples/ops-metrics-terminus/src/app.ts`: End-to-end integration of health and metrics.
+- `packages/terminus/src/health-check.test.ts`: Demonstrates aggregation and assertion flow.

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+import type { HealthIndicatorResult } from './types.js';
+export declare class HealthCheckError extends Error {
+    readonly causes: HealthIndicatorResult;
+    constructor(message: string, causes: HealthIndicatorResult);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB;CAK3D"}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class HealthCheckError extends Error {
+  causes;
+  constructor(message, causes) {
+    super(message);
+    this.name = 'HealthCheckError';
+    this.causes = causes;
+  }
+}

package/dist/health-check.d.ts

@@ -0,0 +1,37 @@
+import type { HealthCheckExecutionOptions, HealthCheckReport, HealthIndicator } from './types.js';
+/**
+ * Run every registered health indicator and aggregate their results.
+ *
+ * @param indicators Indicator instances to execute for the current health probe.
+ * @param executionOptions Optional timeout guardrails for indicator execution.
+ * @returns A structured report containing `info`, `error`, and full `details` maps.
+ */
+export declare function runHealthCheck(indicators: readonly HealthIndicator[], executionOptions?: HealthCheckExecutionOptions): Promise<HealthCheckReport>;
+/**
+ * Assert that an aggregated health report is fully healthy.
+ *
+ * @param report Health report returned by `runHealthCheck(...)` or `TerminusHealthService.check()`.
+ * @param message Error message used when one or more indicators are down.
+ * @returns The same health report when every indicator is healthy.
+ * @throws {HealthCheckError} When the report contains at least one down indicator.
+ */
+export declare function assertHealthCheck(report: HealthCheckReport, message?: string): HealthCheckReport;
+/** Service facade that resolves and runs the health indicators registered in Terminus. */
+export declare class TerminusHealthService {
+    private readonly indicators;
+    private readonly executionOptions;
+    constructor(indicators: readonly HealthIndicator[], executionOptions?: HealthCheckExecutionOptions);
+    /**
+     * Execute all registered indicators once.
+     *
+     * @returns The aggregated health report for this check cycle.
+     */
+    check(): Promise<HealthCheckReport>;
+    /**
+     * Return whether every registered indicator currently reports `up`.
+     *
+     * @returns `true` when the aggregated report status is `ok`.
+     */
+    isHealthy(): Promise<boolean>;
+}
+//# sourceMappingURL=health-check.d.ts.map

package/dist/health-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../src/health-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AA0LpB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,SAAyB,GAAG,iBAAiB,CAMhH;AAED,0FAA0F;AAC1F,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC;IAGrE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}

package/dist/health-check.js

@@ -0,0 +1,191 @@
+import { HealthCheckError } from './errors.js';
+function normalizeIndicatorTimeoutMs(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}
+function createTimeoutMessage(timeoutMs) {
+  return `Health indicator timed out after ${String(timeoutMs)}ms.`;
+}
+async function withTimeout(promise, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([promise, new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(createTimeoutMessage(timeoutMs)));
+      }, timeoutMs);
+    })]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
+function toFailureResult(key, error) {
+  return {
+    [key]: {
+      message: error instanceof Error ? error.message : 'Unknown health indicator error.',
+      status: 'down'
+    }
+  };
+}
+function hasIndicatorStatus(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const status = value.status;
+  return status === 'up' || status === 'down';
+}
+function normalizeIndicatorResult(key, result) {
+  const normalizedEntries = Object.entries(result).filter(([, entryValue]) => hasIndicatorStatus(entryValue));
+  if (normalizedEntries.length > 0) {
+    return Object.fromEntries(normalizedEntries);
+  }
+  return {
+    [key]: {
+      message: 'Indicator returned an unsupported status value.',
+      status: 'down'
+    }
+  };
+}
+function inferIndicatorKey(indicator, index) {
+  const candidateKey = indicator.key;
+  if (typeof candidateKey === 'string' && candidateKey.trim().length > 0) {
+    return candidateKey;
+  }
+  const constructorName = indicator.constructor?.name;
+  if (typeof constructorName === 'string' && constructorName.trim().length > 0) {
+    return constructorName.replace(/HealthIndicator$/, '').replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+  }
+  return `indicator-${String(index + 1)}`;
+}
+function createDuplicateKeyFailureKey(indicatorKey, seenKeys) {
+  const baseKey = `${indicatorKey}-duplicate-key-error`;
+  if (!seenKeys.has(baseKey)) {
+    return baseKey;
+  }
+  let suffix = 2;
+  let candidate = `${baseKey}-${String(suffix)}`;
+  while (seenKeys.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseKey}-${String(suffix)}`;
+  }
+  return candidate;
+}
+function createDuplicateKeyFailure(indicatorKey, duplicateKeys, seenKeys) {
+  return [createDuplicateKeyFailureKey(indicatorKey, seenKeys), {
+    message: `Indicator produced duplicate result key(s): ${duplicateKeys.join(', ')}.`,
+    status: 'down'
+  }];
+}
+async function runIndicator(indicator, index, executionOptions) {
+  const key = inferIndicatorKey(indicator, index);
+  const indicatorTimeoutMs = normalizeIndicatorTimeoutMs(executionOptions.indicatorTimeoutMs);
+  try {
+    const result = indicatorTimeoutMs === undefined ? await indicator.check(key) : await withTimeout(indicator.check(key), indicatorTimeoutMs);
+    return {
+      entries: Object.entries(normalizeIndicatorResult(key, result)),
+      indicatorKey: key
+    };
+  } catch (error) {
+    if (error instanceof HealthCheckError) {
+      return {
+        entries: Object.entries(normalizeIndicatorResult(key, error.causes)),
+        indicatorKey: key
+      };
+    }
+    return {
+      entries: Object.entries(toFailureResult(key, error)),
+      indicatorKey: key
+    };
+  }
+}
+function aggregateIndicatorEntries(checks) {
+  const aggregatedEntries = [];
+  const seenKeys = new Set();
+  for (const check of checks) {
+    const duplicateKeys = [];
+    for (const entry of check.entries) {
+      const [entryKey] = entry;
+      if (seenKeys.has(entryKey)) {
+        duplicateKeys.push(entryKey);
+        continue;
+      }
+      seenKeys.add(entryKey);
+      aggregatedEntries.push(entry);
+    }
+    if (duplicateKeys.length > 0) {
+      const duplicateFailure = createDuplicateKeyFailure(check.indicatorKey, duplicateKeys, seenKeys);
+      seenKeys.add(duplicateFailure[0]);
+      aggregatedEntries.push(duplicateFailure);
+    }
+  }
+  return aggregatedEntries;
+}
+
+/**
+ * Run every registered health indicator and aggregate their results.
+ *
+ * @param indicators Indicator instances to execute for the current health probe.
+ * @param executionOptions Optional timeout guardrails for indicator execution.
+ * @returns A structured report containing `info`, `error`, and full `details` maps.
+ */
+export async function runHealthCheck(indicators, executionOptions = {}) {
+  const checks = aggregateIndicatorEntries(await Promise.all(indicators.map((indicator, index) => runIndicator(indicator, index, executionOptions))));
+  const details = Object.fromEntries(checks);
+  const infoEntries = checks.filter(([, result]) => result.status === 'up');
+  const errorEntries = checks.filter(([, result]) => result.status === 'down');
+  return {
+    checkedAt: new Date().toISOString(),
+    contributors: {
+      down: errorEntries.map(([key]) => key),
+      up: infoEntries.map(([key]) => key)
+    },
+    details,
+    error: Object.fromEntries(errorEntries),
+    info: Object.fromEntries(infoEntries),
+    status: errorEntries.length === 0 ? 'ok' : 'error'
+  };
+}
+
+/**
+ * Assert that an aggregated health report is fully healthy.
+ *
+ * @param report Health report returned by `runHealthCheck(...)` or `TerminusHealthService.check()`.
+ * @param message Error message used when one or more indicators are down.
+ * @returns The same health report when every indicator is healthy.
+ * @throws {HealthCheckError} When the report contains at least one down indicator.
+ */
+export function assertHealthCheck(report, message = 'Health check failed.') {
+  if (report.status === 'error') {
+    throw new HealthCheckError(message, report.error);
+  }
+  return report;
+}
+
+/** Service facade that resolves and runs the health indicators registered in Terminus. */
+export class TerminusHealthService {
+  constructor(indicators, executionOptions = {}) {
+    this.indicators = indicators;
+    this.executionOptions = executionOptions;
+  }
+
+  /**
+   * Execute all registered indicators once.
+   *
+   * @returns The aggregated health report for this check cycle.
+   */
+  async check() {
+    return runHealthCheck(this.indicators, this.executionOptions);
+  }
+
+  /**
+   * Return whether every registered indicator currently reports `up`.
+   *
+   * @returns `true` when the aggregated report status is `ok`.
+   */
+  async isHealthy() {
+    return (await this.check()).status === 'ok';
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './errors.js';
+export * from './health-check.js';
+export * from './indicators/index.js';
+export * from './module.js';
+export * from './tokens.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './errors.js';
+export * from './health-check.js';
+export * from './indicators/index.js';
+export * from './module.js';
+export * from './tokens.js';
+export * from './types.js';

package/dist/indicators/disk.d.ts

@@ -0,0 +1,31 @@
+import type { Provider } from '@fluojs/di';
+import type { HealthIndicator, HealthIndicatorResult } from '../types.js';
+/** Options for checking free disk bytes and free-ratio thresholds. */
+export interface DiskHealthIndicatorOptions {
+    key?: string;
+    minFreeBytes?: number;
+    minFreeRatio?: number;
+    path?: string;
+}
+/**
+ * Create a disk-space health indicator.
+ *
+ * @param options Optional filesystem path and free-space thresholds.
+ * @returns A health indicator backed by `statfs()`.
+ */
+export declare function createDiskHealthIndicator(options?: DiskHealthIndicatorOptions): HealthIndicator;
+/**
+ * Create a provider that registers a `DiskHealthIndicator` instance.
+ *
+ * @param options Optional filesystem path and free-space thresholds.
+ * @returns A value provider that exposes `DiskHealthIndicator` from the DI container.
+ */
+export declare function createDiskHealthIndicatorProvider(options?: DiskHealthIndicatorOptions): Provider;
+/** Health indicator that inspects free space for one filesystem path. */
+export declare class DiskHealthIndicator implements HealthIndicator {
+    private readonly options;
+    readonly key: string | undefined;
+    constructor(options?: DiskHealthIndicatorOptions);
+    check(key: string): Promise<HealthIndicatorResult>;
+}
+//# sourceMappingURL=disk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../src/indicators/disk.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,sEAAsE;AACtE,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAQD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,eAAe,CAEnG;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,GAAE,0BAA+B,GAAG,QAAQ,CAKpG;AAED,yEAAyE;AACzE,qBAAa,mBAAoB,YAAW,eAAe;IAG7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,0BAA+B;IAI/D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAsCzD"}