@checkstack/healthcheck-redis-backend 0.1.13 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/healthcheck-redis-backend
 
+## 0.2.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.1.14
+
+### 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.1.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-redis-backend",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -9,15 +9,15 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.1",
-    "@checkstack/common": "0.6.0",
-    "@checkstack/healthcheck-common": "0.7.0",
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1",
     "ioredis": "^5.3.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "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/command-collector.test.ts

@@ -79,7 +79,7 @@ describe("CommandCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average response time and success rate", () => {
       const collector = new CommandCollector();
       const runs = [
@@ -101,10 +101,11 @@ describe("CommandCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.avgResponseTimeMs).toBe(10);
-      expect(aggregated.successRate).toBe(100);
+      expect(aggregated.avgResponseTimeMs.avg).toBe(10);
+      expect(aggregated.successRate.rate).toBe(100);
     });
 
     it("should calculate success rate correctly", () => {
@@ -128,9 +129,10 @@ describe("CommandCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      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/command-collector.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeRate,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedRate,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -53,20 +59,24 @@ const commandResultSchema = healthResultSchema({
 
 export type CommandResult = z.infer<typeof commandResultSchema>;
 
-const commandAggregatedSchema = healthResultSchema({
-  avgResponseTimeMs: healthResultNumber({
+// Aggregated result fields definition
+const commandAggregatedFields = {
+  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 CommandAggregatedResult = z.infer<typeof commandAggregatedSchema>;
+// Type inferred from field definitions
+export type CommandAggregatedResult = InferAggregatedResult<
+  typeof commandAggregatedFields
+>;
 
 // ============================================================================
 // COMMAND COLLECTOR
@@ -76,15 +86,12 @@ export type CommandAggregatedResult = z.infer<typeof commandAggregatedSchema>;
  * Built-in Redis command collector.
  * Executes Redis commands and checks results.
  */
-export class CommandCollector
-  implements
-    CollectorStrategy<
-      RedisTransportClient,
-      CommandConfig,
-      CommandResult,
-      CommandAggregatedResult
-    >
-{
+export class CommandCollector implements CollectorStrategy<
+  RedisTransportClient,
+  CommandConfig,
+  CommandResult,
+  CommandAggregatedResult
+> {
   id = "command";
   displayName = "Redis Command";
   description = "Execute a Redis command and check the result";
@@ -95,9 +102,9 @@ export class CommandCollector
 
   config = new Versioned({ version: 1, schema: commandConfigSchema });
   result = new Versioned({ version: 1, schema: commandResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: commandAggregatedSchema,
+    fields: commandAggregatedFields,
   });
 
   async execute({
@@ -127,28 +134,18 @@ export class CommandCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<CommandResult>[]
+  mergeResult(
+    existing: CommandAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<CommandResult>,
   ): CommandAggregatedResult {
-    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;
+    const metadata = run.metadata;
 
     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,
+        metadata?.responseTimeMs,
+      ),
+      successRate: mergeRate(existing?.successRate, metadata?.success),
     };
   }
 }

package/src/strategy.test.ts

@@ -12,17 +12,17 @@ describe("RedisHealthCheckStrategy", () => {
       pingResponse?: string;
       infoResponse?: string;
       pingError?: Error;
-    } = {}
+    } = {},
   ): RedisConnection => ({
     ping: mock(() =>
       config.pingError
         ? Promise.reject(config.pingError)
-        : Promise.resolve(config.pingResponse ?? "PONG")
+        : Promise.resolve(config.pingResponse ?? "PONG"),
     ),
     info: mock(() =>
       Promise.resolve(
-        config.infoResponse ?? "redis_version:7.0.0\r\nrole:master\r\n"
-      )
+        config.infoResponse ?? "redis_version:7.0.0\r\nrole:master\r\n",
+      ),
     ),
     get: mock(() => Promise.resolve(undefined)),
     quit: mock(() => Promise.resolve("OK")),
@@ -35,12 +35,12 @@ describe("RedisHealthCheckStrategy", () => {
       infoResponse?: string;
       pingError?: Error;
       connectError?: Error;
-    } = {}
+    } = {},
   ): RedisClient => ({
     connect: mock(() =>
       config.connectError
         ? Promise.reject(config.connectError)
-        : Promise.resolve(createMockConnection(config))
+        : Promise.resolve(createMockConnection(config)),
     ),
   });
 
@@ -63,7 +63,7 @@ describe("RedisHealthCheckStrategy", () => {
 
     it("should throw for connection error", async () => {
       const strategy = new RedisHealthCheckStrategy(
-        createMockClient({ connectError: new Error("Connection refused") })
+        createMockClient({ connectError: new Error("Connection refused") }),
       );
 
       await expect(
@@ -71,7 +71,7 @@ describe("RedisHealthCheckStrategy", () => {
           host: "localhost",
           port: 6379,
           timeout: 5000,
-        })
+        }),
       ).rejects.toThrow("Connection refused");
     });
   });
@@ -94,7 +94,7 @@ describe("RedisHealthCheckStrategy", () => {
 
     it("should return error for ping failure", async () => {
       const strategy = new RedisHealthCheckStrategy(
-        createMockClient({ pingError: new Error("NOAUTH") })
+        createMockClient({ pingError: new Error("NOAUTH") }),
       );
       const connectedClient = await strategy.createClient({
         host: "localhost",
@@ -128,7 +128,7 @@ describe("RedisHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const strategy = new RedisHealthCheckStrategy();
       const runs = [
@@ -160,35 +160,34 @@ describe("RedisHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.avgConnectionTime).toBe(10);
-      expect(aggregated.successRate).toBe(100);
-      expect(aggregated.errorCount).toBe(0);
+      expect(aggregated.avgConnectionTime.avg).toBe(10);
+      expect(aggregated.successRate.rate).toBe(100);
+      expect(aggregated.errorCount.count).toBe(0);
     });
 
     it("should count errors", () => {
       const strategy = new RedisHealthCheckStrategy();
-      const runs = [
-        {
-          id: "1",
-          status: "unhealthy" as const,
-          latencyMs: 100,
-          checkId: "c1",
-          timestamp: new Date(),
-          metadata: {
-            connected: false,
-            connectionTimeMs: 100,
-            pingSuccess: false,
-            error: "Connection refused",
-          },
+      const run = {
+        id: "1",
+        status: "unhealthy" as const,
+        latencyMs: 100,
+        checkId: "c1",
+        timestamp: new Date(),
+        metadata: {
+          connected: false,
+          connectionTimeMs: 100,
+          pingSuccess: false,
+          error: "Connection refused",
         },
-      ];
+      };
 
-      const aggregated = strategy.aggregateResult(runs);
+      const aggregated = strategy.mergeResult(undefined, run);
 
-      expect(aggregated.errorCount).toBe(1);
-      expect(aggregated.successRate).toBe(0);
+      expect(aggregated.errorCount.count).toBe(1);
+      expect(aggregated.successRate.rate).toBe(0);
     });
   });
 });

package/src/strategy.ts

@@ -3,11 +3,21 @@ import {
   HealthCheckStrategy,
   HealthCheckRunForAggregation,
   Versioned,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  aggregatedRate,
+  aggregatedCounter,
+  mergeAverage,
+  mergeRate,
+  mergeCounter,
+  mergeMinMax,
   z,
   configString,
   configNumber,
   configBoolean,
   type ConnectedClient,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
@@ -75,32 +85,32 @@ const redisResultSchema = healthResultSchema({
 
 type RedisResult = z.infer<typeof redisResultSchema>;
 
-/**
- * Aggregated metadata for buckets.
- */
-const redisAggregatedSchema = healthResultSchema({
-  avgConnectionTime: healthResultNumber({
+/** Aggregated field definitions for bucket merging */
+const redisAggregatedFields = {
+  avgConnectionTime: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Connection Time",
     "x-chart-unit": "ms",
   }),
-  maxConnectionTime: healthResultNumber({
+  maxConnectionTime: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Connection Time",
     "x-chart-unit": "ms",
   }),
-  successRate: healthResultNumber({
+  successRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Success Rate",
     "x-chart-unit": "%",
   }),
-  errorCount: healthResultNumber({
+  errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
   }),
-});
+};
 
-type RedisAggregatedResult = z.infer<typeof redisAggregatedSchema>;
+type RedisAggregatedResult = InferAggregatedResult<
+  typeof redisAggregatedFields
+>;
 
 // ============================================================================
 // REDIS CLIENT INTERFACE (for testability)
@@ -160,15 +170,12 @@ const defaultRedisClient: RedisClient = {
 // STRATEGY
 // ============================================================================
 
-export class RedisHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      RedisConfig,
-      RedisTransportClient,
-      RedisResult,
-      RedisAggregatedResult
-    >
-{
+export class RedisHealthCheckStrategy implements HealthCheckStrategy<
+  RedisConfig,
+  RedisTransportClient,
+  RedisResult,
+  typeof redisAggregatedFields
+> {
   id = "redis";
   displayName = "Redis Health Check";
   description = "Redis server connectivity and health monitoring";
@@ -205,58 +212,38 @@ export class RedisHealthCheckStrategy
     ],
   });
 
-  aggregatedResult: Versioned<RedisAggregatedResult> = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: redisAggregatedSchema,
+    fields: redisAggregatedFields,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<RedisResult>[]
+  mergeResult(
+    existing: RedisAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<RedisResult>,
   ): RedisAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
+    const metadata = run.metadata;
 
-    if (validRuns.length === 0) {
-      return {
-        avgConnectionTime: 0,
-        maxConnectionTime: 0,
-        successRate: 0,
-        errorCount: 0,
-      };
-    }
+    const avgConnectionTime = mergeAverage(
+      existing?.avgConnectionTime,
+      metadata?.connectionTimeMs,
+    );
 
-    const connectionTimes = validRuns
-      .map((r) => r.metadata?.connectionTimeMs)
-      .filter((t): t is number => typeof t === "number");
+    const maxConnectionTime = mergeMinMax(
+      existing?.maxConnectionTime,
+      metadata?.connectionTimeMs,
+    );
 
-    const avgConnectionTime =
-      connectionTimes.length > 0
-        ? Math.round(
-            connectionTimes.reduce((a, b) => a + b, 0) / connectionTimes.length
-          )
-        : 0;
+    const isSuccess = metadata?.connected ?? false;
+    const successRate = mergeRate(existing?.successRate, isSuccess);
 
-    const maxConnectionTime =
-      connectionTimes.length > 0 ? Math.max(...connectionTimes) : 0;
+    const hasError = metadata?.error !== undefined;
+    const errorCount = mergeCounter(existing?.errorCount, hasError);
 
-    const successCount = validRuns.filter(
-      (r) => r.metadata?.connected === true
-    ).length;
-    const successRate = Math.round((successCount / validRuns.length) * 100);
-
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
-
-    return {
-      avgConnectionTime,
-      maxConnectionTime,
-      successRate,
-      errorCount,
-    };
+    return { avgConnectionTime, maxConnectionTime, successRate, errorCount };
   }
 
   async createClient(
-    config: RedisConfigInput
+    config: RedisConfigInput,
   ): Promise<ConnectedClient<RedisTransportClient>> {
     const validatedConfig = this.config.validate(config);