@checkstack/backend-api 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/backend-api
 
+## 0.7.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
+
+- @checkstack/queue-api@0.2.4
+
+## 0.6.0
+
+### Minor 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
+
+### Patch Changes
+
+- Updated dependencies [f676e11]
+  - @checkstack/common@0.6.2
+  - @checkstack/signal-common@0.1.6
+  - @checkstack/queue-api@0.2.3
+
 ## 0.5.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -9,9 +9,10 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.6.0",
-    "@checkstack/queue-api": "0.2.1",
-    "@checkstack/signal-common": "0.1.4",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1",
+    "@checkstack/queue-api": "0.2.2",
+    "@checkstack/signal-common": "0.1.5",
     "@orpc/client": "^1.13.2",
     "@orpc/openapi": "^1.13.2",
     "@orpc/server": "^1.13.2",
@@ -23,8 +24,8 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@checkstack/tsconfig": "0.0.2",
-    "@checkstack/scripts": "0.1.0"
+    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/scripts": "0.1.1"
   },
   "peerDependencies": {
     "hono": "^4.0.0",

package/src/aggregated-result.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from "bun:test";
+import {
+  aggregatedAverage,
+  aggregatedRate,
+  aggregatedCounter,
+  aggregatedMinMax,
+  buildAggregatedResultSchema,
+} from "./aggregated-result";
+import { getHealthResultMeta } from "@checkstack/healthcheck-common";
+
+describe("aggregatedAverage", () => {
+  it("creates field with correct type and merge function", () => {
+    const field = aggregatedAverage({
+      "x-chart-type": "line",
+      "x-chart-label": "Avg Response Time",
+    });
+
+    expect(field.type).toBe("average");
+    expect(field.meta["x-chart-label"]).toBe("Avg Response Time");
+  });
+
+  it("mergeStates correctly merges two average states", () => {
+    const field = aggregatedAverage({});
+    const merged = field.mergeStates(
+      { _sum: 100, _count: 2, avg: 50 },
+      { _sum: 200, _count: 2, avg: 100 },
+    );
+    expect(merged).toEqual({ _type: "average", _sum: 300, _count: 4, avg: 75 });
+  });
+
+  it("getDisplayValue returns avg", () => {
+    const field = aggregatedAverage({});
+    expect(field.getDisplayValue({ _sum: 100, _count: 2, avg: 50 })).toBe(50);
+  });
+});
+
+describe("aggregatedRate", () => {
+  it("creates field with correct type", () => {
+    const field = aggregatedRate({
+      "x-chart-type": "gauge",
+      "x-chart-label": "Success Rate",
+    });
+
+    expect(field.type).toBe("rate");
+  });
+
+  it("mergeStates correctly merges two rate states", () => {
+    const field = aggregatedRate({});
+    const merged = field.mergeStates(
+      { _success: 3, _total: 4, rate: 75 },
+      { _success: 7, _total: 10, rate: 70 },
+    );
+    expect(merged.rate).toBe(71);
+  });
+
+  it("getDisplayValue returns rate", () => {
+    const field = aggregatedRate({});
+    expect(field.getDisplayValue({ _success: 5, _total: 10, rate: 50 })).toBe(
+      50,
+    );
+  });
+});
+
+describe("aggregatedCounter", () => {
+  it("creates field with correct type", () => {
+    const field = aggregatedCounter({
+      "x-chart-type": "counter",
+    });
+
+    expect(field.type).toBe("counter");
+  });
+
+  it("mergeStates correctly merges two counter states", () => {
+    const field = aggregatedCounter({});
+    const merged = field.mergeStates({ count: 5 }, { count: 3 });
+    expect(merged).toEqual({ _type: "counter", count: 8 });
+  });
+});
+
+describe("aggregatedMinMax", () => {
+  it("creates field with correct type", () => {
+    const field = aggregatedMinMax({
+      "x-chart-type": "line",
+    });
+
+    expect(field.type).toBe("minmax");
+  });
+
+  it("mergeStates correctly merges two minmax states", () => {
+    const field = aggregatedMinMax({});
+    const merged = field.mergeStates(
+      { min: 10, max: 50 },
+      { min: 5, max: 100 },
+    );
+    expect(merged).toEqual({ _type: "minmax", min: 5, max: 100 });
+  });
+});
+
+describe("buildAggregatedResultSchema", () => {
+  it("creates schema with field keys mapping to state types", () => {
+    const { schema } = buildAggregatedResultSchema({
+      avgResponseTimeMs: aggregatedAverage({}),
+      successRate: aggregatedRate({}),
+    });
+
+    // Should parse valid data with _type - field keys now map directly to state objects
+    const result = schema.parse({
+      avgResponseTimeMs: { _type: "average", _sum: 100, _count: 1, avg: 100 },
+      successRate: { _type: "rate", _success: 95, _total: 100, rate: 95 },
+    });
+
+    expect(result.avgResponseTimeMs.avg).toBe(100);
+    expect(result.successRate.rate).toBe(95);
+  });
+
+  it("mergeAggregatedResults correctly merges two results", () => {
+    const { mergeAggregatedResults } = buildAggregatedResultSchema({
+      avgResponseTimeMs: aggregatedAverage({}),
+      successRate: aggregatedRate({}),
+    });
+
+    const a = {
+      avgResponseTimeMs: {
+        _type: "average" as const,
+        _sum: 100,
+        _count: 2,
+        avg: 50,
+      },
+      successRate: {
+        _type: "rate" as const,
+        _success: 3,
+        _total: 4,
+        rate: 75,
+      },
+    };
+
+    const b = {
+      avgResponseTimeMs: {
+        _type: "average" as const,
+        _sum: 200,
+        _count: 2,
+        avg: 100,
+      },
+      successRate: {
+        _type: "rate" as const,
+        _success: 7,
+        _total: 10,
+        rate: 70,
+      },
+    };
+
+    const merged = mergeAggregatedResults(a, b);
+
+    // Average: (100 + 200) / 4 = 75
+    expect(merged.avgResponseTimeMs.avg).toBe(75);
+    expect(merged.avgResponseTimeMs).toEqual({
+      _type: "average",
+      _sum: 300,
+      _count: 4,
+      avg: 75,
+    });
+
+    // Rate: 10/14 ≈ 71%
+    expect(merged.successRate.rate).toBe(71);
+    expect(merged.successRate).toEqual({
+      _type: "rate",
+      _success: 10,
+      _total: 14,
+      rate: 71,
+    });
+  });
+
+  it("mergeAggregatedResults handles undefined first argument", () => {
+    const { mergeAggregatedResults } = buildAggregatedResultSchema({
+      avgResponseTimeMs: aggregatedAverage({}),
+    });
+
+    const b = {
+      avgResponseTimeMs: {
+        _type: "average" as const,
+        _sum: 100,
+        _count: 1,
+        avg: 100,
+      },
+    };
+
+    const merged = mergeAggregatedResults(undefined, b);
+
+    expect(merged.avgResponseTimeMs.avg).toBe(100);
+    expect(merged.avgResponseTimeMs).toEqual({
+      _type: "average",
+      _sum: 100,
+      _count: 1,
+      avg: 100,
+    });
+  });
+});
+
+describe("chart metadata registration", () => {
+  it("aggregatedAverage schema has chart metadata registered", () => {
+    const field = aggregatedAverage({
+      "x-chart-type": "line",
+      "x-chart-label": "Avg Response Time",
+      "x-chart-unit": "ms",
+    });
+
+    // The stateSchema should have metadata registered via healthResultRegistry
+    // We can verify by checking that the schema is registered
+    const meta = getHealthResultMeta(field.stateSchema);
+
+    expect(meta).toBeDefined();
+    expect(meta?.["x-chart-type"]).toBe("line");
+    expect(meta?.["x-chart-label"]).toBe("Avg Response Time");
+    expect(meta?.["x-chart-unit"]).toBe("ms");
+  });
+
+  it("aggregatedRate schema has chart metadata registered", () => {
+    const field = aggregatedRate({
+      "x-chart-type": "gauge",
+      "x-chart-label": "Success Rate",
+      "x-chart-unit": "%",
+    });
+
+    const meta = getHealthResultMeta(field.stateSchema);
+
+    expect(meta).toBeDefined();
+    expect(meta?.["x-chart-type"]).toBe("gauge");
+    expect(meta?.["x-chart-label"]).toBe("Success Rate");
+  });
+
+  it("aggregatedCounter schema has chart metadata registered", () => {
+    const field = aggregatedCounter({
+      "x-chart-type": "counter",
+      "x-chart-label": "Error Count",
+    });
+
+    const meta = getHealthResultMeta(field.stateSchema);
+
+    expect(meta).toBeDefined();
+    expect(meta?.["x-chart-type"]).toBe("counter");
+    expect(meta?.["x-chart-label"]).toBe("Error Count");
+  });
+
+  it("aggregatedMinMax schema has chart metadata registered", () => {
+    const field = aggregatedMinMax({
+      "x-chart-type": "line",
+      "x-chart-label": "Latency Range",
+    });
+
+    const meta = getHealthResultMeta(field.stateSchema);
+
+    expect(meta).toBeDefined();
+    expect(meta?.["x-chart-type"]).toBe("line");
+    expect(meta?.["x-chart-label"]).toBe("Latency Range");
+  });
+
+  it("each field instance has unique metadata", () => {
+    const field1 = aggregatedAverage({
+      "x-chart-type": "line",
+      "x-chart-label": "First Field",
+    });
+
+    const field2 = aggregatedAverage({
+      "x-chart-type": "gauge",
+      "x-chart-label": "Second Field",
+    });
+
+    const meta1 = getHealthResultMeta(field1.stateSchema);
+    const meta2 = getHealthResultMeta(field2.stateSchema);
+
+    // Each field should have its own metadata
+    expect(meta1?.["x-chart-label"]).toBe("First Field");
+    expect(meta2?.["x-chart-label"]).toBe("Second Field");
+    expect(meta1?.["x-chart-type"]).toBe("line");
+    expect(meta2?.["x-chart-type"]).toBe("gauge");
+  });
+});