measurr 0.5.0 → 0.6.0

package/README.md

@@ -242,6 +242,95 @@ toLeaderboard(result, { by: 'region', measure: 'revenue' }) // ranked rows with
 - `toDistribution`'s `total` is the measure over every row, so many-to-many shares can add up to
   more than 1. `toPivot` sorts numeric keys (weekdays, hours).
 
+### Presentation
+
+`presentKpi`, `presentTimeseries`, `presentDistribution` and `presentLeaderboard` turn a result
+into the wire outputs a dashboard draws (`KpiOutput`, `TimeSeriesOutput`, `DistributionOutput`,
+`LeaderboardOutput`; `TableOutput` and `PivotOutput` for outputs you build yourself). A missing
+value is 0, keys are strings, and the caller picks labels, units and chart types:
+
+```ts
+presentKpi(result, 'paidShare', { label: 'Paid', percent: true })
+// { kind: 'kpi', value: 25, unit: 'PERCENTAGE', label: 'Paid' }
+
+presentTimeseries(result, {
+	bucket: 'day', measure: 'orders', series: 'status',
+	keys: { PAID: 'paid' }, // wire keys, by String(key); 'null' names the empty group
+	labels: { paid: 'Settled' }, // labels by wire key
+	chartType: 'line'
+})
+// points are { ts: Date, value }: ts is the bucket's local start date as UTC midnight
+
+presentDistribution(result, { by: 'tag', measure: 'orders', chartType: 'donut', order: ['t2'] })
+// total is what the segments add up to, percent is 0-100; keys order omits go last
+
+presentLeaderboard(result, { by: 'region', measure: 'orders', meta: (values) => ({ revenue: values.revenue }) })
+```
+
+`isKpi`, `isTimeSeries`, `isDistribution`, `isTable`, `isLeaderboard` and `isPivot` narrow a
+`MetricOutput`. The module is pure, so a browser bundle can import the types and guards.
+
+## Dashboard metrics
+
+`measurr/metrics` names the numbers a dashboard shows: one query and the output it is drawn
+in. The registry runs a batch for a caller and streams one chunk per metric.
+
+```ts
+import { createMetricRegistry, metricDefiner } from 'measurr/metrics'
+import { presentKpi, presentTimeseries } from 'measurr/shapes'
+
+// Types only, so metric modules need not import the analytics instance.
+export const defineMetric = metricDefiner<(typeof datasets)[number], Role>()
+
+const orderTrend = defineMetric({
+	key: 'orders.trend',
+	kind: 'timeseries',
+	description: 'Orders over time',
+	allowedRoles: ['owner', 'member'],
+	supportsTimeRange: true, // false for a snapshot: all time, no previous period
+	filterSchema: z.object({ status: z.enum(['OPEN', 'PAID']).optional() }),
+	query: ({ bucket, filters }) => ({
+		dataset: 'orders',
+		measures: ['orders'],
+		groupBy: [bucket],
+		filters: filters.status ? [{ dimension: 'status', op: 'in', values: [filters.status] }] : [],
+		limit: 100
+	}),
+	shape: (result, { bucket }) =>
+		presentTimeseries(result, { bucket, measure: 'orders', chartType: 'bar' })
+})
+
+export const metrics = createMetricRegistry({
+	analytics,
+	metrics: [orderTrend, orderCount] as const,
+	canRun: (metric, ctx) => ctx.isSuperAdmin || (metric.allowedRoles ?? []).includes(ctx.role),
+	onShapeError: (error, metric) => logger.error('metric.shape_failed', { key: metric.key, error })
+})
+
+const input = metrics.requestSchema.extend({ refresh: z.boolean().default(false) }).parse(body)
+for await (const chunk of metrics.run(input, ctx)) send(chunk)
+// { key, requestKey, result: { current, previous?, supportsTimeRange }, done }
+// or { key, requestKey, error, done }
+```
+
+- `query` returns the query without `period` or `compareToPrevious`. The registry counts the
+  local days `from` and `to` (instants) fall on in `analytics.timezone(ctx)`, all time without
+  them, and always all time for a snapshot. `compareToPrevious` adds the previous period, whose
+  series points are put on the current buckets so a chart overlays them.
+- `granularity` (hour to year, inferred from the range when omitted: day up to 31 days, week up
+  to 90, else month) picks `run.bucket`: `day`, `week` or `month`. Name time-bucket dimensions
+  after them so `groupBy: [bucket]` works.
+- A metric that `canRun` refuses (`'Access denied'`), whose filters do not parse with its
+  `filterSchema` (`'Invalid filters: ...'`), whose query fails (the engine's message) or whose
+  `shape` throws (`'The metric could not be drawn'`) fails alone. `done` marks the last chunk.
+- `metricDefiner<Datasets, Role, Extra>()` takes the app's own definition fields as `Extra`
+  (catalog metadata, UI hints for filters); the registry carries them to `canRun` and
+  `available` without reading them.
+- Keys and outputs stay literal: a chunk narrows to its metric by `key`, and
+  `MetricOutputOf<typeof metrics, 'orders.trend'>`, `MetricFiltersOf`, `MetricKeysOfKind` and
+  `registry.get(key)` are typed per metric. `registry.available(ctx)` lists what `canRun`
+  allows, for a catalog.
+
 ## Serving queries
 
 `measurr/handler` serves queries from any server framework:
@@ -517,7 +606,9 @@ Kept stable for publishing: `createAnalytics` and its options (with `authorize`,
 `streamBatch`, `toHttpError`); and the types `AnalyticsQuery`, `AnalyticsResult`,
 `ResultPeriod`, `PeriodInput`, `Tenant`, `TenantId`, `AccessKey`, `AnalyticsCache`, `FieldKey`,
 `Ratio`, `AnalyticsError` codes and their details (`isAnalyticsError`). `ExprNode` and
-`SelectStatement` are exported for dialect authors and may grow new node kinds.
+`SelectStatement` are exported for dialect authors and may grow new node kinds. The
+presenters and wire outputs in `measurr/shapes`, `measurr/metrics` and `analytics.timezone`
+are new and may still change before they join this list.
 
 ## Install
 

package/dist/analytics.d.ts

@@ -174,6 +174,11 @@ export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
     }): Promise<z.ZodType<DatasetQuery<DS[number]>>>;
     /** The result schema for one dataset. */
     resultSchema(dataset: DS[number]['key']): z.ZodType<QueryResult<Row, Row>>;
+    /**
+     * The timezone `ctx`'s periods and buckets resolve in: the `timezone` hook's answer, UTC
+     * when it has none. Rejects with `invalid_timezone` for a name the runtime does not know.
+     */
+    timezone(ctx: Ctx): Promise<string>;
     /** The datasets `ctx` may query, with the measures and dimensions it may use. */
     listDatasets(ctx: Ctx): Promise<DatasetCatalogEntry<DS[number]['key']>[]>;
 };

package/dist/handler.js

@@ -1,49 +1,11 @@
 import {
-  AnalyticsError2
-} from "./index-zgb1e89d.js";
-
-// src/handler.ts
-async function queryBatch(analytics, queries, ctx) {
-  const results = {};
-  const errors = {};
-  for await (const chunk of streamBatch(analytics, queries, ctx)) {
-    if ("error" in chunk)
-      errors[chunk.key] = chunk.error;
-    else
-      results[chunk.key] = chunk.result;
-  }
-  return { results, errors };
-}
-async function* streamBatch(analytics, queries, ctx) {
-  const pending = new Map(Object.entries(queries).map(([key, query]) => {
-    const settled = analytics.query(query, ctx).then((result) => ({ key, result }), (error) => ({ key, error: batchError(error) }));
-    return [key, settled];
-  }));
-  while (pending.size > 0) {
-    const chunk = await Promise.race(pending.values());
-    pending.delete(chunk.key);
-    yield chunk;
-  }
-}
-function batchError(error) {
-  return error instanceof AnalyticsError2 ? { code: error.code, message: error.message } : { code: "internal", message: "The query failed" };
-}
-function toHttpError(error) {
-  if (error.code === "forbidden") {
-    return { status: 403, code: "FORBIDDEN", message: error.message };
-  }
-  if (error.code === "missing_tenant") {
-    return { status: 401, code: "UNAUTHORIZED", message: error.message };
-  }
-  return {
-    status: 400,
-    code: "BAD_REQUEST",
-    message: error.message,
-    data: { code: error.code, details: error.details }
-  };
-}
+  queryBatch2,
+  streamBatch2,
+  toHttpError2
+} from "./index-xf6qpmgy.js";
+import"./index-z5xv3ffk.js";
 export {
-  queryBatch,
-  streamBatch,
-  toHttpError
+  queryBatch2 as queryBatch,
+  streamBatch2 as streamBatch,
+  toHttpError2 as toHttpError
 };

package/dist/{index-g255jb1s.js → index-115syy01.js}

@@ -146,4 +146,4 @@ function bucketStarts(from, to, unit) {
   return starts;
 }
 
-export { MAX_PERIOD_DAYS, DEFAULT_PERIOD, isValidTimezone, PeriodError, resolvePeriod, previousPeriod, bucketStarts };
+export { MAX_PERIOD_DAYS, DEFAULT_PERIOD, isValidTimezone, localDate, PeriodError, resolvePeriod, previousPeriod, bucketStarts };

package/dist/{index-g2mjqx4f.js → index-pgccd363.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-e6k30sfp.js";
 import {
   DEFAULT_PERIOD
-} from "./index-g255jb1s.js";
+} from "./index-115syy01.js";
 
 // src/dataset.ts
 function aggregate(result, fn, arg, options) {

package/dist/index-xf6qpmgy.js

@@ -0,0 +1,46 @@
+import {
+  AnalyticsError2
+} from "./index-z5xv3ffk.js";
+
+// src/handler.ts
+async function queryBatch2(analytics, queries, ctx) {
+  const results = {};
+  const errors = {};
+  for await (const chunk of streamBatch2(analytics, queries, ctx)) {
+    if ("error" in chunk)
+      errors[chunk.key] = chunk.error;
+    else
+      results[chunk.key] = chunk.result;
+  }
+  return { results, errors };
+}
+async function* streamBatch2(analytics, queries, ctx) {
+  const pending = new Map(Object.entries(queries).map(([key, query]) => {
+    const settled = analytics.query(query, ctx).then((result) => ({ key, result }), (error) => ({ key, error: batchError(error) }));
+    return [key, settled];
+  }));
+  while (pending.size > 0) {
+    const chunk = await Promise.race(pending.values());
+    pending.delete(chunk.key);
+    yield chunk;
+  }
+}
+function batchError(error) {
+  return error instanceof AnalyticsError2 ? { code: error.code, message: error.message } : { code: "internal", message: "The query failed" };
+}
+function toHttpError2(error) {
+  if (error.code === "forbidden") {
+    return { status: 403, code: "FORBIDDEN", message: error.message };
+  }
+  if (error.code === "missing_tenant") {
+    return { status: 401, code: "UNAUTHORIZED", message: error.message };
+  }
+  return {
+    status: 400,
+    code: "BAD_REQUEST",
+    message: error.message,
+    data: { code: error.code, details: error.details }
+  };
+}
+
+export { queryBatch2, streamBatch2, toHttpError2 };

package/dist/{index-zgb1e89d.js → index-z5xv3ffk.js}

@@ -4,7 +4,7 @@ import {
   PeriodError,
   resolvePeriod,
   previousPeriod
-} from "./index-g255jb1s.js";
+} from "./index-115syy01.js";
 
 // src/query.ts
 import { z } from "zod";
@@ -685,6 +685,13 @@ function createAnalytics2(options) {
     }
     return querySchemaFor(allowed);
   };
+  const timezoneOf = async (ctx) => {
+    const timezone = await options.timezone?.(ctx) || "UTC";
+    if (!isValidTimezone(timezone)) {
+      throw new AnalyticsError2("invalid_timezone", `Unknown timezone ${timezone}`);
+    }
+    return timezone;
+  };
   const prepare = async (input, ctx) => {
     const parsed = querySchemaFor(datasets).safeParse(input);
     if (!parsed.success) {
@@ -711,10 +718,7 @@ function createAnalytics2(options) {
     if (!dataset.tenantColumn && tenant !== allTenants2) {
       throw new AnalyticsError2("forbidden", `${dataset.key} has no tenant column; only a caller allowed to see every tenant may query it`);
     }
-    const timezone = await options.timezone?.(ctx) || "UTC";
-    if (!isValidTimezone(timezone)) {
-      throw new AnalyticsError2("invalid_timezone", `Unknown timezone ${timezone}`);
-    }
+    const timezone = await timezoneOf(ctx);
     const query = normalizeQuery(dataset, parsedQuery);
     const at = now();
     let period;
@@ -858,6 +862,7 @@ function createAnalytics2(options) {
     explain,
     querySchema: (schemaOptions) => schemaOptions && ("ctx" in schemaOptions) ? querySchemaForCtx(schemaOptions.ctx) : querySchemaFor(schemaOptions?.datasets?.map(datasetOf) ?? datasets),
     resultSchema: (key) => resultSchemaFor(key),
+    timezone: timezoneOf,
     listDatasets: async (ctx) => (await allowedDatasets(ctx)).map((dataset) => catalogEntry(dataset))
   };
 }

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   AnalyticsError2,
   isAnalyticsError2,
   createAnalytics2
-} from "./index-zgb1e89d.js";
+} from "./index-z5xv3ffk.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -14,7 +14,7 @@ import {
   measure2,
   dimension2,
   defineDataset2
-} from "./index-g2mjqx4f.js";
+} from "./index-pgccd363.js";
 import {
   Expr2,
   Table2,

package/dist/metrics.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Named dashboard metrics: one query over a dataset and the shape it is drawn in. The
+ * registry runs a batch of them for a caller and yields each as it finishes; the period, the
+ * previous period and the tenant scope come from the request and `ctx`, never from a metric.
+ */
+import { z } from 'zod';
+import type { Analytics } from './analytics.js';
+import type { AnyDataset } from './dataset.js';
+import type { DatasetQuery, QueryResult, ResultOf } from './query.js';
+import type { MetricOutput, OutputForKind, OutputKind, TimeGranularity } from './shapes.js';
+/** The buckets a time series is grouped by. */
+export type MetricBucket = 'day' | 'week' | 'month';
+/** What a metric's `query` and `shape` are run with. */
+export type MetricRun<Filters> = {
+    /** The metric's own filters, parsed with its `filterSchema`. */
+    filters: Filters;
+    /** The time-bucket dimension to group a series by: the granularity, as near as it gets. */
+    bucket: MetricBucket;
+    granularity: TimeGranularity;
+};
+/** A result as `shape` receives it: one period, without `previous`. */
+export type MetricQueryResult<DS, Q> = ResultOf<DS, Q> extends QueryResult<infer Row, infer Totals, infer _Period> ? Omit<QueryResult<Row, Totals>, 'previous'> : never;
+export type MetricDefinition<DS extends AnyDataset, Key extends string, Kind extends OutputKind, Filters, Q extends DatasetQuery<DS>, Output extends OutputForKind<Kind>, Role extends string = string> = {
+    key: Key;
+    kind: Kind;
+    description: string;
+    /** For `canRun`; the registry does not read it. */
+    allowedRoles?: readonly Role[] | undefined;
+    /** False for a snapshot of now: it counts all time and has no previous period. */
+    supportsTimeRange: boolean;
+    filterSchema: z.ZodType<Filters>;
+    /** The query, without `period` or `compareToPrevious`: the registry sets those. */
+    query: (run: MetricRun<Filters>) => Q;
+    /** Called once for the period and once for the previous period. */
+    shape: (result: MetricQueryResult<DS, Q>, run: MetricRun<Filters>) => Output;
+};
+/**
+ * `defineMetric` for metrics over the datasets `DS` (a union), with `allowedRoles` typed as
+ * `Role` and the app's own fields `Extra` (catalog metadata, say), which the registry carries
+ * along but does not read. Types only, so metric modules need not import the analytics
+ * instance:
+ *
+ * ```ts
+ * export const defineMetric = metricDefiner<(typeof datasets)[number], Role>()
+ * ```
+ */
+export declare function metricDefiner<DS extends AnyDataset, Role extends string = string, Extra extends object = Record<never, never>>(): <const Key extends string, const Kind extends OutputKind, Filters, const Q extends DatasetQuery<DS>, Output extends OutputForKind<Kind>>(definition: MetricDefinition<DS, Key, Kind, Filters, Q, Output, Role> & Extra) => MetricDefinition<DS, Key, Kind, Filters, Q, Output, Role> & Extra;
+/** Any metric, as the registry holds them. */
+export type AnyMetric = {
+    key: string;
+    kind: OutputKind;
+    description: string;
+    allowedRoles?: readonly string[] | undefined;
+    supportsTimeRange: boolean;
+    filterSchema: z.ZodType<any>;
+    query: (run: MetricRun<any>) => DatasetQuery<AnyDataset>;
+    shape: (result: any, run: MetricRun<any>) => MetricOutput;
+};
+export type MetricKeyOf<R extends {
+    metrics: readonly AnyMetric[];
+}> = R['metrics'][number]['key'];
+export type MetricOf<R extends {
+    metrics: readonly AnyMetric[];
+}, K extends MetricKeyOf<R>> = Extract<R['metrics'][number], {
+    key: K;
+}>;
+export type MetricOutputOf<R extends {
+    metrics: readonly AnyMetric[];
+}, K extends MetricKeyOf<R>> = ReturnType<MetricOf<R, K>['shape']>;
+export type MetricFiltersOf<R extends {
+    metrics: readonly AnyMetric[];
+}, K extends MetricKeyOf<R>> = z.infer<MetricOf<R, K>['filterSchema']>;
+export type MetricKeysOfKind<R extends {
+    metrics: readonly AnyMetric[];
+}, Kind extends OutputKind> = Extract<R['metrics'][number], {
+    kind: Kind;
+}>['key'];
+/** One metric's numbers: the period, and the previous period on the same buckets. */
+export type MetricResult<Output = MetricOutput> = {
+    current: Output;
+    previous?: Output;
+    supportsTimeRange: boolean;
+};
+/** One metric's result or error, as each finishes. */
+export type MetricChunk<M extends AnyMetric = AnyMetric> = M extends AnyMetric ? {
+    key: M['key'];
+    /** The request's name for it; the key unless one request asks for a metric twice. */
+    requestKey: string;
+    /** Whether this is the last chunk of the request. */
+    done: boolean;
+} & ({
+    result: MetricResult<ReturnType<M['shape']>>;
+    error?: undefined;
+} | {
+    error: string;
+    result?: undefined;
+}) : never;
+export type MetricsRequest<Key extends string = string> = {
+    metrics: readonly {
+        key: Key;
+        requestKey?: string | undefined;
+        filters?: unknown;
+    }[];
+    /** Instants; the registry counts the local days they fall on in `analytics.timezone(ctx)`. */
+    from?: Date | undefined;
+    to?: Date | undefined;
+    /** Inferred from the range when omitted: day up to 31 days, week up to 90, else month. */
+    granularity?: TimeGranularity | undefined;
+    compareToPrevious?: boolean | undefined;
+};
+export type MetricRegistry<M extends readonly AnyMetric[], Ctx> = {
+    readonly metrics: M;
+    /** The keys, for a request schema or a catalog. */
+    readonly keys: [M[number]['key'], ...M[number]['key'][]];
+    /** The request schema; `.extend` it with the app's own fields. */
+    readonly requestSchema: z.ZodObject<{
+        metrics: z.ZodArray<z.ZodObject<{
+            key: z.ZodEnum<{
+                [K in M[number]['key']]: K;
+            }>;
+            requestKey: z.ZodOptional<z.ZodString>;
+            filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }>>;
+        from: z.ZodOptional<z.ZodDate>;
+        to: z.ZodOptional<z.ZodDate>;
+        granularity: z.ZodOptional<z.ZodEnum<{
+            [G in TimeGranularity]: G;
+        }>>;
+        compareToPrevious: z.ZodDefault<z.ZodBoolean>;
+    }>;
+    get<K extends M[number]['key']>(key: K): Extract<M[number], {
+        key: K;
+    }>;
+    /** The metrics `canRun` allows for `ctx`. */
+    available(ctx: Ctx): Promise<M[number][]>;
+    /**
+     * Runs the requested metrics in parallel and yields each as it finishes. A metric `ctx` may
+     * not run, or whose filters do not parse, fails alone. A metric that supports a time range
+     * counts `from` to `to` (all time without them) and compares with the previous period when
+     * asked; a snapshot counts all time.
+     */
+    run(request: MetricsRequest<M[number]['key']>, ctx: Ctx): AsyncGenerator<MetricChunk<M[number]>, void, undefined>;
+};
+export type MetricRegistryOptions<DS extends readonly AnyDataset[], M extends readonly AnyMetric[], Ctx> = {
+    analytics: Analytics<DS, Ctx>;
+    metrics: M;
+    /** Whether `ctx` may run `metric`. Every metric runs when omitted. */
+    canRun?: ((metric: M[number], ctx: Ctx) => boolean | Promise<boolean>) | undefined;
+    /** Hears a `shape` that throws; the metric fails with "The metric could not be drawn". */
+    onShapeError?: ((error: unknown, metric: M[number], ctx: Ctx) => unknown) | undefined;
+};
+export declare function createMetricRegistry<DS extends readonly AnyDataset[], const M extends readonly AnyMetric[], Ctx>(options: MetricRegistryOptions<DS, M, Ctx>): MetricRegistry<M, Ctx>;

package/dist/metrics.js

@@ -0,0 +1,167 @@
+import"./index-z5xv3ffk.js";
+import {
+  streamBatch2
+} from "./index-xf6qpmgy.js";
+import {
+  localDate
+} from "./index-115syy01.js";
+
+// src/metrics.ts
+import { z } from "zod";
+function metricDefiner() {
+  return (definition) => definition;
+}
+var GRANULARITIES = [
+  "hour",
+  "day",
+  "week",
+  "month",
+  "quarter",
+  "year"
+];
+function createMetricRegistry(options) {
+  const { analytics, metrics } = options;
+  const byKey = new Map;
+  for (const metric of metrics) {
+    if (byKey.has(metric.key))
+      throw new Error(`Two metrics use the key ${metric.key}`);
+    byKey.set(metric.key, metric);
+  }
+  const keys = metrics.map((metric) => metric.key);
+  if (keys.length === 0)
+    throw new Error("A registry needs a metric");
+  const canRun = (metric, ctx) => options.canRun ? options.canRun(metric, ctx) : true;
+  const requestSchema = z.object({
+    metrics: z.array(z.object({
+      key: z.enum(keys),
+      requestKey: z.string().optional(),
+      filters: z.record(z.string(), z.unknown()).optional()
+    })).min(1, "At least one metric required"),
+    from: z.date().optional(),
+    to: z.date().optional(),
+    granularity: z.enum(GRANULARITIES).optional(),
+    compareToPrevious: z.boolean().default(false)
+  });
+  async function* run(request, ctx) {
+    const timezone = await analytics.timezone(ctx);
+    const granularity = request.granularity ?? inferGranularity(request.from, request.to);
+    const bucket = bucketFor(granularity);
+    const range = request.from && request.to ? {
+      from: localDate(request.from, timezone),
+      to: localDate(request.to, timezone)
+    } : null;
+    const failed = [];
+    const runs = new Map;
+    const queries = {};
+    for (const requested of request.metrics) {
+      const requestKey = requested.requestKey ?? requested.key;
+      const fail = (error) => failed.push({ key: requested.key, requestKey, error });
+      const metric = byKey.get(requested.key);
+      if (!metric) {
+        fail("Unknown metric");
+        continue;
+      }
+      if (!await canRun(metric, ctx)) {
+        fail("Access denied");
+        continue;
+      }
+      const filters = metric.filterSchema.safeParse(requested.filters ?? {});
+      if (!filters.success) {
+        fail(`Invalid filters: ${filters.error.message}`);
+        continue;
+      }
+      const metricRun = { filters: filters.data, bucket, granularity };
+      const period = metric.supportsTimeRange ? range : null;
+      queries[requestKey] = {
+        ...metric.query(metricRun),
+        period: period ?? { all: true },
+        compareToPrevious: period !== null && !!request.compareToPrevious
+      };
+      runs.set(requestKey, { metric, run: metricRun });
+    }
+    const total = failed.length + runs.size;
+    let yielded = 0;
+    const next = (chunk) => ({ ...chunk, done: ++yielded === total });
+    for (const chunk of failed)
+      yield next(chunk);
+    for await (const chunk of streamBatch2(analytics, queries, ctx)) {
+      const prepared = runs.get(chunk.key);
+      if (!prepared)
+        continue;
+      const { metric, run: metricRun } = prepared;
+      const base = { key: metric.key, requestKey: chunk.key };
+      if ("error" in chunk) {
+        yield next({ ...base, error: chunk.error.message });
+        continue;
+      }
+      let result;
+      try {
+        const { previous, ...current } = chunk.result;
+        const output = metric.shape(current, metricRun);
+        result = {
+          current: output,
+          supportsTimeRange: metric.supportsTimeRange
+        };
+        if (previous) {
+          result.previous = alignPrevious(metric.shape({ ...current, ...previous }, metricRun), output);
+        }
+      } catch (error) {
+        try {
+          await options.onShapeError?.(error, metric, ctx);
+        } catch {}
+        yield next({ ...base, error: "The metric could not be drawn" });
+        continue;
+      }
+      yield next({ ...base, result });
+    }
+  }
+  return {
+    metrics,
+    keys,
+    requestSchema,
+    get: (key) => byKey.get(key),
+    available: async (ctx) => {
+      const allowed = await Promise.all(metrics.map((metric) => canRun(metric, ctx)));
+      return metrics.filter((_, index) => allowed[index]);
+    },
+    run
+  };
+}
+function bucketFor(granularity) {
+  if (granularity === "hour" || granularity === "day")
+    return "day";
+  if (granularity === "week")
+    return "week";
+  return "month";
+}
+function inferGranularity(from, to) {
+  if (!from || !to)
+    return "day";
+  const days = (to.getTime() - from.getTime()) / 86400000;
+  if (days <= 31)
+    return "day";
+  if (days <= 90)
+    return "week";
+  return "month";
+}
+function alignPrevious(previous, current) {
+  if (previous.kind !== "timeseries" || current.kind !== "timeseries")
+    return previous;
+  return {
+    ...previous,
+    series: previous.series.map((series) => {
+      const points = current.series.find((entry) => entry.key === series.key)?.points;
+      return {
+        ...series,
+        points: series.points.map((point, index) => ({
+          ...point,
+          ts: points?.[index]?.ts ?? point.ts
+        }))
+      };
+    })
+  };
+}
+export {
+  createMetricRegistry,
+  metricDefiner
+};