Healthcheck Core API

Functions

`aggregateStatus`

aggregateStatus(results: readonly HealthCheckResult[]) => HealthStatus

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`autoRuntimeAdapter`

Source

autoRuntimeAdapter() => RuntimeAdapter

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`createAbortSignal`

Source

createAbortSignal(timeoutMs: number | undefined, parent?: AbortSignal) => { signal: AbortSignal; dispose: () => void; }

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`createHealthManager`

Source

createHealthManager(options: HealthManagerOptions) => HealthManager

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`defineHealthCheck`

Source

defineHealthCheck<TName extends string>(definition: HealthCheckDefinition<TName>) => HealthCheckDefinition<TName>

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`defineMetricCollector`

Source

defineMetricCollector<TName extends string>(definition: MetricCollectorDefinition<TName>) => MetricCollectorDefinition<TName>

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`genericRuntimeAdapter`

Source

genericRuntimeAdapter() => RuntimeAdapter

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`httpCheck`

Source

httpCheck(name: string, url: string | URL, options?: HttpCheckOptions) => HealthCheckDefinition<string>

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`memoryCheck`

Source

memoryCheck(options?: { scopes?: readonly HealthScope[]; availableRatio?: { degraded: number; unhealthy: number; }; usedRatio?: { degraded: number; unhealthy: number; }; critical?: boolean | Partial<Record<HealthScope, boolean>>; }) => HealthCheckDefinition<"memory">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`runtimeInfoCheck`

Source

runtimeInfoCheck(options?: { scopes?: readonly HealthScope[]; critical?: boolean; }) => HealthCheckDefinition<"runtime.info">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`runtimeMetricsCollector`

Source

runtimeMetricsCollector(options?: { scopes?: readonly HealthScope[]; }) => MetricCollectorDefinition<"runtime.metrics">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`shutdownCheck`

Source

shutdownCheck(options?: { scopes?: readonly HealthScope[]; }) => HealthCheckDefinition<"shutdown">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`sleep`

Source

sleep(ms: number, signal?: AbortSignal) => Promise<void>

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`startupCheck`

Source

startupCheck(options: { isStarted: () => boolean | Promise<boolean>; scopes?: readonly HealthScope[]; timeoutMs?: number; }) => HealthCheckDefinition<"startup">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`statusToHttpStatus`

Source

statusToHttpStatus(status: HealthStatus, policy?: HealthHttpStatusPolicy) => number

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`stringifyHealthJson`

Source

stringifyHealthJson(report: HealthReport, options?: HealthJsonOptions) => string

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`summarizeChecks`

Source

summarizeChecks(results: readonly HealthCheckResult[]) => HealthSummary

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`timerLagCheck`

Source

timerLagCheck(options?: { scopes?: readonly HealthScope[]; sampleMs?: number; thresholds?: { degradedMs: number; unhealthyMs: number; }; critical?: boolean; }) => HealthCheckDefinition<"timer.lag">

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

`toHealthJson`

Source

toHealthJson(report: HealthReport, options?: HealthJsonOptions) => HealthReport

Exported from: @nexload-sdk/healthcheck

Public function exported by @nexload-sdk/healthcheck.

Constants

`DEFAULT_HTTP_STATUS_POLICY`

Source

DEFAULT_HTTP_STATUS_POLICY: HealthHttpStatusPolicy

Exported from: @nexload-sdk/healthcheck

Public constant exported by @nexload-sdk/healthcheck.

`HEALTH_ERROR_CODES`

Source

HEALTH_ERROR_CODES: { readonly CHECK_THROWN: "CHECK_THROWN"; readonly CHECK_TIMEOUT: "CHECK_TIMEOUT"; readonly CHECK_ABORTED: "CHECK_ABORTED"; readonly HEALTHCHECK_TIMEOUT: "HEALTHCHECK_TIMEOUT"; readonly HEALTHCHECK_ABORTED: "HEALTHCHECK_ABORTED"; readonly HEALTHCHECK_DEPENDENCY_UNAVAILABLE: "HEALTHCHECK_DEPENDENCY_UNAVAILABLE"; readonly HEALTHCHECK_CONTAINER_LIMIT_UNAVAILABLE: "HEALTHCHECK_CONTAINER_LIMIT_UNAVAILABLE"; readonly HEALTHCHECK_ROUTE_UNAUTHORIZED: "HEALTHCHECK_ROUTE_UNAUTHORIZED"; readonly HEALTHCHECK_INVALID_CONFIG: "HEALTHCHECK_INVALID_CONFIG"; readonly HTTP_STATUS_MISMATCH: "HTTP_STATUS_MISMATCH"; readonly HTTP_BODY_MISMATCH: "HTTP_BODY_MISMATCH"; readonly TCP_CONNECT_FAILED: "TCP_CONNECT_FAILED"; readonly DNS_RESOLVE_FAILED: "DNS_RESOLVE_FAILED"; readonly DATABASE_PING_FAILED: "DATABASE_PING_FAILED"; readonly PAYLOAD_QUERY_FAILED: "PAYLOAD_QUERY_FAILED"; readonly RUNTIME_UNSUPPORTED: "RUNTIME_UNSUPPORTED"; readonly METRIC_UNAVAILABLE: "METRIC_UNAVAILABLE"; }

Exported from: @nexload-sdk/healthcheck

Public constant exported by @nexload-sdk/healthcheck.

`STRICT_READINESS_HTTP_STATUS_POLICY`

Source

STRICT_READINESS_HTTP_STATUS_POLICY: HealthHttpStatusPolicy

Exported from: @nexload-sdk/healthcheck

Public constant exported by @nexload-sdk/healthcheck.

Interfaces

`EnvironmentIdentity`

Source

interface EnvironmentIdentity {
  name?: string
  region?: string
  zone?: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthCheckDefinition`

Source

interface HealthCheckDefinition<TName extends string = string> {
  kind?: "check"
  name: TName
  component?: string
  scopes: readonly HealthScope[]
  critical?: boolean | Partial<Record<HealthScope, boolean>>
  timeoutMs?: number
  retries?: RetryPolicy
  tags?: readonly string[]
  run(context: HealthRunContext): Promise<HealthCheckRunResult> | HealthCheckRunResult
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthCheckResult`

Source

interface HealthCheckResult<TName extends string = string> {
  name: TName
  component?: string
  scope: HealthRunScope
  status: HealthStatus
  critical: boolean
  observedAt: string
  durationMs: number
  timedOut: boolean
  attempt: number
  metrics: HealthMetrics
  details?: HealthDetails
  error?: HealthErrorInfo
  tags?: readonly string[]
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthCheckRunResult`

Source

interface HealthCheckRunResult {
  status: HealthStatus
  metrics?: HealthMetrics
  details?: HealthDetails
  error?: HealthErrorInfo
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthErrorInfo`

Source

interface HealthErrorInfo {
  code: string
  message: string
  causeName?: string
  causeMessage?: string
  stack?: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthHttpStatusPolicy`

Source

interface HealthHttpStatusPolicy {
  ok: number
  degraded: number
  unhealthy: number
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthJsonOptions`

Source

interface HealthJsonOptions {
  includeDetails?: boolean
  redact?: boolean
  redaction?: Partial<RedactionPolicy>
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthLinks`

Source

interface HealthLinks {
  self?: string
  metrics?: string
  diagnostics?: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthManager`

Source

interface HealthManager {
  register(check: HealthCheckDefinition): HealthManager
  registerCollector(collector: MetricCollectorDefinition): HealthManager
  unregister(name: string): boolean
  run(scope: HealthRunScope, options?: HealthRunOptions): Promise<HealthReport>
  setShutdownState(state: boolean, reason?: string): void
  isShuttingDown(): boolean
  dispose(): void
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthManagerOptions`

Source

interface HealthManagerOptions {
  service: ServiceIdentity
  runtime?: RuntimeAdapter | "auto"
  environment?: EnvironmentIdentity
  defaults?: {
    timeoutMs?: number
    concurrency?: number
    /** Defaults to true. Set false to report timed-out checks as degraded. */
    unhealthyOnTimeout?: boolean
    includeStack?: boolean
    profile?: HealthDataProfile
  }
  /** Profiles are passed to checks and collectors as context hints. */
  profiles?: Partial<Record<HealthScope, HealthDataProfile>> & { default?: HealthDataProfile }
  /** @deprecated Configure redaction when calling toHealthJson or stringifyHealthJson. */
  redaction?: Partial<RedactionPolicy>
  checks?: readonly HealthCheckDefinition[]
  collectors?: readonly MetricCollectorDefinition[]
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthMetric`

Source

interface HealthMetric {
  name: string
  value: HealthMetricValue
  unit?:
    | "bytes"
    | "seconds"
    | "milliseconds"
    | "ratio"
    | "count"
    | "percent"
    | "state"
  type?: "gauge" | "counter" | "histogram" | "info"
  labels?: Record<string, string>
  description?: string
  observedAt?: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthReport`

Source

interface HealthReport {
  schemaVersion: "2.0"
  service: ServiceIdentity
  scope: HealthRunScope
  status: HealthStatus
  observedAt: string
  durationMs: number
  runtime: RuntimeIdentity
  environment?: EnvironmentIdentity
  summary: HealthSummary
  checks: readonly HealthCheckResult[]
  metrics: readonly HealthMetric[]
  resources?: Record<string, unknown>
  links?: HealthLinks
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthRunContext`

Source

interface HealthRunContext {
  scope: HealthRunScope
  signal: AbortSignal
  runtime: RuntimeAdapter
  service: ServiceIdentity
  profile: HealthDataProfile
  now: () => number
  getShutdownState: () => { shuttingDown: boolean, reason?: string }
  result: (result: HealthCheckRunResult) => HealthCheckRunResult
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthRunOptions`

Source

interface HealthRunOptions {
  signal?: AbortSignal
  profile?: HealthDataProfile
  /** @deprecated Select a profile and configure serializer detail options instead. */
  includeDiagnostics?: boolean
  includeStacks?: boolean
  timeoutMs?: number
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HealthSummary`

Source

interface HealthSummary {
  ok: number
  degraded: number
  unhealthy: number
  total: number
  criticalFailed: number
  nonCriticalFailed: number
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`HttpCheckOptions`

Source

interface HttpCheckOptions {
  scopes?: readonly HealthScope[]
  method?: "GET" | "HEAD" | "POST"
  headers?: HeadersInit
  body?: BodyInit | null
  expectedStatus?: number | readonly number[] | { min: number, max: number }
  validateBody?: (body: string, response: Response) => boolean | Promise<boolean>
  timeoutMs?: number
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`MetricCollectionResult`

Source

interface MetricCollectionResult {
  metrics: readonly HealthMetric[]
  resources?: Record<string, unknown>
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`MetricCollectorDefinition`

Source

interface MetricCollectorDefinition<TName extends string = string> {
  kind?: "collector"
  name: TName
  scopes?: readonly HealthScope[]
  defaultEnabled?: boolean
  timeoutMs?: number
  collect(context: HealthRunContext): Promise<MetricCollectionResult> | MetricCollectionResult
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RedactionPolicy`

Source

interface RedactionPolicy {
  redactSecrets: boolean
  redactUrls: "none" | "query" | "origin" | "full"
  includeStack: boolean
  includeErrorMessage: boolean
  allowedDetailKeys?: readonly string[]
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RetryPolicy`

Source

interface RetryPolicy {
  attempts: number
  delayMs?: number
  backoff?: "none" | "linear" | "exponential"
  retryOn?: readonly HealthStatus[]
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RuntimeAdapter`

Source

interface RuntimeAdapter {
  name: RuntimeIdentity["name"]
  now(): number
  uptimeSeconds(): number | null
  getRuntimeInfo(): RuntimeIdentity
  getMemory?(): RuntimeMemorySnapshot | Promise<RuntimeMemorySnapshot>
  getCpu?(previous?: RuntimeCpuSnapshot): RuntimeCpuSnapshot | Promise<RuntimeCpuSnapshot>
  onShutdown?(signals: readonly string[], callback: (signal: string) => void): () => void
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RuntimeCpuSnapshot`

Source

interface RuntimeCpuSnapshot {
  userMicros: number | null
  systemMicros: number | null
  availableParallelism: number | null
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RuntimeIdentity`

Source

interface RuntimeIdentity {
  name: "node" | "bun" | "unknown"
  version?: string
  revision?: string
  platform?: string
  arch?: string
  pid?: number
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`RuntimeMemorySnapshot`

Source

interface RuntimeMemorySnapshot {
  rssBytes: number | null
  heapTotalBytes: number | null
  heapUsedBytes: number | null
  externalBytes: number | null
  arrayBuffersBytes: number | null
  constrainedBytes: number | null
  availableBytes: number | null
  totalBytes: number | null
  usedRatio: number | null
  availableRatio: number | null
  source: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

`ServiceIdentity`

Source

interface ServiceIdentity {
  name: string
  version?: string
  environment?: string
  instanceId?: string
}

Exported from: @nexload-sdk/healthcheck

Public interface exported by @nexload-sdk/healthcheck.

Types

`HealthDataProfile`

Source

type HealthDataProfile
  = | "probe"
    | "summary"
    | "monitoring"
    | "diagnostics"
    | "full";

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthDetails`

Source

type HealthDetails = Record<string, unknown>;

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthErrorCode`

Source

type HealthErrorCode
  = (typeof HEALTH_ERROR_CODES)[keyof typeof HEALTH_ERROR_CODES];

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthMetricValue`

Source

type HealthMetricValue = string | number | boolean | null;

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthMetrics`

Source

type HealthMetrics = Record<string, HealthMetricValue>;

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthRunScope`

Source

type HealthRunScope = HealthScope | "all";

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthScope`

Source

type HealthScope
  = | "liveness"
    | "readiness"
    | "startup"
    | "diagnostics";

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

`HealthStatus`

Source

type HealthStatus = "ok" | "degraded" | "unhealthy";

Exported from: @nexload-sdk/healthcheck

Public type exported by @nexload-sdk/healthcheck.

Primary runtime exports

createHealthManager(options) creates a manager with run, shutdown-state, and registration operations.
defineHealthCheck() and defineMetricCollector() preserve typed definitions.
runtimeInfoCheck, shutdownCheck, startupCheck, timerLagCheck, memoryCheck, and httpCheck create built-in checks.
runtimeMetricsCollector() produces report-level runtime metrics.
toHealthJson() and stringifyHealthJson() serialize reports with detail and redaction controls.
aggregateStatus() and summarizeChecks() operate on completed results.
statusToHttpStatus() applies DEFAULT_HTTP_STATUS_POLICY or STRICT_READINESS_HTTP_STATUS_POLICY.
genericRuntimeAdapter() and autoRuntimeAdapter() avoid importing a runtime integration.
createAbortSignal() and sleep() support cancellation-aware checks.

HEALTH_ERROR_CODES is the stable error-code vocabulary. Public types include manager, report, check, collector, runtime, retry, redaction, metric, HTTP-policy, and serialization contracts.

Source: packages/healthcheck/core/src/index.ts