@checkstack/backend-api 0.6.0 → 0.8.0

package/src/incremental-aggregation.test.ts

@@ -4,58 +4,67 @@ import {
   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({ count: 1 });
+    expect(result).toEqual({ _type: "counter", count: 1 });
   });
 
   it("increments existing counter with true", () => {
     const result = mergeCounter({ count: 5 }, true);
-    expect(result).toEqual({ count: 6 });
+    expect(result).toEqual({ _type: "counter", count: 6 });
   });
 
   it("does not increment with false", () => {
     const result = mergeCounter({ count: 5 }, false);
-    expect(result).toEqual({ count: 5 });
+    expect(result).toEqual({ _type: "counter", count: 5 });
   });
 
   it("accepts numeric increment", () => {
     const result = mergeCounter({ count: 10 }, 3);
-    expect(result).toEqual({ count: 13 });
+    expect(result).toEqual({ _type: "counter", count: 13 });
   });
 
   it("handles zero increment", () => {
     const result = mergeCounter({ count: 10 }, 0);
-    expect(result).toEqual({ count: 10 });
+    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({ _sum: 100, _count: 1, avg: 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({ _sum: 0, _count: 0, avg: 0 });
+    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({ _sum: 600, _count: 3, avg: 200 });
+    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({ _sum: 300, _count: 2, avg: 150 });
+    expect(state).toEqual({ _type: "average", _sum: 300, _count: 2, avg: 150 });
   });
 
   it("rounds average to 1 decimal place", () => {
@@ -69,17 +78,22 @@ describe("mergeAverage", () => {
 describe("mergeRate", () => {
   it("creates new rate from undefined with success", () => {
     const result = mergeRate(undefined, true);
-    expect(result).toEqual({ _success: 1, _total: 1, rate: 100 });
+    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({ _success: 0, _total: 1, rate: 0 });
+    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({ _success: 0, _total: 0, rate: 0 });
+    expect(result).toEqual({ _type: "rate", _success: 0, _total: 0, rate: 0 });
   });
 
   it("correctly computes rate across multiple values", () => {
@@ -88,38 +102,38 @@ describe("mergeRate", () => {
     state = mergeRate(state, false);
     state = mergeRate(state, true);
     // 3/4 = 75%
-    expect(state).toEqual({ _success: 3, _total: 4, rate: 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({ _success: 1, _total: 2, rate: 50 });
+    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({ min: 50, max: 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({ min: 0, max: 0 });
+    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({ min: 30, max: 50 });
+    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({ min: 50, max: 80 });
+    expect(state).toEqual({ _type: "minmax", min: 50, max: 80 });
   });
 
   it("updates both when appropriate", () => {
@@ -127,20 +141,103 @@ describe("mergeMinMax", () => {
     state = mergeMinMax(state, 20);
     state = mergeMinMax(state, 100);
     state = mergeMinMax(state, 60);
-    expect(state).toEqual({ min: 20, max: 100 });
+    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({ min: 30, max: 50 });
+    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({ min: -50, max: -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

@@ -5,25 +5,37 @@ import { z } from "zod";
  * 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
+ * - 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 =====
+// =============================================================================
+// 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(),
 });
 
 /**
- * Accumulated counter state.
+ * 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.)
@@ -32,23 +44,28 @@ export type CounterState = z.infer<typeof counterStateSchema>;
  * @param increment - Value to add (boolean true = 1, false = 0, or direct number)
  */
 export function mergeCounter(
-  existing: CounterState | undefined,
+  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 =====
+// =============================================================================
+// 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 */
@@ -58,10 +75,15 @@ export const averageStateSchema = z.object({
 });
 
 /**
- * Accumulated average state.
+ * 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.)
@@ -70,18 +92,24 @@ export type AverageState = z.infer<typeof averageStateSchema>;
  * @param value - New value to incorporate (undefined skipped)
  */
 export function mergeAverage(
-  existing: AverageState | undefined,
+  existing: AverageStateInput | undefined,
   value: number | undefined,
 ): AverageState {
   if (value === undefined) {
-    // No new value, return existing or initial state
-    return existing ?? { _sum: 0, _count: 0, avg: 0 };
+    // 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)
@@ -89,13 +117,17 @@ export function mergeAverage(
   };
 }
 
-// ===== Rate Pattern =====
+// =============================================================================
+// 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 */
@@ -105,10 +137,15 @@ export const rateStateSchema = z.object({
 });
 
 /**
- * Accumulated rate state (percentage).
+ * 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.
@@ -117,39 +154,54 @@ export type RateState = z.infer<typeof rateStateSchema>;
  * @param success - Whether this run was successful (undefined skipped)
  */
 export function mergeRate(
-  existing: RateState | undefined,
+  existing: RateStateInput | undefined,
   success: boolean | undefined,
 ): RateState {
   if (success === undefined) {
-    // No new value, return existing or initial state
-    return existing ?? { _success: 0, _total: 0, rate: 0 };
+    // 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 =====
+// =============================================================================
+// 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(),
 });
 
 /**
- * Accumulated min/max state.
+ * 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.
@@ -158,21 +210,99 @@ export type MinMaxState = z.infer<typeof minMaxStateSchema>;
  * @param value - New value to incorporate (undefined skipped)
  */
 export function mergeMinMax(
-  existing: MinMaxState | undefined,
+  existing: MinMaxStateInput | undefined,
   value: number | undefined,
 ): MinMaxState {
   if (value === undefined) {
-    // No new value, return existing or initial state
-    return existing ?? { min: 0, max: 0 };
+    // 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 { min: value, max: 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

@@ -3,6 +3,7 @@ export * from "./extension-point";
 export * from "./core-services";
 export * from "./plugin-system";
 export * from "./health-check";
+export * from "./base-strategy-config";
 export * from "./auth-strategy";
 export * from "./zod-config";
 export * from "./encryption";
@@ -25,3 +26,4 @@ export * from "./transport-client";
 export * from "./collector-strategy";
 export * from "./collector-registry";
 export * from "./incremental-aggregation";
+export * from "./aggregated-result";