metrickit 0.1.2

package/dist/index.js

@@ -0,0 +1,1322 @@
+// src/cache-redis.ts
+function redisCacheAdapter(client) {
+  return {
+    async mget(keys) {
+      if (keys.length === 0)
+        return [];
+      return client.mget(...keys);
+    },
+    async mset(entries) {
+      if (entries.length === 0)
+        return;
+      const pipeline = client.pipeline();
+      for (const { key, value, ttl } of entries) {
+        if (ttl > 0) {
+          pipeline.setex(key, ttl, value);
+        }
+      }
+      await pipeline.exec();
+    }
+  };
+}
+
+// src/cache.ts
+var noopCacheAdapter = {
+  async mget(keys) {
+    return keys.map(() => null);
+  },
+  async mset() {}
+};
+function parseCache(cached, schema) {
+  if (!cached)
+    return null;
+  try {
+    const parsed = JSON.parse(cached);
+    const result = schema.safeParse(parsed);
+    if (result.success) {
+      return result.data;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/schemas/time.ts
+import { z } from "zod";
+var TimeGranularitySchema = z.enum([
+  "hour",
+  "day",
+  "week",
+  "month",
+  "quarter",
+  "year"
+]);
+var TimeRangeSchema = z.object({
+  from: z.date().optional(),
+  to: z.date().optional()
+});
+var RequiredTimeRangeSchema = z.object({
+  from: z.date(),
+  to: z.date()
+});
+var CompareSchema = z.object({
+  compareToPrevious: z.boolean().optional().default(false)
+});
+// src/schemas/output.ts
+import { z as z2 } from "zod";
+var OutputKindSchema = z2.enum([
+  "kpi",
+  "timeseries",
+  "distribution",
+  "table",
+  "leaderboard",
+  "pivot"
+]);
+var MetricUnitSchema = z2.enum([
+  "DKK",
+  "EUR",
+  "USD",
+  "GBP",
+  "SEK",
+  "NOK",
+  "PERCENTAGE"
+]);
+var KpiOutputSchema = z2.object({
+  kind: z2.literal("kpi"),
+  value: z2.number(),
+  label: z2.string().optional(),
+  unit: MetricUnitSchema.optional(),
+  prefix: z2.string().optional(),
+  suffix: z2.string().optional(),
+  trend: z2.enum(["up", "down", "flat"]).optional()
+});
+function defineKpiOutput(output) {
+  return {
+    kind: "kpi",
+    ...output
+  };
+}
+var TimeSeriesPointSchema = z2.object({
+  ts: z2.date(),
+  value: z2.number(),
+  label: z2.string().optional()
+});
+var TimeSeriesSeriesSchema = z2.object({
+  key: z2.string(),
+  label: z2.string().optional(),
+  points: z2.array(TimeSeriesPointSchema),
+  chartType: z2.enum(["line", "bar"]).optional(),
+  axis: z2.enum(["left", "right"]).optional(),
+  meta: z2.record(z2.string(), z2.unknown()).optional()
+});
+var TimeSeriesOutputSchema = z2.object({
+  kind: z2.literal("timeseries"),
+  granularity: TimeGranularitySchema,
+  series: z2.array(TimeSeriesSeriesSchema)
+});
+function defineTimeSeriesOutput(output) {
+  if (Array.isArray(output.series)) {
+    return {
+      kind: "timeseries",
+      ...output,
+      series: [...output.series]
+    };
+  }
+  return {
+    kind: "timeseries",
+    ...output,
+    series: Object.entries(output.series).map(([key, series]) => ({
+      key,
+      ...series
+    }))
+  };
+}
+var DistributionSegmentSchema = z2.object({
+  key: z2.string(),
+  label: z2.string(),
+  value: z2.number(),
+  percent: z2.number().optional()
+});
+var DistributionChartTypeSchema = z2.enum([
+  "bar",
+  "donut",
+  "pie",
+  "funnel"
+]);
+var DistributionOutputSchema = z2.object({
+  kind: z2.literal("distribution"),
+  total: z2.number(),
+  segments: z2.array(DistributionSegmentSchema),
+  chartType: DistributionChartTypeSchema.optional()
+});
+function defineDistributionOutput(output) {
+  return {
+    kind: "distribution",
+    ...output,
+    segments: [...output.segments]
+  };
+}
+var TableColumnSchema = z2.object({
+  key: z2.string(),
+  label: z2.string(),
+  type: z2.enum(["string", "number", "date", "boolean"]).optional(),
+  nullable: z2.boolean().optional()
+});
+var TableOutputSchema = z2.object({
+  kind: z2.literal("table"),
+  columns: z2.array(TableColumnSchema),
+  rows: z2.array(z2.record(z2.string(), z2.unknown())),
+  total: z2.number().optional()
+});
+function defineTableOutput(output) {
+  return {
+    kind: "table",
+    ...output,
+    columns: [...output.columns],
+    rows: [...output.rows]
+  };
+}
+var PivotDimensionSchema = z2.object({
+  key: z2.string(),
+  label: z2.string()
+});
+var PivotTotalsSchema = z2.object({
+  rowTotals: z2.array(z2.number()).optional(),
+  columnTotals: z2.array(z2.number()).optional(),
+  grandTotal: z2.number().optional()
+});
+function addGrandTotalMismatchIssue(ctx, totalsName, totals, grandTotal) {
+  const totalsSum = totals?.reduce((total, value) => total + value, 0);
+  if (totalsSum === undefined)
+    return;
+  if (Math.abs(totalsSum - grandTotal) <= Number.EPSILON)
+    return;
+  ctx.addIssue({
+    code: z2.ZodIssueCode.custom,
+    path: ["totals", "grandTotal"],
+    message: `grandTotal must equal the sum of ${totalsName}`
+  });
+}
+function clonePivotTotals(totals) {
+  if (!totals)
+    return;
+  return {
+    rowTotals: totals.rowTotals ? [...totals.rowTotals] : undefined,
+    columnTotals: totals.columnTotals ? [...totals.columnTotals] : undefined,
+    grandTotal: totals.grandTotal
+  };
+}
+function clonePivotCellTooltips(cellTooltips) {
+  if (!cellTooltips)
+    return;
+  return cellTooltips.map((row) => [...row]);
+}
+var PivotOutputSchema = z2.object({
+  kind: z2.literal("pivot"),
+  rowDimension: PivotDimensionSchema,
+  columnDimension: PivotDimensionSchema,
+  rows: z2.array(z2.string()),
+  columns: z2.array(z2.string()),
+  values: z2.array(z2.array(z2.number())),
+  cellTooltips: z2.array(z2.array(z2.string())).optional(),
+  totals: PivotTotalsSchema.optional()
+}).superRefine((pivot, ctx) => {
+  const rowCount = pivot.rows.length;
+  const columnCount = pivot.columns.length;
+  if (pivot.values.length !== rowCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["values"],
+      message: `Pivot values must have ${rowCount} rows`
+    });
+  }
+  for (const [rowIndex, row] of pivot.values.entries()) {
+    if (row.length !== columnCount) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        path: ["values", rowIndex],
+        message: `Pivot row ${rowIndex} must have ${columnCount} columns`
+      });
+    }
+  }
+  if (pivot.cellTooltips !== undefined) {
+    if (pivot.cellTooltips.length !== rowCount) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        path: ["cellTooltips"],
+        message: `cellTooltips must have ${rowCount} rows`
+      });
+    }
+    for (const [rowIndex, row] of pivot.cellTooltips.entries()) {
+      if (row.length !== columnCount) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: ["cellTooltips", rowIndex],
+          message: `cellTooltips row ${rowIndex} must have ${columnCount} columns`
+        });
+      }
+    }
+  }
+  if (pivot.totals?.rowTotals && pivot.totals.rowTotals.length !== rowCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["totals", "rowTotals"],
+      message: `rowTotals must have ${rowCount} entries`
+    });
+  }
+  if (pivot.totals?.columnTotals && pivot.totals.columnTotals.length !== columnCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["totals", "columnTotals"],
+      message: `columnTotals must have ${columnCount} entries`
+    });
+  }
+  if (pivot.totals?.grandTotal !== undefined) {
+    addGrandTotalMismatchIssue(ctx, "rowTotals", pivot.totals.rowTotals, pivot.totals.grandTotal);
+    addGrandTotalMismatchIssue(ctx, "columnTotals", pivot.totals.columnTotals, pivot.totals.grandTotal);
+  }
+});
+function definePivotOutput(output) {
+  return {
+    kind: "pivot",
+    ...output,
+    rows: [...output.rows],
+    columns: [...output.columns],
+    values: output.values.map((row) => [...row]),
+    cellTooltips: clonePivotCellTooltips(output.cellTooltips),
+    totals: clonePivotTotals(output.totals)
+  };
+}
+var LeaderboardItemSchema = z2.object({
+  rank: z2.number(),
+  id: z2.string(),
+  label: z2.string(),
+  value: z2.number(),
+  meta: z2.record(z2.string(), z2.unknown()).optional()
+});
+var LeaderboardOutputSchema = z2.object({
+  kind: z2.literal("leaderboard"),
+  items: z2.array(LeaderboardItemSchema),
+  total: z2.number().optional()
+});
+function defineLeaderboardOutput(output) {
+  return {
+    kind: "leaderboard",
+    ...output,
+    items: [...output.items]
+  };
+}
+function defineMetricOutput(kind, output) {
+  const handlers = {
+    kpi: () => defineKpiOutput(output),
+    timeseries: () => defineTimeSeriesOutput(output),
+    distribution: () => defineDistributionOutput(output),
+    table: () => defineTableOutput(output),
+    leaderboard: () => defineLeaderboardOutput(output),
+    pivot: () => definePivotOutput(output)
+  };
+  return handlers[kind]();
+}
+function validateOutput(kind, output) {
+  return OutputSchemaMap[kind].parse(output);
+}
+var MetricOutputSchema = z2.discriminatedUnion("kind", [
+  KpiOutputSchema,
+  TimeSeriesOutputSchema,
+  DistributionOutputSchema,
+  TableOutputSchema,
+  LeaderboardOutputSchema,
+  PivotOutputSchema
+]);
+var OutputSchemaMap = {
+  kpi: KpiOutputSchema,
+  timeseries: TimeSeriesOutputSchema,
+  distribution: DistributionOutputSchema,
+  table: TableOutputSchema,
+  leaderboard: LeaderboardOutputSchema,
+  pivot: PivotOutputSchema
+};
+var MetricExecutionCacheStatusSchema = z2.enum([
+  "hit",
+  "partialHit",
+  "miss",
+  "bypassed"
+]);
+var MetricExecutionSchema = z2.object({
+  cacheStatus: MetricExecutionCacheStatusSchema,
+  durationMs: z2.number().nonnegative(),
+  granularity: TimeGranularitySchema.optional()
+});
+var MetricResultSchema = z2.object({
+  current: MetricOutputSchema,
+  previous: MetricOutputSchema.optional(),
+  supportsTimeRange: z2.boolean(),
+  execution: MetricExecutionSchema.optional()
+});
+// src/schemas/inputs.ts
+import { z as z3 } from "zod";
+var BaseFiltersSchema = z3.object({
+  organizationIds: z3.array(z3.string()).optional()
+}).merge(TimeRangeSchema);
+var TimeSeriesFiltersSchema = z3.object({
+  organizationIds: z3.array(z3.string()).optional()
+}).merge(RequiredTimeRangeSchema);
+function extendBaseFilters(shape) {
+  const optionalShape = Object.fromEntries(Object.entries(shape).map(([key, schema]) => [
+    key,
+    schema.optional()
+  ]));
+  return BaseFiltersSchema.extend(optionalShape);
+}
+function extendTimeSeriesFilters(shape) {
+  const optionalShape = Object.fromEntries(Object.entries(shape).map(([key, schema]) => [
+    key,
+    schema.optional()
+  ]));
+  return TimeSeriesFiltersSchema.extend(optionalShape);
+}
+// src/schemas/metric-type.ts
+import { z as z4 } from "zod";
+var MetricTypeSchema = z4.enum(["TOTAL", "AVG", "PER_BUCKET"]);
+// src/define-metric.ts
+function defineMetricWithSchema(kind, outputSchema, def) {
+  return {
+    kind,
+    outputSchema,
+    ...def
+  };
+}
+function defineKpiMetric(def) {
+  return defineMetricWithSchema("kpi", KpiOutputSchema, def);
+}
+function defineTimeSeriesMetric(def) {
+  return defineMetricWithSchema("timeseries", TimeSeriesOutputSchema, def);
+}
+function defineDistributionMetric(def) {
+  return defineMetricWithSchema("distribution", DistributionOutputSchema, def);
+}
+function defineTableMetric(def) {
+  return defineMetricWithSchema("table", TableOutputSchema, def);
+}
+function defineLeaderboardMetric(def) {
+  return defineMetricWithSchema("leaderboard", LeaderboardOutputSchema, def);
+}
+function definePivotMetric(def) {
+  return defineMetricWithSchema("pivot", PivotOutputSchema, def);
+}
+function getOutputSchema(metric) {
+  return metric.outputSchema;
+}
+function validateMetricOutput(metric, output2) {
+  return getOutputSchema(metric).parse(output2);
+}
+
+// src/registry.ts
+import { z as z5 } from "zod";
+function createRegistry(metrics, options) {
+  const metricKeys = metrics.map((m) => m.key);
+  const MetricKeySchema = z5.enum(metricKeys);
+  const MetricRequestSchema = z5.object({
+    key: MetricKeySchema,
+    requestKey: z5.string().optional(),
+    filters: z5.record(z5.string(), z5.unknown()).optional()
+  });
+  const MetricsRequestSchema = z5.object({
+    metrics: z5.array(MetricRequestSchema).min(1, "At least one metric required"),
+    granularity: TimeGranularitySchema.optional(),
+    from: z5.date().optional(),
+    to: z5.date().optional(),
+    compareToPrevious: z5.boolean().optional().default(false),
+    disableCache: z5.boolean().optional().default(false)
+  });
+  const metricsByKey = Object.fromEntries(metrics.map((metric) => [metric.key, metric]));
+  const baseFilterSchema = options?.baseFilterSchema ?? BaseFiltersSchema;
+  const kindSchemas = options?.kindSchemas ?? OutputSchemaMap;
+  function getMetricByKey(key) {
+    return metricsByKey[key];
+  }
+  function parseMetricRequestInput(metricRequest, options2) {
+    const metric = getMetricByKey(metricRequest.key);
+    if (!metric) {
+      throw new Error(`Unknown metric: ${metricRequest.key}`);
+    }
+    const baseFilters = baseFilterSchema.parse({
+      from: options2?.from,
+      to: options2?.to,
+      ...metricRequest.filters
+    });
+    return {
+      metric,
+      requestKey: getMetricResultKey(metricRequest),
+      filters: metric.filterSchema.parse(baseFilters)
+    };
+  }
+  return {
+    metrics,
+    baseFilterSchema,
+    kindSchemas,
+    metricKeys,
+    MetricKeySchema,
+    MetricRequestSchema,
+    MetricsRequestSchema,
+    metricsByKey,
+    getMetricByKey,
+    parseMetricRequestInput,
+    getOutputSchema
+  };
+}
+function getMetricResultKey(metricRequest) {
+  return metricRequest.requestKey ?? metricRequest.key;
+}
+function getMetric(result, key) {
+  return result.metrics[key];
+}
+
+// src/engine.ts
+function createMetricsEngine(config) {
+  const cache = config?.cache ?? noopCacheAdapter;
+  const baseFilterSchema = config?.baseFilters ?? BaseFiltersSchema;
+  const kindSchemas = {
+    ...OutputSchemaMap,
+    ...config?.customKinds ?? {}
+  };
+  function defineMetric(kind, def) {
+    return defineMetricWithSchema(kind, kindSchemas[kind], def);
+  }
+  function defineKpiMetric2(def) {
+    return defineKpiMetric(def);
+  }
+  function defineTimeSeriesMetric2(def) {
+    return defineTimeSeriesMetric(def);
+  }
+  function defineDistributionMetric2(def) {
+    return defineDistributionMetric(def);
+  }
+  function defineTableMetric2(def) {
+    return defineTableMetric(def);
+  }
+  function defineLeaderboardMetric2(def) {
+    return defineLeaderboardMetric(def);
+  }
+  function definePivotMetric2(def) {
+    return definePivotMetric(def);
+  }
+  function createRegistry2(metrics) {
+    return createRegistry(metrics, {
+      baseFilterSchema,
+      kindSchemas
+    });
+  }
+  return {
+    cache,
+    baseFilterSchema,
+    kindSchemas,
+    defineMetric,
+    defineKpiMetric: defineKpiMetric2,
+    defineTimeSeriesMetric: defineTimeSeriesMetric2,
+    defineDistributionMetric: defineDistributionMetric2,
+    defineTableMetric: defineTableMetric2,
+    defineLeaderboardMetric: defineLeaderboardMetric2,
+    definePivotMetric: definePivotMetric2,
+    createRegistry: createRegistry2
+  };
+}
+// src/cache-utils.ts
+function stableHash(obj) {
+  const stable = JSON.stringify(obj, Object.keys(obj).sort());
+  let h = 2166136261;
+  for (let i = 0;i < stable.length; i++) {
+    h ^= stable.charCodeAt(i);
+    h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
+  }
+  return (h >>> 0).toString(16);
+}
+function normalizeForCache(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined)
+      continue;
+    if (value instanceof Date) {
+      result[key] = value.toISOString();
+    } else if (Array.isArray(value)) {
+      result[key] = value.map((v) => v instanceof Date ? v.toISOString() : v);
+    } else if (typeof value === "object" && value !== null) {
+      const nested = normalizeForCache(value);
+      for (const [nk, nv] of Object.entries(nested)) {
+        result[`${key}.${nk}`] = nv;
+      }
+    } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function getCacheKey(metricKey, filters, period = "current", granularity) {
+  const normalized = normalizeForCache({
+    ...filters,
+    granularity
+  });
+  const hash = stableHash(normalized);
+  return `metrics:${metricKey}:${period}:${hash}`;
+}
+
+// src/time.ts
+function getPreviousPeriod(range) {
+  if (!range.from || !range.to)
+    return null;
+  const durationMs = range.to.getTime() - range.from.getTime();
+  return {
+    from: new Date(range.from.getTime() - durationMs),
+    to: new Date(range.from.getTime())
+  };
+}
+function getBucketStart(date, granularity) {
+  const d = new Date(date);
+  switch (granularity) {
+    case "hour":
+      d.setUTCMinutes(0, 0, 0);
+      break;
+    case "day":
+      d.setUTCHours(0, 0, 0, 0);
+      break;
+    case "week": {
+      const day = d.getUTCDay();
+      const diff = d.getUTCDate() - day + (day === 0 ? -6 : 1);
+      d.setUTCDate(diff);
+      d.setUTCHours(0, 0, 0, 0);
+      break;
+    }
+    case "month":
+      d.setUTCDate(1);
+      d.setUTCHours(0, 0, 0, 0);
+      break;
+    case "quarter": {
+      const month = d.getUTCMonth();
+      const quarterStart = month - month % 3;
+      d.setUTCMonth(quarterStart, 1);
+      d.setUTCHours(0, 0, 0, 0);
+      break;
+    }
+    case "year":
+      d.setUTCMonth(0, 1);
+      d.setUTCHours(0, 0, 0, 0);
+      break;
+  }
+  return d;
+}
+function normalizeUserDate(date) {
+  const d = new Date(date);
+  const hours = d.getUTCHours();
+  if (hours >= 20) {
+    d.setUTCDate(d.getUTCDate() + 1);
+  }
+  d.setUTCHours(0, 0, 0, 0);
+  return d;
+}
+function generateBuckets(from, to, granularity) {
+  const buckets = [];
+  const normalizedFrom = granularity === "hour" ? from : normalizeUserDate(from);
+  const normalizedTo = granularity === "hour" ? to : normalizeUserDate(to);
+  let current = getBucketStart(normalizedFrom, granularity);
+  while (current <= normalizedTo) {
+    buckets.push(new Date(current));
+    current = getNextBucket(current, granularity);
+  }
+  return buckets;
+}
+function getNextBucket(date, granularity) {
+  const d = new Date(date);
+  switch (granularity) {
+    case "hour":
+      d.setUTCHours(d.getUTCHours() + 1);
+      break;
+    case "day":
+      d.setUTCDate(d.getUTCDate() + 1);
+      break;
+    case "week":
+      d.setUTCDate(d.getUTCDate() + 7);
+      break;
+    case "month":
+      d.setUTCMonth(d.getUTCMonth() + 1);
+      break;
+    case "quarter":
+      d.setUTCMonth(d.getUTCMonth() + 3);
+      break;
+    case "year":
+      d.setUTCFullYear(d.getUTCFullYear() + 1);
+      break;
+  }
+  return d;
+}
+function inferGranularity(range) {
+  if (!range.from || !range.to)
+    return "day";
+  const diffMs = range.to.getTime() - range.from.getTime();
+  const diffDays = diffMs / (1000 * 60 * 60 * 24);
+  if (diffDays <= 2)
+    return "hour";
+  if (diffDays <= 31)
+    return "day";
+  if (diffDays <= 90)
+    return "week";
+  if (diffDays <= 365)
+    return "month";
+  if (diffDays <= 730)
+    return "quarter";
+  return "year";
+}
+
+// src/run-metrics.ts
+function shiftTimeSeriesTimestamps(output2, offsetMs) {
+  if (!output2 || typeof output2 !== "object" || !("kind" in output2) || output2.kind !== "timeseries") {
+    return output2;
+  }
+  const timeseriesOutput = output2;
+  return {
+    ...timeseriesOutput,
+    series: timeseriesOutput.series.map((s) => ({
+      ...s,
+      points: s.points.map((p) => ({
+        ...p,
+        ts: new Date(p.ts.getTime() + offsetMs)
+      }))
+    }))
+  };
+}
+async function runSingleMetric(ctx) {
+  const { metric, filters, granularity, compareToPrevious, resolverCtx } = ctx;
+  const current = await metric.resolve({
+    filters: metric.filterSchema.parse(filters),
+    ctx: { ...resolverCtx, granularity }
+  });
+  let previous;
+  if (compareToPrevious && metric.supportsTimeRange && filters.from && filters.to) {
+    const prevRange = getPreviousPeriod({ from: filters.from, to: filters.to });
+    if (prevRange) {
+      const prevFilters = {
+        ...filters,
+        from: prevRange.from,
+        to: prevRange.to
+      };
+      const prevResult = await metric.resolve({
+        filters: metric.filterSchema.parse(prevFilters),
+        ctx: { ...resolverCtx, granularity }
+      });
+      const periodOffset = filters.from.getTime() - prevRange.from.getTime();
+      previous = shiftTimeSeriesTimestamps(prevResult, periodOffset);
+    }
+  }
+  return { current, previous, supportsTimeRange: metric.supportsTimeRange };
+}
+async function prepareMetrics(options) {
+  const {
+    registry,
+    createContext,
+    cache = noopCacheAdapter,
+    hasAccess
+  } = options;
+  const request = registry.MetricsRequestSchema.parse(options.request);
+  const disableCache = request.disableCache ?? false;
+  const userCtx = await createContext();
+  const granularity = request.granularity ?? inferGranularity({ from: request.from, to: request.to });
+  const resolverCtx = { ...userCtx, granularity };
+  const cacheRequests = [];
+  const validMetrics = [];
+  const errors = {};
+  for (const metricReq of request.metrics) {
+    const metric = registry.getMetricByKey(metricReq.key);
+    const requestKey = metricReq.requestKey ?? metricReq.key;
+    if (!metric) {
+      errors[requestKey] = `Unknown metric: ${metricReq.key}`;
+      continue;
+    }
+    if (hasAccess && !hasAccess(metric)) {
+      errors[requestKey] = "Access denied";
+      continue;
+    }
+    let parsedMetricFilters;
+    try {
+      const parsedMetricRequest = registry.parseMetricRequestInput(metricReq, {
+        from: request.from,
+        to: request.to
+      });
+      parsedMetricFilters = parsedMetricRequest.filters;
+      validMetrics.push({
+        metric: parsedMetricRequest.metric,
+        filters: parsedMetricFilters,
+        requestKey: parsedMetricRequest.requestKey
+      });
+    } catch (err) {
+      errors[requestKey] = err instanceof Error ? err.message : "Invalid metric filters";
+      continue;
+    }
+    const filters = parsedMetricFilters;
+    const ttl = metric.cacheTtl ?? 600;
+    if (!disableCache && ttl > 0) {
+      cacheRequests.push({
+        key: getCacheKey(metric.key, filters, "current", granularity),
+        metric,
+        filters
+      });
+      if (request.compareToPrevious && metric.supportsTimeRange) {
+        const prevRange = getPreviousPeriod({
+          from: filters.from,
+          to: filters.to
+        });
+        if (prevRange) {
+          cacheRequests.push({
+            key: getCacheKey(metric.key, { ...filters, ...prevRange }, "previous", granularity),
+            metric,
+            filters: { ...filters, ...prevRange }
+          });
+        }
+      }
+    }
+  }
+  const cacheKeys = cacheRequests.map((r) => r.key);
+  const cachedValues = cacheKeys.length > 0 ? await cache.mget(cacheKeys) : [];
+  const cacheMap = new Map;
+  for (let i = 0;i < cacheRequests.length; i++) {
+    const req = cacheRequests[i];
+    const cached = cachedValues[i];
+    if (req && cached) {
+      const parsed = parseCache(cached, getOutputSchema(req.metric));
+      if (parsed) {
+        cacheMap.set(req.key, parsed);
+      }
+    }
+  }
+  return {
+    validMetrics,
+    errors,
+    cacheMap,
+    granularity,
+    resolverCtx,
+    compareToPrevious: request.compareToPrevious ?? false,
+    disableCache,
+    cache
+  };
+}
+async function executeMetric(validatedMetric, prepared) {
+  const { metric, filters, requestKey } = validatedMetric;
+  const {
+    cacheMap,
+    granularity,
+    resolverCtx,
+    compareToPrevious,
+    disableCache,
+    cache
+  } = prepared;
+  const startedAt = Date.now();
+  try {
+    const cachedCurrent = cacheMap.get(getCacheKey(metric.key, filters, "current", granularity));
+    const prevRange = getPreviousPeriod({ from: filters.from, to: filters.to });
+    const cachedPrevious = prevRange ? cacheMap.get(getCacheKey(metric.key, { ...filters, ...prevRange }, "previous", granularity)) : undefined;
+    if (cachedCurrent) {
+      let previous = cachedPrevious;
+      let usedLivePreviousFetch = false;
+      if (!previous && compareToPrevious && metric.supportsTimeRange && filters.from && filters.to) {
+        usedLivePreviousFetch = true;
+        const partialResult = await runSingleMetric({
+          metric,
+          filters,
+          granularity,
+          compareToPrevious: true,
+          resolverCtx
+        });
+        previous = partialResult.previous;
+        if (previous && prevRange) {
+          const ttl2 = metric.cacheTtl ?? 600;
+          if (!disableCache && ttl2 > 0) {
+            cache.mset([
+              {
+                key: getCacheKey(metric.key, { ...filters, ...prevRange }, "previous", granularity),
+                value: JSON.stringify(previous),
+                ttl: ttl2
+              }
+            ]).catch((error) => console.error(error));
+          }
+        }
+      }
+      return {
+        key: metric.key,
+        requestKey,
+        result: {
+          current: cachedCurrent,
+          previous,
+          supportsTimeRange: metric.supportsTimeRange,
+          execution: {
+            cacheStatus: usedLivePreviousFetch ? "partialHit" : "hit",
+            durationMs: Date.now() - startedAt,
+            granularity
+          }
+        }
+      };
+    }
+    const result = await runSingleMetric({
+      metric,
+      filters,
+      granularity,
+      compareToPrevious,
+      resolverCtx
+    });
+    const ttl = metric.cacheTtl ?? 600;
+    if (!disableCache && ttl > 0) {
+      const cacheEntries = [
+        {
+          key: getCacheKey(metric.key, filters, "current", granularity),
+          value: JSON.stringify(result.current),
+          ttl
+        }
+      ];
+      if (result.previous) {
+        const prevRange2 = getPreviousPeriod({
+          from: filters.from,
+          to: filters.to
+        });
+        if (prevRange2) {
+          cacheEntries.push({
+            key: getCacheKey(metric.key, { ...filters, ...prevRange2 }, "previous", granularity),
+            value: JSON.stringify(result.previous),
+            ttl
+          });
+        }
+      }
+      cache.mset(cacheEntries).catch((error) => console.error(error));
+    }
+    return {
+      key: metric.key,
+      requestKey,
+      result: {
+        ...result,
+        execution: {
+          cacheStatus: disableCache ? "bypassed" : "miss",
+          durationMs: Date.now() - startedAt,
+          granularity
+        }
+      }
+    };
+  } catch (err) {
+    return {
+      key: metric.key,
+      requestKey,
+      error: err instanceof Error ? err.message : "Unknown error"
+    };
+  }
+}
+async function runMetrics(options) {
+  const prepared = await prepareMetrics(options);
+  const { validMetrics, errors } = prepared;
+  const results = {};
+  const outcomes = await Promise.all(validMetrics.map((vm) => executeMetric(vm, prepared)));
+  for (const outcome of outcomes) {
+    if (outcome.error) {
+      errors[outcome.requestKey ?? outcome.key] = outcome.error;
+    } else if (outcome.result) {
+      results[outcome.requestKey ?? outcome.key] = outcome.result;
+    }
+  }
+  return {
+    metrics: results,
+    errors
+  };
+}
+async function* runMetricsStream(options) {
+  const prepared = await prepareMetrics(options);
+  const { validMetrics, errors } = prepared;
+  const totalMetrics = validMetrics.length + Object.keys(errors).length;
+  let yieldedCount = 0;
+  for (const key of Object.keys(errors)) {
+    yieldedCount++;
+    yield {
+      key,
+      requestKey: key,
+      error: errors[key],
+      done: yieldedCount === totalMetrics
+    };
+  }
+  if (validMetrics.length === 0) {
+    return;
+  }
+  const pending = new Map;
+  for (const vm of validMetrics) {
+    const promise = executeMetric(vm, prepared);
+    pending.set(promise, vm.requestKey);
+  }
+  while (pending.size > 0) {
+    const settled = await Promise.race(Array.from(pending.keys()).map((p) => p.then((result) => ({ promise: p, result }))));
+    pending.delete(settled.promise);
+    yieldedCount++;
+    yield {
+      key: settled.result.key,
+      requestKey: settled.result.requestKey,
+      result: settled.result.result,
+      error: settled.result.error,
+      done: yieldedCount === totalMetrics
+    };
+  }
+}
+// src/type-guards.ts
+function isKpi(output2) {
+  return output2.kind === "kpi";
+}
+function isTimeSeries(output2) {
+  return output2.kind === "timeseries";
+}
+function isDistribution(output2) {
+  return output2.kind === "distribution";
+}
+function isTable(output2) {
+  return output2.kind === "table";
+}
+function isLeaderboard(output2) {
+  return output2.kind === "leaderboard";
+}
+function isPivot(output2) {
+  return output2.kind === "pivot";
+}
+// src/catalog.ts
+function defineMetricCatalogMetadata(metadata) {
+  return metadata;
+}
+// src/filters/types.ts
+function defineMetricFilterFieldMetadata(metadata) {
+  return metadata;
+}
+// src/filters/parse.ts
+function getDef(zodType) {
+  return zodType._def ?? {};
+}
+function getTypeName(zodType) {
+  const def = getDef(zodType);
+  if (def.typeName)
+    return def.typeName;
+  if (typeof def.type === "string") {
+    const v4ToV3Map = {
+      string: "ZodString",
+      number: "ZodNumber",
+      boolean: "ZodBoolean",
+      date: "ZodDate",
+      enum: "ZodEnum",
+      array: "ZodArray",
+      object: "ZodObject",
+      optional: "ZodOptional",
+      nullable: "ZodNullable",
+      default: "ZodDefault"
+    };
+    return v4ToV3Map[def.type] || def.type;
+  }
+  return;
+}
+function getEnumValues(zodType) {
+  const def = getDef(zodType);
+  const options = zodType.options;
+  if (Array.isArray(options)) {
+    return options.map(String);
+  }
+  if (def.entries && typeof def.entries === "object") {
+    return Object.values(def.entries).map(String);
+  }
+  if (def.values && typeof def.values === "object") {
+    return Object.values(def.values).map(String);
+  }
+  return [];
+}
+function getArrayElementType(zodType) {
+  const def = getDef(zodType);
+  if (def.element)
+    return def.element;
+  if (def.type && typeof def.type !== "string") {
+    return def.type;
+  }
+  return;
+}
+function getShape(zodType) {
+  return zodType.shape || {};
+}
+function unwrapZodType(zodType) {
+  const def = getDef(zodType);
+  const typeName = getTypeName(zodType);
+  const wrapperTypes = ["ZodOptional", "ZodNullable", "ZodDefault"];
+  if (typeName && wrapperTypes.includes(typeName) && def.innerType) {
+    return unwrapZodType(def.innerType);
+  }
+  return zodType;
+}
+function isMinMaxRangeObject(zodType) {
+  const shape = getShape(zodType);
+  const keys = Object.keys(shape);
+  const validKeys = ["min", "max"];
+  const hasOnlyValidKeys = keys.every((key) => validKeys.includes(key));
+  if (!hasOnlyValidKeys || keys.length === 0)
+    return false;
+  for (const key of keys) {
+    const fieldType = shape[key];
+    if (!fieldType)
+      return false;
+    const unwrapped = unwrapZodType(fieldType);
+    const typeName = getTypeName(unwrapped);
+    if (typeName !== "ZodNumber")
+      return false;
+  }
+  return true;
+}
+function determineTypeFromFilterObject(obj) {
+  const shape = getShape(obj);
+  for (const value of Object.values(shape)) {
+    const opValue = unwrapZodType(value);
+    const typeName = getTypeName(opValue);
+    switch (typeName) {
+      case "ZodNumber":
+        return "number";
+      case "ZodBoolean":
+        return "boolean";
+      case "ZodDate":
+        return "date";
+      case "ZodEnum":
+      case "ZodNativeEnum":
+        return "option";
+      case "ZodArray": {
+        const elementType = getArrayElementType(opValue);
+        const elementTypeName = elementType ? getTypeName(elementType) : null;
+        if (elementTypeName === "ZodEnum" || elementTypeName === "ZodNativeEnum") {
+          return "multiOption";
+        }
+        if (elementTypeName === "ZodNumber")
+          return "number";
+        break;
+      }
+    }
+  }
+  return "text";
+}
+function determineFieldType(zodType) {
+  const unwrapped = unwrapZodType(zodType);
+  const typeName = getTypeName(unwrapped);
+  if (typeName === "ZodObject") {
+    if (isMinMaxRangeObject(unwrapped))
+      return "numberRange";
+    return determineTypeFromFilterObject(unwrapped);
+  }
+  switch (typeName) {
+    case "ZodString":
+      return "text";
+    case "ZodNumber":
+      return "number";
+    case "ZodBoolean":
+      return "boolean";
+    case "ZodDate":
+      return "date";
+    case "ZodEnum":
+    case "ZodNativeEnum":
+      return "option";
+    case "ZodArray": {
+      const elementType = getArrayElementType(unwrapped);
+      const elementTypeName = elementType ? getTypeName(elementType) : null;
+      if (elementTypeName === "ZodEnum" || elementTypeName === "ZodNativeEnum") {
+        return "multiOption";
+      }
+      return "text";
+    }
+    default:
+      return "text";
+  }
+}
+function getDescription(zodType) {
+  const def = getDef(zodType);
+  if (def?.description)
+    return def.description;
+  const unwrapped = unwrapZodType(zodType);
+  const unwrappedDef = getDef(unwrapped);
+  if (unwrappedDef?.description)
+    return unwrappedDef.description;
+  if (getTypeName(unwrapped) === "ZodObject") {
+    const shape = getShape(unwrapped);
+    for (const value of Object.values(shape)) {
+      const opDef = getDef(value);
+      if (opDef?.description)
+        return opDef.description;
+    }
+  }
+  return;
+}
+function formatEnumValue(value) {
+  const label = value.toLowerCase().replace(/_/g, " ").replace(/\b\w/g, (str) => str.toUpperCase());
+  return { label, value };
+}
+function formatFieldDisplayName(fieldId) {
+  return fieldId.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/\b\w/g, (str) => str.toUpperCase());
+}
+function extractEnumValues(zodType) {
+  const unwrapped = unwrapZodType(zodType);
+  const typeName = getTypeName(unwrapped);
+  if (typeName === "ZodEnum" || typeName === "ZodNativeEnum") {
+    const values = getEnumValues(unwrapped);
+    return values.map(formatEnumValue);
+  }
+  if (typeName === "ZodArray") {
+    const elementType = getArrayElementType(unwrapped);
+    if (elementType) {
+      const elementTypeName = getTypeName(elementType);
+      if (elementTypeName === "ZodEnum" || elementTypeName === "ZodNativeEnum") {
+        const values = getEnumValues(elementType);
+        return values.map(formatEnumValue);
+      }
+    }
+  }
+  if (typeName === "ZodObject") {
+    const shape = getShape(unwrapped);
+    for (const value of Object.values(shape)) {
+      const opValue = unwrapZodType(value);
+      const opTypeName = getTypeName(opValue);
+      if (opTypeName === "ZodEnum" || opTypeName === "ZodNativeEnum") {
+        const values = getEnumValues(opValue);
+        return values.map(formatEnumValue);
+      }
+      if (opTypeName === "ZodArray") {
+        const elementType = getArrayElementType(opValue);
+        if (elementType) {
+          const elementTypeName = getTypeName(elementType);
+          if (elementTypeName === "ZodEnum" || elementTypeName === "ZodNativeEnum") {
+            const values = getEnumValues(elementType);
+            return values.map(formatEnumValue);
+          }
+        }
+      }
+    }
+  }
+  return [];
+}
+function parseMetricFilterSchema(schema, options) {
+  const excludeFields = new Set(options?.excludeFields ?? []);
+  const includeFields = options?.includeFields;
+  const fieldMetadata = options?.fieldMetadata ?? {};
+  const fields = [];
+  const unwrapped = unwrapZodType(schema);
+  if (getTypeName(unwrapped) !== "ZodObject")
+    return [];
+  const shape = getShape(unwrapped);
+  for (const [key, zodType] of Object.entries(shape)) {
+    if (excludeFields.has(key))
+      continue;
+    if (includeFields && !includeFields.includes(key))
+      continue;
+    const metadata = fieldMetadata[key];
+    const fieldType = metadata?.type ?? determineFieldType(zodType);
+    const description = metadata?.description ?? getDescription(zodType);
+    const enumOptions = metadata?.options ?? extractEnumValues(zodType);
+    fields.push({
+      id: key,
+      displayName: metadata?.displayName ?? formatFieldDisplayName(key),
+      type: fieldType,
+      description,
+      options: enumOptions.length > 0 ? enumOptions : undefined,
+      defaultOperator: metadata?.defaultOperator
+    });
+  }
+  return fields;
+}
+// src/filters/default-metadata.ts
+var COMMON_METRIC_FILTER_FIELD_METADATA = defineMetricFilterFieldMetadata({
+  metric: {
+    displayName: "Metric",
+    description: "Choose how the metric should be aggregated.",
+    defaultOperator: "is"
+  },
+  groupBy: {
+    displayName: "Group By",
+    description: "Split the metric into multiple groups.",
+    defaultOperator: "is"
+  },
+  limit: {
+    displayName: "Limit",
+    description: "Maximum number of rows to return."
+  },
+  view: {
+    displayName: "View",
+    description: "Choose which interpretation of the metric to render.",
+    defaultOperator: "is"
+  },
+  chartType: {
+    displayName: "Chart Type",
+    description: "Choose the preferred visualization for this metric.",
+    defaultOperator: "is"
+  }
+});
+function mergeMetricFilterFieldMetadata(...metadataEntries) {
+  return Object.assign({}, ...metadataEntries);
+}
+export {
+  validateOutput,
+  validateMetricOutput,
+  runMetricsStream,
+  runMetrics,
+  redisCacheAdapter,
+  parseMetricFilterSchema,
+  parseCache,
+  normalizeUserDate,
+  noopCacheAdapter,
+  mergeMetricFilterFieldMetadata,
+  isTimeSeries,
+  isTable,
+  isPivot,
+  isLeaderboard,
+  isKpi,
+  isDistribution,
+  inferGranularity,
+  getPreviousPeriod,
+  getOutputSchema,
+  getMetric,
+  getBucketStart,
+  generateBuckets,
+  extendTimeSeriesFilters,
+  extendBaseFilters,
+  defineTimeSeriesOutput,
+  defineTimeSeriesMetric,
+  defineTableOutput,
+  defineTableMetric,
+  definePivotOutput,
+  definePivotMetric,
+  defineMetricWithSchema,
+  defineMetricOutput,
+  defineMetricFilterFieldMetadata,
+  defineMetricCatalogMetadata,
+  defineLeaderboardOutput,
+  defineLeaderboardMetric,
+  defineKpiOutput,
+  defineKpiMetric,
+  defineDistributionOutput,
+  defineDistributionMetric,
+  createRegistry,
+  createMetricsEngine,
+  TimeSeriesSeriesSchema,
+  TimeSeriesPointSchema,
+  TimeSeriesOutputSchema,
+  TimeSeriesFiltersSchema,
+  TimeRangeSchema,
+  TimeGranularitySchema,
+  TableOutputSchema,
+  TableColumnSchema,
+  RequiredTimeRangeSchema,
+  PivotTotalsSchema,
+  PivotOutputSchema,
+  PivotDimensionSchema,
+  OutputSchemaMap,
+  OutputKindSchema,
+  MetricUnitSchema,
+  MetricTypeSchema,
+  MetricResultSchema,
+  MetricOutputSchema,
+  MetricExecutionSchema,
+  MetricExecutionCacheStatusSchema,
+  LeaderboardOutputSchema,
+  LeaderboardItemSchema,
+  KpiOutputSchema,
+  DistributionSegmentSchema,
+  DistributionOutputSchema,
+  DistributionChartTypeSchema,
+  CompareSchema,
+  COMMON_METRIC_FILTER_FIELD_METADATA,
+  BaseFiltersSchema
+};