Make some health-check information more clear

.changeset/real-guests-smash.md

@@ -0,0 +1,6 @@
+---
+"@dts-stn/health-checks": major
+---
+
+- UNKNOWN status changed to TIMEDOUT.
+- Timing properties changed to responseTimeMs and timoutMs.

packages/health-checks/other/health-checks.schema.json

@@ -5,7 +5,7 @@
   "type": "object",
   "definitions": {
     "healthStatus": {
-      "enum": ["HEALTHY", "UNHEALTHY", "UNKNOWN"]
+      "enum": ["HEALTHY", "UNHEALTHY", "TIMEDOUT"]
     }
   },
   "properties": {

packages/health-checks/src/health-checks.ts

@@ -1,7 +1,7 @@
 /**
  * Represents the health state of a component or system.
  */
-export type HealthStatus = 'HEALTHY' | 'UNHEALTHY' | 'UNKNOWN';
+export type HealthStatus = 'HEALTHY' | 'UNHEALTHY' | 'TIMEDOUT';
 
 /**
  * Represents a health check for a specific system component.
@@ -16,7 +16,7 @@ export interface HealthCheck {
  * Configuration options for running health checks.
  */
 export interface HealthCheckOptions {
-  timeout?: number;
+  timeoutMs?: number;
   includeDetails?: boolean;
   includeComponents?: string[];
   excludeComponents?: string[];
@@ -33,7 +33,7 @@ export interface SystemHealthSummary {
   readonly status: HealthStatus;
   readonly buildId?: string;
   readonly version?: string;
-  readonly responseTime: number;
+  readonly responseTimeMs: number;
   readonly components?: Record<string, ComponentSummary>[];
 }
 
@@ -47,7 +47,7 @@ export const HealthCheckConfig = {
   },
   responses: {
     contentType: 'application/health+json',
-    statusCodes: { healthy: 200, unhealthy: 503, unknown: 500 },
+    statusCodes: { healthy: 200, unhealthy: 503, timedout: 408 },
   },
 } as const;
 
@@ -72,17 +72,17 @@ type HealthCheckResult = HealthCheckSuccess | HealthCheckFailure;
 interface HealthCheckSuccess {
   readonly status: 'HEALTHY';
   readonly name: string;
-  readonly responseTime: number;
+  readonly responseTimeMs: number;
   readonly metadata?: Record<string, string>;
 }
 
 /**
  * Represents a failed component health check result.
  */
 interface HealthCheckFailure {
-  readonly status: 'UNHEALTHY' | 'UNKNOWN';
+  readonly status: 'UNHEALTHY' | 'TIMEDOUT';
   readonly name: string;
-  readonly responseTime: number;
+  readonly responseTimeMs: number;
   readonly metadata?: Record<string, string>;
   readonly errorDetails: string;
   readonly stackTrace?: string;
@@ -98,16 +98,16 @@ type ComponentSummary = ComponentSuccessSummary | ComponentFailureSummary;
  */
 interface ComponentSuccessSummary {
   readonly status: 'HEALTHY';
-  readonly responseTime: number;
+  readonly responseTimeMs: number;
   readonly metadata?: Record<string, string>;
 }
 
 /**
  * Summarizes a failed health check for a component.
  */
 interface ComponentFailureSummary {
-  readonly status: 'UNHEALTHY' | 'UNKNOWN';
-  readonly responseTime: number;
+  readonly status: 'UNHEALTHY' | 'TIMEDOUT';
+  readonly responseTimeMs: number;
   readonly metadata?: Record<string, string>;
   readonly errorDetails?: string;
   readonly stackTrace?: string;
@@ -121,7 +121,7 @@ export async function execute(
   options: HealthCheckOptions = {},
 ): Promise<SystemHealthSummary> {
   const {
-    timeout = HealthCheckConfig.defaults.timeout,
+    timeoutMs = HealthCheckConfig.defaults.timeout,
     includeDetails = HealthCheckConfig.defaults.includeDetails,
     includeComponents = healthChecks.map((check) => check.name),
     excludeComponents = [],
@@ -133,13 +133,13 @@ export async function execute(
   );
 
   const startTime = Date.now();
-  const results = await Promise.all(enabledChecks.map((check) => executeWithTimeout(check, timeout)));
-  const responseTime = Date.now() - startTime;
+  const results = await Promise.all(enabledChecks.map((check) => executeWithTimeout(check, timeoutMs)));
+  const responseTimeMs = Date.now() - startTime;
 
   return {
     buildId: metadata?.buildId,
     components: results.map((result) => createComponentSummary(result, includeDetails)),
-    responseTime,
+    responseTimeMs,
     status: results.map((result) => result.status).reduce(aggregateHealthStatus, 'HEALTHY'),
     version: metadata?.version,
   };
@@ -170,17 +170,17 @@ export async function executeWithTimeout(healthCheck: HealthCheck, timeout: numb
     return {
       metadata: healthCheck.metadata,
       name: healthCheck.name,
-      responseTime: Date.now() - startTime,
+      responseTimeMs: Date.now() - startTime,
       status: 'HEALTHY',
     };
   } catch (error) {
     return {
       errorDetails: error instanceof Error ? error.message : JSON.stringify(error),
       metadata: healthCheck.metadata,
       name: healthCheck.name,
-      responseTime: Date.now() - startTime,
+      responseTimeMs: Date.now() - startTime,
       stackTrace: error instanceof Error ? error.stack : undefined,
-      status: error instanceof HealthCheckTimeoutError ? 'UNKNOWN' : 'UNHEALTHY',
+      status: error instanceof HealthCheckTimeoutError ? 'TIMEDOUT' : 'UNHEALTHY',
     };
   } finally {
     // finished... abort all unresolved promises
@@ -196,9 +196,9 @@ export function aggregateHealthStatus(prevStatus: HealthStatus, currStatus: Heal
   if (prevStatus === 'UNHEALTHY') return 'UNHEALTHY';
   if (currStatus === 'UNHEALTHY') return 'UNHEALTHY';
 
-  // then prioritize UNKNOWN status
-  if (prevStatus === 'UNKNOWN') return 'UNKNOWN';
-  if (currStatus === 'UNKNOWN') return 'UNKNOWN';
+  // then prioritize TIMEDOUT status
+  if (prevStatus === 'TIMEDOUT') return 'UNHEALTHY';
+  if (currStatus === 'TIMEDOUT') return 'UNHEALTHY';
 
   // guess we're HEALTHY 🏆
   return 'HEALTHY';
@@ -216,7 +216,7 @@ export function createComponentSummary(
 
   const result: ComponentSummary = {
     status: healthCheckResult.status,
-    responseTime: healthCheckResult.responseTime,
+    responseTimeMs: healthCheckResult.responseTimeMs,
     ...(includeMetadata && {
       metadata: healthCheckResult.metadata,
     }),

packages/health-checks/test/health-checks.test.ts

@@ -19,13 +19,13 @@ describe('aggregateHealthStatus(..)', () => {
   const cases: [HealthStatus, HealthStatus, HealthStatus][] = [
     ['HEALTHY', 'HEALTHY', 'HEALTHY'],
     ['HEALTHY', 'UNHEALTHY', 'UNHEALTHY'],
-    ['HEALTHY', 'UNKNOWN', 'UNKNOWN'],
+    ['HEALTHY', 'TIMEDOUT', 'UNHEALTHY'],
     ['UNHEALTHY', 'HEALTHY', 'UNHEALTHY'],
     ['UNHEALTHY', 'UNHEALTHY', 'UNHEALTHY'],
-    ['UNHEALTHY', 'UNKNOWN', 'UNHEALTHY'],
-    ['UNKNOWN', 'HEALTHY', 'UNKNOWN'],
-    ['UNKNOWN', 'UNHEALTHY', 'UNHEALTHY'],
-    ['UNKNOWN', 'UNKNOWN', 'UNKNOWN'],
+    ['UNHEALTHY', 'TIMEDOUT', 'UNHEALTHY'],
+    ['TIMEDOUT', 'HEALTHY', 'UNHEALTHY'],
+    ['TIMEDOUT', 'UNHEALTHY', 'UNHEALTHY'],
+    ['TIMEDOUT', 'TIMEDOUT', 'UNHEALTHY'],
   ];
 
   cases.forEach(([prevStatus, currStatus, expectedStatus]) => {
@@ -61,11 +61,11 @@ describe('run(..)', () => {
       { name: 'component2', check: () => delay(timeout << 2) },
     ];
 
-    const summary = execute(healthChecks, { timeout: timeout });
+    const summary = execute(healthChecks, { timeoutMs: timeout });
     vi.advanceTimersByTime(timeout);
     const { status } = await summary;
 
-    expect(status).toEqual('UNKNOWN');
+    expect(status).toEqual('UNHEALTHY');
   });
 
   it('should return correct component details', async () => {
@@ -101,14 +101,14 @@ describe('run(..)', () => {
       {
         component1: {
           status: 'HEALTHY',
-          responseTime: 100,
+          responseTimeMs: 100,
           metadata: { foo: 'bar' },
         },
       },
       {
         component2: {
           status: 'UNHEALTHY',
-          responseTime: 0,
+          responseTimeMs: 0,
           errorDetails: 'Something went wrong',
           stackTrace: expect.any(String) as string,
         },
@@ -146,7 +146,7 @@ describe('run(..)', () => {
     vi.advanceTimersByTime(HealthCheckConfig.defaults.timeout);
     const { status } = await summary;
 
-    expect(status).toEqual('UNKNOWN');
+    expect(status).toEqual('UNHEALTHY');
   });
 
   it('should filter components based on includeComponents', async () => {
@@ -188,21 +188,21 @@ describe('runWithTimeout(..)', () => {
 
     const result = executeWithTimeout(healthCheck, 100);
     vi.advanceTimersByTime(50);
-    const { responseTime, status } = await result;
+    const { responseTimeMs, status } = await result;
 
     expect(status).toEqual('HEALTHY');
-    expect(responseTime).toEqual(50);
+    expect(responseTimeMs).toEqual(50);
   });
 
-  it('should resolve with UNKNOWN status for timed out check', async () => {
+  it('should resolve with TIMEDOUT status for timed out check', async () => {
     const healthCheck: HealthCheck = { name: 'testComponent', check: () => delay(200) };
 
     const result = executeWithTimeout(healthCheck, 100);
     vi.advanceTimersByTime(100);
-    const { responseTime, status } = await result;
+    const { responseTimeMs, status } = await result;
 
-    expect(status).toEqual('UNKNOWN');
-    expect(responseTime).toEqual(100);
+    expect(status).toEqual('TIMEDOUT');
+    expect(responseTimeMs).toEqual(100);
   });
 
   it('should resolve with UNHEALTHY status for failed check', async () => {
@@ -215,10 +215,10 @@ describe('runWithTimeout(..)', () => {
 
     const result = executeWithTimeout(healthCheck, 100);
     vi.advanceTimersByTime(100);
-    const { responseTime, status } = await result;
+    const { responseTimeMs, status } = await result;
 
     expect(status).toEqual('UNHEALTHY');
-    expect(responseTime).toEqual(0);
+    expect(responseTimeMs).toEqual(0);
   });
 
   it('should include component metadata in the result', async () => {
@@ -238,7 +238,7 @@ describe('createComponentSummary(..)', () => {
       {
         status: 'HEALTHY',
         name: 'testComponent',
-        responseTime: 50,
+        responseTimeMs: 50,
         metadata: { foo: 'bar' },
       },
       true,
@@ -247,7 +247,7 @@ describe('createComponentSummary(..)', () => {
     expect(summary).toEqual({
       testComponent: {
         status: 'HEALTHY',
-        responseTime: 50,
+        responseTimeMs: 50,
         metadata: { foo: 'bar' },
       },
     });
@@ -258,7 +258,7 @@ describe('createComponentSummary(..)', () => {
       {
         status: 'UNHEALTHY',
         name: 'testComponent',
-        responseTime: 50,
+        responseTimeMs: 50,
         errorDetails: 'Something went wrong',
         metadata: { foo: 'bar' },
       },
@@ -268,7 +268,7 @@ describe('createComponentSummary(..)', () => {
     expect(summary).toEqual({
       testComponent: {
         status: 'UNHEALTHY',
-        responseTime: 50,
+        responseTimeMs: 50,
         errorDetails: 'Something went wrong',
         metadata: { foo: 'bar' },
       },
@@ -280,7 +280,7 @@ describe('createComponentSummary(..)', () => {
       {
         status: 'UNHEALTHY',
         name: 'testComponent',
-        responseTime: 50,
+        responseTimeMs: 50,
         errorDetails: 'Something went wrong',
         metadata: { foo: 'bar' },
       },
@@ -290,7 +290,7 @@ describe('createComponentSummary(..)', () => {
     expect(summary).toEqual({
       testComponent: {
         status: 'UNHEALTHY',
-        responseTime: 50,
+        responseTimeMs: 50,
       },
     });
   });
@@ -300,7 +300,7 @@ describe('getStatusCode(..)', () => {
   const cases: [HealthStatus, number][] = [
     ['HEALTHY', 200],
     ['UNHEALTHY', 503],
-    ['UNKNOWN', 500],
+    ['TIMEDOUT', 408],
   ];
 
   cases.forEach(([healthStatus, expectedHttpStatus]) => {