first commit

docs/observability/monitor/health-check/src/health-checker/health-checker.helpers.md

@@ -0,0 +1,49 @@
+# `health-checker/health-checker.helpers`
+
+## Purpose
+
+`health-checker.helpers` carries the pure helpers that back the `HealthChecker` class: the Zod schemas that validate constructor + per-check options, the default `Clock` / `TimersLike` pair, the aggregate-status function, the raw-result normaliser, and the timeout-enforcing wrapper. They are split out of `health-checker.ts` to keep the main class file inside the project line-count budget and to make each helper independently unit-testable through `HealthChecker`'s tests.
+
+## Features
+
+- `dependencyCheckSchema` + `optionsSchema` — Zod boundary schemas; throw `HealthCheckError(INVALID_OPTIONS)` on failure when wired in.
+- `defaultClock` — `() => Date.now()`.
+- `defaultTimers` — `setTimeout` / `clearTimeout` adapter for the `TimersLike` contract.
+- `aggregateStatus(results, isCritical)` — pure function mapping a result list to overall `CheckStatus`.
+- `normalizeResult(name, raw, elapsed, clock)` — pure normaliser preserving raw `name` / `timestamp` when present.
+- `executeWithTimeout(thunk, ms, timers)` — schedules a `HealthCheckError(CHECK_TIMEOUT)` rejection through the supplied `TimersLike`.
+
+## Usage: Basic
+
+```ts
+import { aggregateStatus } from "@suaveplan/health-check/health-checker";
+
+const status = aggregateStatus(results, (name) => criticalNames.has(name));
+```
+
+## Usage: Advanced
+
+```ts
+import { executeWithTimeout } from "@suaveplan/health-check/health-checker";
+
+const result = await executeWithTimeout(
+    () => probe(),
+    250,
+    { setTimer: setTimeout, clearTimer: clearTimeout },
+);
+```
+
+## API Reference
+
+- `DEFAULT_TIMEOUT: 5000`
+- `defaultClock: Clock`
+- `defaultTimers: TimersLike`
+- `dependencyCheckSchema: ZodObject`
+- `optionsSchema: ZodObject`
+- `aggregateStatus(results, isCritical) → CheckStatus`
+- `normalizeResult(name, raw, elapsed, clock) → CheckResult`
+- `executeWithTimeout<T>(thunk, ms, timers) → Promise<T>`
+
+## Implementation Notes
+
+`executeWithTimeout` carries a `settled` flag to absorb the race between the timer firing and the thunk resolving. Either path is responsible for flipping the flag; the other path no-ops. `clearTimer` is only called on the resolution / rejection side because the timer-fired side has already executed and there is nothing to cancel. Rejections from the thunk are coerced into `HealthCheckError(CHECK_EXECUTION_FAILED)` so the outer `runCheck` always sees a typed error and can route on `code` instead of `instanceof Error`. The Zod schemas are constructed at module top level — instantiating them once per import keeps the per-call overhead to a single `safeParse` invocation.