@checkstack/healthcheck-http-backend 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/healthcheck-http-backend
 
+## 0.3.0
+
+### Minor Changes
+
+- 3dd1914: Migrate health check strategies to VersionedAggregated with \_type discriminator
+
+  All 13 health check strategies now use `VersionedAggregated` for their `aggregatedResult` property, enabling automatic bucket merging with 100% mathematical fidelity.
+
+  **Key changes:**
+
+  - **`_type` discriminator**: All aggregated state objects now include a required `_type` field (`"average"`, `"rate"`, `"counter"`, `"minmax"`) for reliable type detection
+  - The `HealthCheckStrategy` interface now requires `aggregatedResult` to be a `VersionedAggregated<AggregatedResultShape>`
+  - Strategy/collector `mergeResult` methods return state objects with `_type` (e.g., `{ _type: "average", _sum, _count, avg }`)
+  - `mergeAggregatedBucketResults`, `combineBuckets`, and `reaggregateBuckets` now require `registry` and `strategyId` parameters
+  - `HealthCheckService` constructor now requires both `registry` and `collectorRegistry` parameters
+  - Frontend `extractComputedValue` now uses `_type` discriminator for robust type detection
+
+  **Breaking Change**: State objects now require `_type`. Merge functions automatically add `_type` to output. The bucket merging functions and `HealthCheckService` now require additional required parameters.
+
+### Patch Changes
+
+- Updated dependencies [3dd1914]
+  - @checkstack/backend-api@0.7.0
+
+## 0.2.5
+
+### Patch Changes
+
+- 48c2080: Migrate aggregation from batch to incremental (`mergeResult`)
+
+  ### Breaking Changes (Internal)
+
+  - Replaced `aggregateResult(runs[])` with `mergeResult(existing, run)` interface across all HealthCheckStrategy and CollectorStrategy implementations
+
+  ### New Features
+
+  - Added incremental aggregation utilities in `@checkstack/backend-api`:
+    - `mergeCounter()` - track occurrences
+    - `mergeAverage()` - track sum/count, compute avg
+    - `mergeRate()` - track success/total, compute %
+    - `mergeMinMax()` - track min/max values
+  - Exported Zod schemas for internal state: `averageStateSchema`, `rateStateSchema`, `minMaxStateSchema`, `counterStateSchema`
+
+  ### Improvements
+
+  - Enables O(1) storage overhead by maintaining incremental aggregation state
+  - Prepares for real-time hourly aggregation without batch accumulation
+
+- Updated dependencies [f676e11]
+- Updated dependencies [48c2080]
+  - @checkstack/common@0.6.2
+  - @checkstack/backend-api@0.6.0
+  - @checkstack/healthcheck-common@0.8.2
+
 ## 0.2.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-http-backend",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -9,16 +9,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.1",
-    "@checkstack/healthcheck-common": "0.7.0",
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/healthcheck-common": "0.8.1",
     "jsonpath-plus": "^10.3.0",
-    "@checkstack/common": "0.6.0"
+    "@checkstack/common": "0.6.1"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.8",
     "typescript": "^5.0.0",
-    "@checkstack/tsconfig": "0.0.2",
-    "@checkstack/scripts": "0.1.0"
+    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/scripts": "0.1.1"
   }
 }

package/src/request-collector.test.ts

@@ -8,7 +8,7 @@ describe("RequestCollector", () => {
       statusCode?: number;
       statusText?: string;
       body?: string;
-    } = {}
+    } = {},
   ): HttpTransportClient => ({
     exec: mock(() =>
       Promise.resolve({
@@ -16,7 +16,7 @@ describe("RequestCollector", () => {
         statusText: response.statusText ?? "OK",
         headers: {},
         body: response.body ?? "",
-      })
+      }),
     ),
   });
 
@@ -89,7 +89,7 @@ describe("RequestCollector", () => {
             "Content-Type": "application/json",
             Authorization: "Bearer token",
           },
-        })
+        }),
       );
     });
 
@@ -111,12 +111,12 @@ describe("RequestCollector", () => {
       expect(client.exec).toHaveBeenCalledWith(
         expect.objectContaining({
           body: '{"key":"value"}',
-        })
+        }),
       );
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average response time", () => {
       const collector = new RequestCollector();
       const runs = [
@@ -152,10 +152,12 @@ describe("RequestCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.avgResponseTimeMs).toBe(75);
-      expect(aggregated.successRate).toBe(100);
+      expect(aggregated.avgResponseTimeMs.avg).toBe(75);
+      expect(aggregated.successRate.rate).toBe(100);
     });
 
     it("should calculate success rate correctly", () => {
@@ -193,9 +195,11 @@ describe("RequestCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.successRate).toBe(50);
+      expect(aggregated.successRate.rate).toBe(50);
     });
   });
 

package/src/request-collector.ts

@@ -5,6 +5,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeRate,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedRate,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -76,20 +82,24 @@ const requestResultSchema = healthResultSchema({
 
 export type RequestResult = z.infer<typeof requestResultSchema>;
 
-const requestAggregatedSchema = healthResultSchema({
-  avgResponseTimeMs: healthResultNumber({
+// Aggregated result fields definition
+const requestAggregatedFields = {
+  avgResponseTimeMs: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Response Time",
     "x-chart-unit": "ms",
   }),
-  successRate: healthResultNumber({
+  successRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Success Rate",
     "x-chart-unit": "%",
   }),
-});
+};
 
-export type RequestAggregatedResult = z.infer<typeof requestAggregatedSchema>;
+// Type inferred automatically from field definitions
+export type RequestAggregatedResult = InferAggregatedResult<
+  typeof requestAggregatedFields
+>;
 
 // ============================================================================
 // REQUEST COLLECTOR
@@ -115,9 +125,9 @@ export class RequestCollector implements CollectorStrategy<
 
   config = new Versioned({ version: 1, schema: requestConfigSchema });
   result = new Versioned({ version: 1, schema: requestResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: requestAggregatedSchema,
+    fields: requestAggregatedFields,
   });
 
   async execute({
@@ -162,28 +172,16 @@ export class RequestCollector implements CollectorStrategy<
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<RequestResult>[],
+  mergeResult(
+    existing: RequestAggregatedResult | undefined,
+    newRun: HealthCheckRunForAggregation<RequestResult>,
   ): RequestAggregatedResult {
-    const times = runs
-      .map((r) => r.metadata?.responseTimeMs)
-      .filter((v): v is number => typeof v === "number");
-
-    const successes = runs
-      .map((r) => r.metadata?.success)
-      .filter((v): v is boolean => typeof v === "boolean");
-
-    const successCount = successes.filter(Boolean).length;
-
     return {
-      avgResponseTimeMs:
-        times.length > 0
-          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
-          : 0,
-      successRate:
-        successes.length > 0
-          ? Math.round((successCount / successes.length) * 100)
-          : 0,
+      avgResponseTimeMs: mergeAverage(
+        existing?.avgResponseTimeMs,
+        newRun.metadata?.responseTimeMs,
+      ),
+      successRate: mergeRate(existing?.successRate, newRun.metadata?.success),
     };
   }
 }

package/src/strategy.test.ts

@@ -31,7 +31,7 @@ describe("HttpHealthCheckStrategy", () => {
           status: 200,
           statusText: "OK",
           headers: { "Content-Type": "application/json" },
-        })
+        }),
       );
 
       const connectedClient = await strategy.createClient({ timeout: 5000 });
@@ -50,7 +50,7 @@ describe("HttpHealthCheckStrategy", () => {
 
     it("should return 404 status for not found", async () => {
       spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response(null, { status: 404, statusText: "Not Found" })
+        new Response(null, { status: 404, statusText: "Not Found" }),
       );
 
       const connectedClient = await strategy.createClient({ timeout: 5000 });
@@ -69,7 +69,7 @@ describe("HttpHealthCheckStrategy", () => {
       let capturedHeaders: Record<string, string> | undefined;
       spyOn(globalThis, "fetch").mockImplementation((async (
         _url: RequestInfo | URL,
-        options?: RequestInit
+        options?: RequestInit,
       ) => {
         capturedHeaders = options?.headers as Record<string, string>;
         return new Response(null, { status: 200 });
@@ -99,7 +99,7 @@ describe("HttpHealthCheckStrategy", () => {
         new Response(JSON.stringify(responseBody), {
           status: 200,
           headers: { "Content-Type": "application/json" },
-        })
+        }),
       );
 
       const connectedClient = await strategy.createClient({ timeout: 5000 });
@@ -119,7 +119,7 @@ describe("HttpHealthCheckStrategy", () => {
         new Response("Hello World", {
           status: 200,
           headers: { "Content-Type": "text/plain" },
-        })
+        }),
       );
 
       const connectedClient = await strategy.createClient({ timeout: 5000 });
@@ -138,7 +138,7 @@ describe("HttpHealthCheckStrategy", () => {
       let capturedBody: string | undefined;
       spyOn(globalThis, "fetch").mockImplementation((async (
         _url: RequestInfo | URL,
-        options?: RequestInit
+        options?: RequestInit,
       ) => {
         capturedBody = options?.body as string;
         return new Response(null, { status: 201 });
@@ -161,7 +161,7 @@ describe("HttpHealthCheckStrategy", () => {
       let capturedMethod: string | undefined;
       spyOn(globalThis, "fetch").mockImplementation((async (
         _url: RequestInfo | URL,
-        options?: RequestInit
+        options?: RequestInit,
       ) => {
         capturedMethod = options?.method;
         return new Response(null, { status: 200 });
@@ -180,7 +180,7 @@ describe("HttpHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should count errors correctly", () => {
       const runs = [
         {
@@ -213,9 +213,12 @@ describe("HttpHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
+      aggregated = strategy.mergeResult(aggregated, runs[2]);
 
-      expect(aggregated.errorCount).toBe(2);
+      expect(aggregated.errorCount.count).toBe(2);
     });
 
     it("should return zero errors when all runs succeed", () => {
@@ -238,9 +241,11 @@ describe("HttpHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.errorCount).toBe(0);
+      expect(aggregated.errorCount.count).toBe(0);
     });
   });
 });

package/src/strategy.ts

@@ -2,11 +2,14 @@ import {
   HealthCheckStrategy,
   HealthCheckRunForAggregation,
   Versioned,
+  VersionedAggregated,
+  aggregatedCounter,
+  mergeCounter,
   z,
+  type InferAggregatedResult,
   type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
-  healthResultNumber,
   healthResultString,
   healthResultSchema,
 } from "@checkstack/healthcheck-common";
@@ -57,29 +60,26 @@ const httpResultMetadataSchema = healthResultSchema({
 
 type HttpResultMetadata = z.infer<typeof httpResultMetadataSchema>;
 
-/** Aggregated metadata for buckets */
-const httpAggregatedMetadataSchema = healthResultSchema({
-  errorCount: healthResultNumber({
+/** Aggregated field definitions for bucket merging */
+const httpAggregatedFields = {
+  errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
   }),
-});
+};
 
-type HttpAggregatedMetadata = z.infer<typeof httpAggregatedMetadataSchema>;
+type HttpAggregatedResult = InferAggregatedResult<typeof httpAggregatedFields>;
 
 // ============================================================================
 // STRATEGY
 // ============================================================================
 
-export class HttpHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      HttpHealthCheckConfig,
-      HttpTransportClient,
-      HttpResultMetadata,
-      HttpAggregatedMetadata
-    >
-{
+export class HttpHealthCheckStrategy implements HealthCheckStrategy<
+  HttpHealthCheckConfig,
+  HttpTransportClient,
+  HttpResultMetadata,
+  typeof httpAggregatedFields
+> {
   id = "http";
   displayName = "HTTP/HTTPS Health Check";
   description = "HTTP endpoint health monitoring";
@@ -114,23 +114,19 @@ export class HttpHealthCheckStrategy
     schema: httpResultMetadataSchema,
   });
 
-  aggregatedResult: Versioned<HttpAggregatedMetadata> = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: httpAggregatedMetadataSchema,
+    fields: httpAggregatedFields,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<HttpResultMetadata>[]
-  ): HttpAggregatedMetadata {
-    let errorCount = 0;
-
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-      }
-    }
-
-    return { errorCount };
+  mergeResult(
+    existing: HttpAggregatedResult | undefined,
+    newRun: HealthCheckRunForAggregation<HttpResultMetadata>,
+  ): HttpAggregatedResult {
+    const hasError = !!newRun.metadata?.error;
+    return {
+      errorCount: mergeCounter(existing?.errorCount, hasError),
+    };
   }
 
   /**
@@ -138,7 +134,7 @@ export class HttpHealthCheckStrategy
    * All request parameters come from the collector (RequestCollector).
    */
   async createClient(
-    config: HttpHealthCheckConfig
+    config: HttpHealthCheckConfig,
   ): Promise<ConnectedClient<HttpTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
@@ -147,7 +143,7 @@ export class HttpHealthCheckStrategy
         const controller = new AbortController();
         const timeoutId = setTimeout(
           () => controller.abort(),
-          request.timeout ?? validatedConfig.timeout
+          request.timeout ?? validatedConfig.timeout,
         );
 
         try {