measurr 0.5.0 → 0.7.0

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

@@ -4,7 +4,7 @@ import {
   PeriodError,
   resolvePeriod,
   previousPeriod
-} from "./index-g255jb1s.js";
+} from "./index-115syy01.js";
 
 // src/query.ts
 import { z } from "zod";
@@ -108,7 +108,8 @@ function datasetQuerySchema(dataset) {
     throw new Error(`Dataset ${dataset.key} has no measures`);
   const groupKeys = nonEmpty(groupable.map(([key]) => key));
   const timeKeys = nonEmpty(Object.keys(dataset.time));
-  const sortKeys = nonEmpty([...measureKeys, ...groupKeys ?? []]) ?? measureKeys;
+  const sqlMeasureKeys = measures.filter(([, entry]) => entry.kind !== "resolved").map(([key]) => key);
+  const sortKeys = nonEmpty([...sqlMeasureKeys, ...groupKeys ?? []]) ?? measureKeys;
   const notes = groupable.filter(([, dim]) => dim.kind === "manyToMany" && dim.note).map(([key, dim]) => `${key}: ${dim.kind === "manyToMany" ? dim.note : ""}`);
   const [firstFilter, ...otherFilters] = filterable.map(([key, dim]) => filterSchema(key, dim));
   return z.object({
@@ -142,6 +143,14 @@ function datasetQuerySchema(dataset) {
         message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(", ")}`
       });
     }
+    const sortMeasure = by === undefined ? undefined : dataset.measures[by];
+    if (sortMeasure?.kind === "resolved") {
+      context.addIssue({
+        code: "custom",
+        path: ["sort", "by"],
+        message: `${by} is computed after the query runs and cannot be sorted by`
+      });
+    }
     const period = query.period ?? dataset.defaultPeriod;
     if (query.compareToPrevious && "all" in period) {
       context.addIssue({
@@ -256,8 +265,23 @@ function measureNode(dataset, key) {
         left: measureNode(dataset, entry.numerator),
         right: measureNode(dataset, entry.denominator)
       };
+    case "resolved":
+      throw new Error(`Dataset ${dataset.key}: measure ${key} is resolved by the app, not the database`);
   }
 }
+function sqlMeasures(dataset, keys) {
+  const result = new Set;
+  for (const key of keys) {
+    const entry = measureOf(dataset, key);
+    if (entry.kind === "resolved") {
+      for (const used of entry.uses)
+        result.add(used);
+    } else {
+      result.add(key);
+    }
+  }
+  return [...result];
+}
 function dimensionNodes(dataset, key, timezone) {
   const entry = dimensionOf(dataset, key);
   switch (entry.kind) {
@@ -410,12 +434,19 @@ function planQuery(dataset, query, context, grouped) {
       select.push({ alias: columnAlias.groupLabel(key), node: nodes.label });
     }
   }
-  for (const key of query.measures) {
+  const measureKeys = sqlMeasures(dataset, query.measures);
+  for (const key of measureKeys) {
     select.push({
       alias: columnAlias.measure(key),
       node: measureNode(dataset, key)
     });
   }
+  if (select.length === 0) {
+    select.push({
+      alias: "row_count",
+      node: { kind: "aggregate", fn: "count", arg: null, where: null }
+    });
+  }
   const where = [
     ...baseWhere(dataset, context.tenant, context.period && {
       time: query.time,
@@ -442,7 +473,10 @@ function orderBy(dataset, query, select) {
     const kind = dimensionOf(dataset, key).kind;
     return kind === "timeBucket" || kind === "timePart";
   });
-  const sort = query.sort ?? (timeKey ? { by: timeKey, direction: "asc" } : { by: query.measures[0] ?? "", direction: "desc" });
+  const sort = query.sort ?? (timeKey ? { by: timeKey, direction: "asc" } : {
+    by: sqlMeasures(dataset, query.measures)[0] ?? "",
+    direction: "desc"
+  });
   const sortIndex = sort.by in dataset.measures ? indexOf(columnAlias.measure(sort.by)) : indexOf(columnAlias.groupKey(sort.by));
   if (sortIndex >= 0)
     order.push({ index: sortIndex, direction: sort.direction });
@@ -546,8 +580,11 @@ function labelOf(dimension, key, rawLabel) {
 function shapeMeasures(dataset, measures, raw, dialect) {
   const values = {};
   for (const key of measures) {
+    const entry = measureOf(dataset, key);
+    if (entry.kind === "resolved")
+      continue;
     const value = dialect.decodeNumber(raw[columnAlias.measure(key)]);
-    values[key] = measureOf(dataset, key).result === "count" ? value ?? 0 : value;
+    values[key] = entry.result === "count" ? value ?? 0 : value;
   }
   return values;
 }
@@ -566,7 +603,7 @@ function shapeRows(dataset, query, rawRows, dialect) {
     }
     return { ...row, ...shapeMeasures(dataset, query.measures, raw, dialect) };
   });
-  return { rows, truncated };
+  return { rows, kept, truncated };
 }
 function resultNotes(dataset, query) {
   const notes = [];
@@ -613,6 +650,25 @@ function createAnalytics2(options) {
     }
     restrictedOf.set(dataset.key, restricted);
   }
+  const resolvers = options.resolvers ?? {};
+  for (const [datasetKey, entries] of Object.entries(resolvers)) {
+    const dataset = byKey.get(datasetKey);
+    if (!dataset)
+      throw new Error(`Resolvers name unknown dataset ${datasetKey}`);
+    for (const key of Object.keys(entries ?? {})) {
+      const entry = dataset.measures[key];
+      if (entry?.kind !== "resolved") {
+        throw new Error(`Resolvers name ${datasetKey}.${key}, which is not a resolved measure`);
+      }
+    }
+  }
+  for (const dataset of datasets) {
+    for (const [key, entry] of Object.entries(dataset.measures)) {
+      if (entry.kind === "resolved" && !resolvers[dataset.key]?.[key]) {
+        throw new Error(`Dataset ${dataset.key} resolves ${key} in the app, but createAnalytics has no resolver for it`);
+      }
+    }
+  }
   const now = options.now ?? (() => new Date);
   const querySchemas = new Map;
   const resultSchemas = new Map;
@@ -685,6 +741,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 +774,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;
@@ -729,12 +789,13 @@ function createAnalytics2(options) {
     const previous = query.compareToPrevious && period ? previousPeriod(period) : null;
     return { dataset, query, tenant, timezone, period, previous, now: at };
   };
-  const runQuery = async (prepared) => {
+  const runQuery = async (prepared, ctx) => {
     const { dataset, query, tenant, timezone, period, previous, now } = prepared;
     const source = sourceFor(dataset);
     const { dialect } = source;
     const run = (statement) => source.execute(dialect.compile(statement));
     const resolvedValues = await resolveOpenValues(dataset, query, tenant, now, run, dialect);
+    const range = ({ from, to }) => ({ from, to, timezone });
     const runPeriod = async (target) => {
       const statements = periodStatements(dataset, query, {
         tenant,
@@ -747,12 +808,46 @@ function createAnalytics2(options) {
         run(statements.rows),
         statements.totals ? run(statements.totals) : null
       ]);
-      const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect);
+      const { rows, kept, truncated } = shapeRows(dataset, query, rawRows, dialect);
       const totalsRow = (rawTotals ?? rawRows)[0] ?? {};
       const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect);
+      for (const key of query.measures) {
+        const entry = dataset.measures[key];
+        if (entry?.kind !== "resolved")
+          continue;
+        const used = (raw) => shapeMeasures(dataset, entry.uses, raw, dialect);
+        const resolver = resolvers[dataset.key]?.[key];
+        if (!resolver)
+          throw new Error(`No resolver for ${dataset.key}.${key}`);
+        const output = await resolver({
+          rows: kept.map((raw, index) => ({
+            dimensions: Object.fromEntries(query.groupBy.map((group) => [group, rows[index]?.[group]])),
+            values: used(raw)
+          })),
+          totals: used(totalsRow),
+          groupBy: query.groupBy,
+          filters: query.filters.map((filter) => {
+            const resolved = resolvedValues.get(filter.dimension);
+            return resolved && "values" in filter ? { ...filter, values: [...resolved] } : filter;
+          }),
+          period: target ? range(target) : { all: true, timezone },
+          tenant,
+          ctx
+        });
+        if (output.rows.length !== rows.length) {
+          throw new Error(`The resolver for ${dataset.key}.${key} returned ${output.rows.length} values for ${rows.length} rows`);
+        }
+        const value = (raw) => {
+          const finite = typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+          return entry.result === "count" ? finite ?? 0 : finite;
+        };
+        rows.forEach((row, index) => {
+          row[key] = value(output.rows[index]);
+        });
+        totals[key] = value(output.totals);
+      }
       return { rows, totals, truncated };
     };
-    const range = ({ from, to }) => ({ from, to, timezone });
     const [current, before] = await Promise.all([
       runPeriod(period),
       previous && runPeriod(previous).then(({ rows, totals }) => ({
@@ -810,7 +905,7 @@ function createAnalytics2(options) {
       if (key)
         cache = result ? "hit" : "miss";
       if (!result) {
-        result = await runQuery(prepared);
+        result = await runQuery(prepared, ctx);
         if (key)
           store(key, result, entry);
       }
@@ -858,6 +953,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))
   };
 }
@@ -978,7 +1074,18 @@ function restrictedFields(dataset) {
     if (!entry)
       return [];
     const own = entry.access === undefined ? [] : [entry.access];
-    return entry.kind === "ratio" ? [...own, ...accessOf(entry.numerator), ...accessOf(entry.denominator)] : own;
+    switch (entry.kind) {
+      case "ratio":
+        return [
+          ...own,
+          ...accessOf(entry.numerator),
+          ...accessOf(entry.denominator)
+        ];
+      case "resolved":
+        return [...own, ...entry.uses.flatMap(accessOf)];
+      default:
+        return own;
+    }
   };
   return [
     ...Object.keys(measures).map((key) => ({

package/dist/index-psw9s799.js

@@ -0,0 +1,46 @@
+import {
+  AnalyticsError2
+} from "./index-g0ah4ehn.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-g2mjqx4f.js → index-rgqsrd72.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) {
@@ -62,8 +62,19 @@ var measure2 = {
       numerator,
       denominator
     };
-  }
+  },
+  resolved
 };
+function resolved(options) {
+  return {
+    kind: "resolved",
+    result: options.result,
+    label: options.label,
+    description: options.description,
+    access: options.access,
+    uses: options.uses ?? []
+  };
+}
 function base(options) {
   return {
     label: options.label,
@@ -222,6 +233,15 @@ function validateDataset(dataset) {
     }
     if (entry.kind === "ratio")
       checkRatio(measures, key, [], fail);
+    if (entry.kind === "resolved") {
+      for (const used of entry.uses) {
+        const usedEntry = measures[used];
+        if (!usedEntry)
+          fail(`measure ${key} uses unknown measure ${used}`);
+        if (usedEntry?.kind === "resolved")
+          fail(`measure ${key} uses ${used}, which is resolved too`);
+      }
+    }
   }
   const dimensions = dataset.dimensions;
   for (const [key, entry] of Object.entries(dimensions)) {
@@ -266,6 +286,8 @@ function checkRatio(measures, key, path, fail) {
   const entry = measures[key];
   if (!entry)
     fail(`ratio measure ${path.at(-1)} names unknown measure ${key}`);
+  if (entry?.kind === "resolved")
+    fail(`ratio measure ${path.at(-1)} names ${key}, which is resolved`);
   if (entry?.kind !== "ratio")
     return;
   checkRatio(measures, entry.numerator, [...path, key], fail);

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { type AccessKey, type Analytics, type AnalyticsCache, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails, type AnalyticsErrorOf, type AnalyticsOptions, type AnalyticsQuery, type AnalyticsQueryEvent, type AnalyticsResult, type AnalyticsSource, createAnalytics, type DatasetCatalogEntry, type FieldKey, isAnalyticsError } from './analytics.js';
+export { type AccessKey, type Analytics, type AnalyticsCache, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails, type AnalyticsErrorOf, type AnalyticsOptions, type AnalyticsQuery, type AnalyticsQueryEvent, type AnalyticsResolvers, type AnalyticsResult, type AnalyticsSource, createAnalytics, type DatasetCatalogEntry, type FieldKey, isAnalyticsError, type MeasureResolver, type ResolvedKey, type ResolverInput, type ResolverOutput } from './analytics.js';
 export { CompileError, type CompiledStatement, type Dialect, type JoinClause, type SelectItem, type SelectStatement, type SqlRenderer, decodeNumber, renderStatement } from './compile.js';
-export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type DimensionValue, defineDataset, dimension, type MeasureValue, measure, type Ratio } from './dataset.js';
+export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type DimensionValue, defineDataset, dimension, type MeasureValue, measure, type Ratio, type ResolvedMeasure } from './dataset.js';
 export { and, caseWhen, coalesce, type ColumnKey, eq, Expr, type ExprNode, exists, gt, gte, inList, isNotNull, isNull, literal, lt, lte, minutesAgo, ne, not, or, type SqlType, Table, type TableRef, table, toText } from './expr.js';
 export { analyticsToolGuidance } from './guidance.js';
 export type { PeriodInput, PeriodPreset } from './period.js';
-export { allTenants, type Tenant, type TenantId } from './plan.js';
+export { allTenants, type NormalizedFilter, type Tenant, type TenantId } from './plan.js';
 export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf, type ResultPeriod } from './query.js';

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   AnalyticsError2,
   isAnalyticsError2,
   createAnalytics2
-} from "./index-zgb1e89d.js";
+} from "./index-g0ah4ehn.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -14,7 +14,7 @@ import {
   measure2,
   dimension2,
   defineDataset2
-} from "./index-g2mjqx4f.js";
+} from "./index-rgqsrd72.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>;