@checkstack/backend-api 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/backend-api
 
+## 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.6.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -9,9 +9,9 @@
     "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/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 +23,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/collector-strategy.ts

@@ -29,7 +29,7 @@ export interface CollectorStrategy<
   TClient extends TransportClient<unknown, unknown>,
   TConfig = unknown,
   TResult = Record<string, unknown>,
-  TAggregated = Record<string, unknown>
+  TAggregated = Record<string, unknown>,
 > {
   /** Unique identifier for this collector */
   id: string;
@@ -76,8 +76,15 @@ export interface CollectorStrategy<
   }): Promise<CollectorResult<TResult>>;
 
   /**
-   * Aggregate results from multiple runs into a summary.
-   * Called during retention processing.
+   * Incrementally merge new run data into an existing aggregate.
+   * Called after each health check run for real-time aggregation.
+   *
+   * @param existing - Existing aggregated result (undefined for first run in bucket)
+   * @param newRun - Data from the new run to merge
+   * @returns Updated aggregated result
    */
-  aggregateResult(runs: HealthCheckRunForAggregation<TResult>[]): TAggregated;
+  mergeResult(
+    existing: TAggregated | undefined,
+    newRun: HealthCheckRunForAggregation<TResult>,
+  ): TAggregated;
 }

package/src/health-check.ts

@@ -13,10 +13,10 @@ export interface HealthCheckResult<TMetadata = Record<string, unknown>> {
 }
 
 /**
- * Raw run data for aggregation (passed to aggregateMetadata function).
+ * Raw run data for aggregation (passed to mergeResult function).
  */
 export interface HealthCheckRunForAggregation<
-  TResultMetadata = Record<string, unknown>
+  TResultMetadata = Record<string, unknown>,
 > {
   status: "healthy" | "unhealthy" | "degraded";
   latencyMs?: number;
@@ -27,7 +27,7 @@ export interface HealthCheckRunForAggregation<
  * Connected transport client with cleanup capability.
  */
 export interface ConnectedClient<
-  TClient extends TransportClient<unknown, unknown>
+  TClient extends TransportClient<unknown, unknown>,
 > {
   /** The connected transport client */
   client: TClient;
@@ -54,7 +54,7 @@ export interface HealthCheckStrategy<
     unknown
   >,
   TResult = Record<string, unknown>,
-  TAggregatedResult = Record<string, unknown>
+  TAggregatedResult = Record<string, unknown>,
 > {
   id: string;
   displayName: string;
@@ -80,13 +80,18 @@ export interface HealthCheckStrategy<
   createClient(config: TConfig): Promise<ConnectedClient<TClient>>;
 
   /**
-   * Aggregate results from multiple runs into a summary for bucket storage.
-   * Called during retention processing when raw data is aggregated.
+   * Incrementally merge new run data into an existing aggregate.
+   * Called after each health check run for real-time aggregation.
    * Core metrics (counts, latency) are auto-calculated by platform.
    * This function only handles strategy-specific result aggregation.
+   *
+   * @param existing - Existing aggregated result (undefined for first run in bucket)
+   * @param newRun - Data from the new run to merge
+   * @returns Updated aggregated result
    */
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<TResult>[]
+  mergeResult(
+    existing: TAggregatedResult | undefined,
+    newRun: HealthCheckRunForAggregation<TResult>,
   ): TAggregatedResult;
 }
 
@@ -111,10 +116,10 @@ export interface HealthCheckRegistry {
       TransportClient<unknown, unknown>,
       unknown,
       unknown
-    >
+    >,
   ): void;
   getStrategy(
-    id: string
+    id: string,
   ):
     | HealthCheckStrategy<
         unknown,

package/src/incremental-aggregation.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "bun:test";
+import {
+  mergeCounter,
+  mergeAverage,
+  mergeRate,
+  mergeMinMax,
+} from "./incremental-aggregation";
+
+describe("mergeCounter", () => {
+  it("creates new counter from undefined", () => {
+    const result = mergeCounter(undefined, true);
+    expect(result).toEqual({ count: 1 });
+  });
+
+  it("increments existing counter with true", () => {
+    const result = mergeCounter({ count: 5 }, true);
+    expect(result).toEqual({ count: 6 });
+  });
+
+  it("does not increment with false", () => {
+    const result = mergeCounter({ count: 5 }, false);
+    expect(result).toEqual({ count: 5 });
+  });
+
+  it("accepts numeric increment", () => {
+    const result = mergeCounter({ count: 10 }, 3);
+    expect(result).toEqual({ count: 13 });
+  });
+
+  it("handles zero increment", () => {
+    const result = mergeCounter({ count: 10 }, 0);
+    expect(result).toEqual({ count: 10 });
+  });
+});
+
+describe("mergeAverage", () => {
+  it("creates new average from undefined with value", () => {
+    const result = mergeAverage(undefined, 100);
+    expect(result).toEqual({ _sum: 100, _count: 1, avg: 100 });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeAverage(undefined, undefined);
+    expect(result).toEqual({ _sum: 0, _count: 0, avg: 0 });
+  });
+
+  it("correctly computes average across multiple values", () => {
+    let state = mergeAverage(undefined, 100);
+    state = mergeAverage(state, 200);
+    state = mergeAverage(state, 300);
+    expect(state).toEqual({ _sum: 600, _count: 3, avg: 200 });
+  });
+
+  it("skips undefined values without affecting count", () => {
+    let state = mergeAverage(undefined, 100);
+    state = mergeAverage(state, undefined);
+    state = mergeAverage(state, 200);
+    expect(state).toEqual({ _sum: 300, _count: 2, avg: 150 });
+  });
+
+  it("rounds average to 1 decimal place", () => {
+    let state = mergeAverage(undefined, 100);
+    state = mergeAverage(state, 101);
+    // (100 + 101) / 2 = 100.5, rounds to 1 decimal place
+    expect(state.avg).toBe(100.5);
+  });
+});
+
+describe("mergeRate", () => {
+  it("creates new rate from undefined with success", () => {
+    const result = mergeRate(undefined, true);
+    expect(result).toEqual({ _success: 1, _total: 1, rate: 100 });
+  });
+
+  it("creates new rate from undefined with failure", () => {
+    const result = mergeRate(undefined, false);
+    expect(result).toEqual({ _success: 0, _total: 1, rate: 0 });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeRate(undefined, undefined);
+    expect(result).toEqual({ _success: 0, _total: 0, rate: 0 });
+  });
+
+  it("correctly computes rate across multiple values", () => {
+    let state = mergeRate(undefined, true);
+    state = mergeRate(state, true);
+    state = mergeRate(state, false);
+    state = mergeRate(state, true);
+    // 3/4 = 75%
+    expect(state).toEqual({ _success: 3, _total: 4, rate: 75 });
+  });
+
+  it("skips undefined values without affecting totals", () => {
+    let state = mergeRate(undefined, true);
+    state = mergeRate(state, undefined);
+    state = mergeRate(state, false);
+    expect(state).toEqual({ _success: 1, _total: 2, rate: 50 });
+  });
+});
+
+describe("mergeMinMax", () => {
+  it("creates new min/max from undefined", () => {
+    const result = mergeMinMax(undefined, 50);
+    expect(result).toEqual({ min: 50, max: 50 });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeMinMax(undefined, undefined);
+    expect(result).toEqual({ min: 0, max: 0 });
+  });
+
+  it("updates min when new value is lower", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, 30);
+    expect(state).toEqual({ min: 30, max: 50 });
+  });
+
+  it("updates max when new value is higher", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, 80);
+    expect(state).toEqual({ min: 50, max: 80 });
+  });
+
+  it("updates both when appropriate", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, 20);
+    state = mergeMinMax(state, 100);
+    state = mergeMinMax(state, 60);
+    expect(state).toEqual({ min: 20, max: 100 });
+  });
+
+  it("skips undefined values", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, undefined);
+    state = mergeMinMax(state, 30);
+    expect(state).toEqual({ min: 30, max: 50 });
+  });
+
+  it("handles negative values", () => {
+    let state = mergeMinMax(undefined, -10);
+    state = mergeMinMax(state, -50);
+    state = mergeMinMax(state, -5);
+    expect(state).toEqual({ min: -50, max: -5 });
+  });
+});

package/src/incremental-aggregation.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+
+/**
+ * Incremental aggregation utilities for real-time metrics.
+ * These utilities enable O(1) memory aggregation without storing raw data.
+ *
+ * Each pattern provides:
+ * - A Zod schema for validation/serialization
+ * - A TypeScript interface (inferred from schema)
+ * - A merge function for incremental updates
+ */
+
+// ===== Counter Pattern =====
+
+/**
+ * Zod schema for accumulated counter state.
+ */
+export const counterStateSchema = z.object({
+  count: z.number(),
+});
+
+/**
+ * Accumulated counter state.
+ */
+export type CounterState = z.infer<typeof counterStateSchema>;
+
+/**
+ * Incrementally merge a counter.
+ * Use for tracking occurrences (errorCount, requestCount, etc.)
+ *
+ * @param existing - Previous counter state (undefined for first run)
+ * @param increment - Value to add (boolean true = 1, false = 0, or direct number)
+ */
+export function mergeCounter(
+  existing: CounterState | undefined,
+  increment: boolean | number,
+): CounterState {
+  const value =
+    typeof increment === "boolean" ? (increment ? 1 : 0) : increment;
+  return {
+    count: (existing?.count ?? 0) + value,
+  };
+}
+
+// ===== Average Pattern =====
+
+/**
+ * Zod schema for accumulated average state.
+ * Internal `_sum` and `_count` fields enable accurate averaging.
+ */
+export const averageStateSchema = z.object({
+  /** Internal: sum of all values */
+  _sum: z.number(),
+  /** Internal: count of values */
+  _count: z.number(),
+  /** Computed average (rounded) */
+  avg: z.number(),
+});
+
+/**
+ * Accumulated average state.
+ */
+export type AverageState = z.infer<typeof averageStateSchema>;
+
+/**
+ * Incrementally merge an average.
+ * Use for tracking averages (avgResponseTimeMs, avgExecutionTimeMs, etc.)
+ *
+ * @param existing - Previous average state (undefined for first run)
+ * @param value - New value to incorporate (undefined skipped)
+ */
+export function mergeAverage(
+  existing: AverageState | undefined,
+  value: number | undefined,
+): AverageState {
+  if (value === undefined) {
+    // No new value, return existing or initial state
+    return existing ?? { _sum: 0, _count: 0, avg: 0 };
+  }
+
+  const sum = (existing?._sum ?? 0) + value;
+  const count = (existing?._count ?? 0) + 1;
+
+  return {
+    _sum: sum,
+    _count: count,
+    // Round to 1 decimal place to preserve precision for float metrics (e.g., load averages)
+    avg: Math.round((sum / count) * 10) / 10,
+  };
+}
+
+// ===== Rate Pattern =====
+
+/**
+ * Zod schema for accumulated rate state (percentage).
+ * Internal `_success` and `_total` fields enable accurate rate calculation.
+ */
+export const rateStateSchema = z.object({
+  /** Internal: count of successes */
+  _success: z.number(),
+  /** Internal: total count */
+  _total: z.number(),
+  /** Computed rate as percentage (0-100, rounded) */
+  rate: z.number(),
+});
+
+/**
+ * Accumulated rate state (percentage).
+ */
+export type RateState = z.infer<typeof rateStateSchema>;
+
+/**
+ * Incrementally merge a rate (percentage).
+ * Use for tracking success rates, availability percentages, etc.
+ *
+ * @param existing - Previous rate state (undefined for first run)
+ * @param success - Whether this run was successful (undefined skipped)
+ */
+export function mergeRate(
+  existing: RateState | undefined,
+  success: boolean | undefined,
+): RateState {
+  if (success === undefined) {
+    // No new value, return existing or initial state
+    return existing ?? { _success: 0, _total: 0, rate: 0 };
+  }
+
+  const successCount = (existing?._success ?? 0) + (success ? 1 : 0);
+  const total = (existing?._total ?? 0) + 1;
+
+  return {
+    _success: successCount,
+    _total: total,
+    rate: Math.round((successCount / total) * 100),
+  };
+}
+
+// ===== MinMax Pattern =====
+
+/**
+ * Zod schema for accumulated min/max state.
+ */
+export const minMaxStateSchema = z.object({
+  min: z.number(),
+  max: z.number(),
+});
+
+/**
+ * Accumulated min/max state.
+ */
+export type MinMaxState = z.infer<typeof minMaxStateSchema>;
+
+/**
+ * Incrementally merge min/max values.
+ * Use for tracking min/max latency, memory, etc.
+ *
+ * @param existing - Previous min/max state (undefined for first run)
+ * @param value - New value to incorporate (undefined skipped)
+ */
+export function mergeMinMax(
+  existing: MinMaxState | undefined,
+  value: number | undefined,
+): MinMaxState {
+  if (value === undefined) {
+    // No new value, return existing or initial state
+    return existing ?? { min: 0, max: 0 };
+  }
+
+  if (existing === undefined) {
+    // First value
+    return { min: value, max: value };
+  }
+
+  return {
+    min: Math.min(existing.min, value),
+    max: Math.max(existing.max, value),
+  };
+}

package/src/index.ts

@@ -24,3 +24,4 @@ export * from "./chart-metadata";
 export * from "./transport-client";
 export * from "./collector-strategy";
 export * from "./collector-registry";
+export * from "./incremental-aggregation";