@checkstack/backend-api 0.5.2 → 0.7.0

package/src/incremental-aggregation.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from "bun:test";
+import {
+  mergeCounter,
+  mergeAverage,
+  mergeRate,
+  mergeMinMax,
+  mergeCounterStates,
+  mergeAverageStates,
+  mergeRateStates,
+  mergeMinMaxStates,
+} from "./incremental-aggregation";
+
+describe("mergeCounter", () => {
+  it("creates new counter from undefined", () => {
+    const result = mergeCounter(undefined, true);
+    expect(result).toEqual({ _type: "counter", count: 1 });
+  });
+
+  it("increments existing counter with true", () => {
+    const result = mergeCounter({ count: 5 }, true);
+    expect(result).toEqual({ _type: "counter", count: 6 });
+  });
+
+  it("does not increment with false", () => {
+    const result = mergeCounter({ count: 5 }, false);
+    expect(result).toEqual({ _type: "counter", count: 5 });
+  });
+
+  it("accepts numeric increment", () => {
+    const result = mergeCounter({ count: 10 }, 3);
+    expect(result).toEqual({ _type: "counter", count: 13 });
+  });
+
+  it("handles zero increment", () => {
+    const result = mergeCounter({ count: 10 }, 0);
+    expect(result).toEqual({ _type: "counter", count: 10 });
+  });
+});
+
+describe("mergeAverage", () => {
+  it("creates new average from undefined with value", () => {
+    const result = mergeAverage(undefined, 100);
+    expect(result).toEqual({
+      _type: "average",
+      _sum: 100,
+      _count: 1,
+      avg: 100,
+    });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeAverage(undefined, undefined);
+    expect(result).toEqual({ _type: "average", _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({ _type: "average", _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({ _type: "average", _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({
+      _type: "rate",
+      _success: 1,
+      _total: 1,
+      rate: 100,
+    });
+  });
+
+  it("creates new rate from undefined with failure", () => {
+    const result = mergeRate(undefined, false);
+    expect(result).toEqual({ _type: "rate", _success: 0, _total: 1, rate: 0 });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeRate(undefined, undefined);
+    expect(result).toEqual({ _type: "rate", _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({ _type: "rate", _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({ _type: "rate", _success: 1, _total: 2, rate: 50 });
+  });
+});
+
+describe("mergeMinMax", () => {
+  it("creates new min/max from undefined", () => {
+    const result = mergeMinMax(undefined, 50);
+    expect(result).toEqual({ _type: "minmax", min: 50, max: 50 });
+  });
+
+  it("returns initial state when undefined value passed to undefined", () => {
+    const result = mergeMinMax(undefined, undefined);
+    expect(result).toEqual({ _type: "minmax", min: 0, max: 0 });
+  });
+
+  it("updates min when new value is lower", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, 30);
+    expect(state).toEqual({ _type: "minmax", min: 30, max: 50 });
+  });
+
+  it("updates max when new value is higher", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, 80);
+    expect(state).toEqual({ _type: "minmax", 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({ _type: "minmax", min: 20, max: 100 });
+  });
+
+  it("skips undefined values", () => {
+    let state = mergeMinMax(undefined, 50);
+    state = mergeMinMax(state, undefined);
+    state = mergeMinMax(state, 30);
+    expect(state).toEqual({ _type: "minmax", min: 30, max: 50 });
+  });
+
+  it("handles negative values", () => {
+    let state = mergeMinMax(undefined, -10);
+    state = mergeMinMax(state, -50);
+    state = mergeMinMax(state, -5);
+    expect(state).toEqual({ _type: "minmax", min: -50, max: -5 });
+  });
+});
+
+// =============================================================================
+// State-Merge Utilities (for combining pre-aggregated states)
+// =============================================================================
+
+describe("mergeCounterStates", () => {
+  it("combines two counter states", () => {
+    const result = mergeCounterStates({ count: 5 }, { count: 3 });
+    expect(result).toEqual({ _type: "counter", count: 8 });
+  });
+
+  it("handles zero counts", () => {
+    const result = mergeCounterStates({ count: 0 }, { count: 10 });
+    expect(result).toEqual({ _type: "counter", count: 10 });
+  });
+});
+
+describe("mergeAverageStates", () => {
+  it("correctly merges two average states", () => {
+    const a = { _sum: 100, _count: 2, avg: 50 };
+    const b = { _sum: 200, _count: 2, avg: 100 };
+    const result = mergeAverageStates(a, b);
+    expect(result).toEqual({ _type: "average", _sum: 300, _count: 4, avg: 75 });
+  });
+
+  it("handles unequal counts", () => {
+    const a = { _sum: 100, _count: 1, avg: 100 };
+    const b = { _sum: 200, _count: 4, avg: 50 };
+    const result = mergeAverageStates(a, b);
+    // (100 + 200) / 5 = 60
+    expect(result).toEqual({ _type: "average", _sum: 300, _count: 5, avg: 60 });
+  });
+
+  it("handles zero count", () => {
+    const a = { _sum: 0, _count: 0, avg: 0 };
+    const b = { _sum: 100, _count: 2, avg: 50 };
+    const result = mergeAverageStates(a, b);
+    expect(result).toEqual({ _type: "average", _sum: 100, _count: 2, avg: 50 });
+  });
+});
+
+describe("mergeRateStates", () => {
+  it("correctly merges two rate states", () => {
+    const a = { _success: 3, _total: 4, rate: 75 };
+    const b = { _success: 7, _total: 10, rate: 70 };
+    const result = mergeRateStates(a, b);
+    // 10/14 ≈ 71.4% -> rounds to 71
+    expect(result).toEqual({
+      _type: "rate",
+      _success: 10,
+      _total: 14,
+      rate: 71,
+    });
+  });
+
+  it("handles zero total", () => {
+    const a = { _success: 0, _total: 0, rate: 0 };
+    const b = { _success: 5, _total: 10, rate: 50 };
+    const result = mergeRateStates(a, b);
+    expect(result).toEqual({
+      _type: "rate",
+      _success: 5,
+      _total: 10,
+      rate: 50,
+    });
+  });
+});
+
+describe("mergeMinMaxStates", () => {
+  it("takes min of mins and max of maxes", () => {
+    const a = { min: 10, max: 50 };
+    const b = { min: 5, max: 100 };
+    const result = mergeMinMaxStates(a, b);
+    expect(result).toEqual({ _type: "minmax", min: 5, max: 100 });
+  });
+
+  it("handles overlapping ranges", () => {
+    const a = { min: 20, max: 60 };
+    const b = { min: 40, max: 80 };
+    const result = mergeMinMaxStates(a, b);
+    expect(result).toEqual({ _type: "minmax", min: 20, max: 80 });
+  });
+});

package/src/incremental-aggregation.ts

@@ -0,0 +1,308 @@
+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 (with required _type)
+ * - TypeScript types: State (with _type) and StateInput (without _type)
+ * - A merge function that always outputs the _type discriminator
+ *
+ * Strategy/collector implementations provide data WITHOUT _type.
+ * The merge functions add _type automatically.
+ */
+
+// =============================================================================
+// COUNTER PATTERN
+// =============================================================================
+
+/**
+ * Zod schema for accumulated counter state.
+ * _type is required for reliable type detection.
+ */
+export const counterStateSchema = z.object({
+  _type: z.literal("counter"),
+  count: z.number(),
+});
+
+/**
+ * Counter state with required _type discriminator (derived from schema).
+ */
+export type CounterState = z.infer<typeof counterStateSchema>;
+
+/**
+ * Counter state input type - without _type (for strategy/collector implementations).
+ */
+export type CounterStateInput = Omit<CounterState, "_type">;
+
+/**
+ * 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: CounterStateInput | undefined,
+  increment: boolean | number,
+): CounterState {
+  const value =
+    typeof increment === "boolean" ? (increment ? 1 : 0) : increment;
+  return {
+    _type: "counter",
+    count: (existing?.count ?? 0) + value,
+  };
+}
+
+// =============================================================================
+// AVERAGE PATTERN
+// =============================================================================
+
+/**
+ * Zod schema for accumulated average state.
+ * Internal `_sum` and `_count` fields enable accurate averaging.
+ * _type is required for reliable type detection.
+ */
+export const averageStateSchema = z.object({
+  _type: z.literal("average"),
+  /** Internal: sum of all values */
+  _sum: z.number(),
+  /** Internal: count of values */
+  _count: z.number(),
+  /** Computed average (rounded) */
+  avg: z.number(),
+});
+
+/**
+ * Average state with required _type discriminator (derived from schema).
+ */
+export type AverageState = z.infer<typeof averageStateSchema>;
+
+/**
+ * Average state input type - without _type (for strategy/collector implementations).
+ */
+export type AverageStateInput = Omit<AverageState, "_type">;
+
+/**
+ * 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: AverageStateInput | undefined,
+  value: number | undefined,
+): AverageState {
+  if (value === undefined) {
+    // No new value, return existing with _type or initial state
+    return {
+      _type: "average",
+      _sum: existing?._sum ?? 0,
+      _count: existing?._count ?? 0,
+      avg: existing?.avg ?? 0,
+    };
+  }
+
+  const sum = (existing?._sum ?? 0) + value;
+  const count = (existing?._count ?? 0) + 1;
+
+  return {
+    _type: "average",
+    _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.
+ * _type is required for reliable type detection.
+ */
+export const rateStateSchema = z.object({
+  _type: z.literal("rate"),
+  /** Internal: count of successes */
+  _success: z.number(),
+  /** Internal: total count */
+  _total: z.number(),
+  /** Computed rate as percentage (0-100, rounded) */
+  rate: z.number(),
+});
+
+/**
+ * Rate state with required _type discriminator (derived from schema).
+ */
+export type RateState = z.infer<typeof rateStateSchema>;
+
+/**
+ * Rate state input type - without _type (for strategy/collector implementations).
+ */
+export type RateStateInput = Omit<RateState, "_type">;
+
+/**
+ * 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: RateStateInput | undefined,
+  success: boolean | undefined,
+): RateState {
+  if (success === undefined) {
+    // No new value, return existing with _type or initial state
+    return {
+      _type: "rate",
+      _success: existing?._success ?? 0,
+      _total: existing?._total ?? 0,
+      rate: existing?.rate ?? 0,
+    };
+  }
+
+  const successCount = (existing?._success ?? 0) + (success ? 1 : 0);
+  const total = (existing?._total ?? 0) + 1;
+
+  return {
+    _type: "rate",
+    _success: successCount,
+    _total: total,
+    rate: Math.round((successCount / total) * 100),
+  };
+}
+
+// =============================================================================
+// MINMAX PATTERN
+// =============================================================================
+
+/**
+ * Zod schema for accumulated min/max state.
+ * _type is required for reliable type detection.
+ */
+export const minMaxStateSchema = z.object({
+  _type: z.literal("minmax"),
+  min: z.number(),
+  max: z.number(),
+});
+
+/**
+ * MinMax state with required _type discriminator (derived from schema).
+ */
+export type MinMaxState = z.infer<typeof minMaxStateSchema>;
+
+/**
+ * MinMax state input type - without _type (for strategy/collector implementations).
+ */
+export type MinMaxStateInput = Omit<MinMaxState, "_type">;
+
+/**
+ * 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: MinMaxStateInput | undefined,
+  value: number | undefined,
+): MinMaxState {
+  if (value === undefined) {
+    // No new value, return existing with _type or initial state
+    return {
+      _type: "minmax",
+      min: existing?.min ?? 0,
+      max: existing?.max ?? 0,
+    };
+  }
+
+  if (existing === undefined) {
+    // First value
+    return { _type: "minmax", min: value, max: value };
+  }
+
+  return {
+    _type: "minmax",
+    min: Math.min(existing.min, value),
+    max: Math.max(existing.max, value),
+  };
+}
+
+// =============================================================================
+// STATE-MERGE UTILITIES - For merging two pre-aggregated states
+// =============================================================================
+
+/**
+ * Merge two CounterStates.
+ * Used when combining pre-aggregated buckets (e.g., in combineBuckets).
+ * Always includes _type discriminator for reliable type detection.
+ */
+export function mergeCounterStates(
+  a: CounterStateInput,
+  b: CounterStateInput,
+): CounterState {
+  return {
+    _type: "counter",
+    count: a.count + b.count,
+  };
+}
+
+/**
+ * Merge two AverageStates.
+ * Used when combining pre-aggregated buckets.
+ * Always includes _type discriminator for reliable type detection.
+ */
+export function mergeAverageStates(
+  a: AverageStateInput,
+  b: AverageStateInput,
+): AverageState {
+  const sum = a._sum + b._sum;
+  const count = a._count + b._count;
+  return {
+    _type: "average",
+    _sum: sum,
+    _count: count,
+    avg: count > 0 ? Math.round((sum / count) * 10) / 10 : 0,
+  };
+}
+
+/**
+ * Merge two RateStates.
+ * Used when combining pre-aggregated buckets.
+ * Always includes _type discriminator for reliable type detection.
+ */
+export function mergeRateStates(
+  a: RateStateInput,
+  b: RateStateInput,
+): RateState {
+  const success = a._success + b._success;
+  const total = a._total + b._total;
+  return {
+    _type: "rate",
+    _success: success,
+    _total: total,
+    rate: total > 0 ? Math.round((success / total) * 100) : 0,
+  };
+}
+
+/**
+ * Merge two MinMaxStates.
+ * Used when combining pre-aggregated buckets.
+ * Always includes _type discriminator for reliable type detection.
+ */
+export function mergeMinMaxStates(
+  a: MinMaxStateInput,
+  b: MinMaxStateInput,
+): MinMaxState {
+  return {
+    _type: "minmax",
+    min: Math.min(a.min, b.min),
+    max: Math.max(a.max, b.max),
+  };
+}

package/src/index.ts

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