measurr 0.3.0 → 0.5.0

package/README.md

@@ -12,10 +12,12 @@ returns shaped, typed rows.
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
   refuses to run without a tenant. A caller can be scoped to one tenant or a list of them;
   platform admins can query every tenant only through an explicit `allTenants` value that no
-  query input can carry.
+  query input can carry. A dataset without tenants (staff work) is only for those admins.
+- Access per dataset and per field: a staff-only measure lives on the same dataset as the
+  measures everyone may use.
 - The query schema is generated with Zod, so it doubles as an LLM tool schema
   (`z.toJSONSchema`) and as the request validator. It can be built per caller, offering only
-  the datasets they may query.
+  the datasets and fields they may use.
 - No driver or ORM dependency. `zod` is a peer dependency.
 
 ## Quick start
@@ -51,6 +53,11 @@ export const orders = defineDataset({
 	measures: {
 		orders: measure.count({ label: 'Orders' }),
 		revenue: measure.sum(order.col('amount'), { label: 'Revenue' }),
+		// Only callers `authorizeField` allows for 'staff' see or query it.
+		margin: measure.sum(order.col('amount').sub(order.col('cost')), {
+			label: 'Margin',
+			access: 'staff'
+		}),
 		refunded: measure.countWhere(exists(refund, eq(refund.col('orderId'), order.col('id'))), {
 			label: 'Refunded orders'
 		}),
@@ -96,6 +103,7 @@ export const analytics = createAnalytics({
 	},
 	tenant: (ctx: Ctx) => ctx.organizationId,
 	authorize: (dataset, ctx) => ctx.can(`analytics:${dataset.key}`),
+	authorizeField: (dataset, key, access, ctx) => ctx.roles.includes(access),
 	timezone: (ctx) => ctx.timezone,
 	onQuery: (event, ctx) => metrics.record(event.dataset, event.durationMs, event.outcome)
 })
@@ -117,18 +125,38 @@ result.rows[0]?.paidShare // Ratio | null
 
 ## Callers and tools
 
-`authorize` is the one access rule. Everything that offers datasets goes through it:
+Three rules decide what a caller may use, and everything that offers datasets goes through
+them:
+
+- `authorize(dataset, ctx)` decides which datasets `ctx` may query (all when omitted).
+- `authorizeField(dataset, key, access, ctx)` decides which marked measures and dimensions it
+  may use. A field is marked with `access`, a string your app defines (`'staff'`); unmarked
+  fields are open to everyone who may query the dataset. The hook is called only for marked
+  fields, once per access key, and is required as soon as one field is marked
+  (`createAnalytics` throws otherwise). A `ratio` also needs the access of the measures it
+  divides, so a margin rate is as restricted as the margin. The hook's `access` is typed as the
+  union of the keys the datasets use (`AccessKey`) and `key` as their field keys (`FieldKey`),
+  so a new key such as `'finance'` fails an exhaustive `switch` in the hook until it is handled.
+- A dataset without a tenant column is only for a `ctx` whose `tenant(ctx)` is `allTenants`
+  (see below).
+
+With them:
 
 - `analytics.listDatasets(ctx)` resolves to the catalog entries (measures, dimensions, closed
-  values) of the datasets `ctx` may query.
-- `analytics.querySchema({ ctx })` resolves to the input schema for those datasets, for a tool
-  built per caller. It rejects with `AnalyticsError('forbidden')` when nothing is allowed.
+  values) of the datasets `ctx` may query, without the fields it may not use. A dataset with
+  no measure left for `ctx` is left out.
+- `analytics.querySchema({ ctx })` resolves to the input schema for the same datasets and
+  fields, for a tool built per caller, so a model is never offered what it may not use. It
+  rejects with `AnalyticsError('forbidden')` when nothing is allowed.
   `analytics.querySchema({ datasets })` is the synchronous form for a list you already have
-  (typed for those datasets only), and `querySchema()` covers every dataset. Schemas are built once per set of datasets, so
-  `querySchema({ ctx })` returns the same object as `querySchema({ datasets })` for the same
-  allowed set: cache a tool built from it by its dataset keys.
-- `analytics.query` checks `authorize` again on every call, so a schema offered too widely
-  still cannot leak a dataset.
+  (typed for those datasets only), and `querySchema()` covers every dataset and field. Schemas
+  are built once per set of datasets and fields, so `querySchema({ ctx })` returns the same
+  object as `querySchema({ datasets })` when `ctx` may use every field of the allowed set:
+  cache a tool built from it by the keys of what it offers.
+- `analytics.query` checks all three again on every call, so a schema offered too widely still
+  cannot leak a dataset or a field. Naming a field `ctx` may not use (as a measure, in
+  `groupBy` or `sort`, or in a filter) fails with `AnalyticsError('forbidden')`, which names
+  the field.
 
 `AnalyticsResultSchema` is any dataset's result without its keys: rows of `{ key, label }`
 per grouped dimension and a number or null per measure, with totals, `previous?`, `notes` and
@@ -148,9 +176,95 @@ ${analyticsToolGuidance}`
 ```
 
 `onQuery(event, ctx)` hears every `query` once it succeeds or fails:
-`{ dataset, durationMs, rows, outcome: 'success' | 'error', error? }`. `dataset` is null when
-the input named no known dataset, so free text from a model never becomes a metric label.
-What the hook throws or rejects with is swallowed; it cannot fail a query.
+`{ dataset, durationMs, rows, outcome: 'success' | 'error', cache?, error? }`. `dataset` is null
+when the input named no known dataset, so free text from a model never becomes a metric label.
+`cache` is `'hit'` or `'miss'` when a cache is configured. What the hook throws or rejects with is
+swallowed; it cannot fail a query.
+
+Each measure in `listDatasets` has a `valueType`: `count` (a whole number, never null),
+`ratio` (0-1, from `share` and `ratio`) or `number` (sums, averages, medians), so a UI knows
+to format a share as a percentage.
+
+## Caching
+
+`cache: { get, set }` keeps finished results in a store of your choice, such as Redis. A query
+is parsed and authorized first, so a cached result never reaches a caller who may not run the
+query. The key is `measurr:<dataset>:<sha256>`, hashed from the query with its defaults, the
+tenant scope, the timezone and the resolved days (so `last 30 days` moves on at local midnight).
+Results are plain JSON.
+
+```ts
+const TTL_SECONDS: Record<AnalyticsDatasetKey, number> = { orders: 300, units: 60 }
+
+createAnalytics({
+	// ...
+	cache: {
+		// A miss bypasses the cache; the fresh result is still stored.
+		get: async (key, { ctx }) =>
+			ctx.refresh ? null : JSON.parse((await redis.get(`${BUILD_ID}:${key}`)) ?? 'null'),
+		set: (key, result, { dataset }) =>
+			redis.setex(`${BUILD_ID}:${key}`, TTL_SECONDS[dataset], JSON.stringify(result))
+	}
+})
+```
+
+A stored value that is not a result of its dataset counts as a miss, and a cache that throws or
+rejects is a miss or a skipped write, never a failed query. A changed measure keeps its key, so
+prefix keys with a build id (as above) if old numbers must not outlive a deploy. A dataset that
+uses `minutesAgo` is as stale as the time to live.
+
+## Chart shapes
+
+`measurr/shapes` turns a result into what a chart or a KPI card draws. The functions are pure
+and add no numbers the result does not hold; with `compareToPrevious` they carry the previous
+period too.
+
+```ts
+import { toDistribution, toKpi, toPivot, toTimeseries, toLeaderboard } from 'measurr/shapes'
+
+toKpi(result, 'orders')
+// { kind: 'kpi', value: 12, previous: 8, change: 0.5 }
+
+toTimeseries(result, { bucket: 'day', unit: 'day', measure: 'orders', series: 'status' })
+// { kind: 'timeseries', unit, series: [{ key, label, points: [{ bucket: '2026-10-01', value }], previous? }] }
+
+toDistribution(result, { by: 'status', measure: 'orders' }) // segments with share of the total
+toPivot(result, { rows: 'weekday', columns: 'hour', measure: 'orders' }) // values[row][column]
+toLeaderboard(result, { by: 'region', measure: 'revenue' }) // ranked rows with every measure
+```
+
+- `toTimeseries` gives every bucket of the period a point; buckets without rows get `fill` (0 by
+  default, pass `null` for averages). An all-time result has only the buckets it found. The
+  previous period's points are on its own buckets; compare them by position.
+- A grouped query returns at most `limit` rows (20 by default, 100 at most), and the shape keeps
+  `truncated`. Set `limit: 100` for a series; 30 days split into three series fit, 90 days into
+  eleven do not.
+- `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).
+
+## Serving queries
+
+`measurr/handler` serves queries from any server framework:
+
+- `queryBatch(analytics, { total: q1, byStatus: q2 }, ctx)` runs named queries in parallel and
+  resolves to `{ results, errors }`, typed per name. One failing query does not fail the
+  others; an error other than `AnalyticsError` is reported as `{ code: 'internal' }` without
+  its message.
+- `streamBatch(analytics, queries, ctx)` yields `{ key, result }` or `{ key, error }` as each
+  query finishes, for a streaming endpoint.
+- `toHttpError(error)` maps an `AnalyticsError` to `{ status, code, message, data? }`:
+  `forbidden` is 403 `FORBIDDEN`, `missing_tenant` 401 `UNAUTHORIZED`, the rest 400
+  `BAD_REQUEST` with the code and details. The codes are the names oRPC and tRPC use:
+
+```ts
+try {
+	return await analytics.query(input, ctx)
+} catch (error) {
+	if (!(error instanceof AnalyticsError)) throw error
+	const { code, message, data } = toHttpError(error)
+	throw new ORPCError(code, { message, data })
+}
+```
 
 ## Tenants and platform admins
 
@@ -196,13 +310,33 @@ checking the session) before building `ctx`; never read it from the query input.
 lookups resolve labels across tenants, so `"Complaint"` matches every tenant's tag of that
 name.
 
+**Datasets without tenants.** Some tables belong to no organization, such as maintenance
+cases staff work on. Declare them with `tenantColumn: null`. The key stays required, so a
+forgotten tenant column still fails typecheck.
+
+```ts
+export const maintenance = defineDataset({
+	key: 'maintenance',
+	label: 'Maintenance',
+	description: 'One row per maintenance case.',
+	from: maintenanceCase,
+	tenantColumn: null,
+	// ...
+})
+```
+
+Only a `ctx` whose `tenant(ctx)` is `allTenants` may query such a dataset, label lookups
+included. An id or a list of ids, even an empty one, fails with `AnalyticsError('forbidden')`
+before any statement runs; a narrower scope is never ignored. `listDatasets(ctx)` and
+`querySchema({ ctx })` leave the dataset out for those callers.
+
 ## The model
 
 | Concept | What it is |
 | --- | --- |
-| Dataset | One fact table: tenant column, optional scope, time fields, default period, measures, dimensions, source. |
-| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). |
-| Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). |
+| Dataset | One fact table: tenant column (or `null`), optional scope, time fields, default period, measures, dimensions, source. |
+| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). Optionally restricted with `access`. |
+| Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). Optionally restricted with `access`. |
 | Query | `dataset`, 1-4 `measures`, 0-2 `groupBy`, `filters`, `period`, `time`, `compareToPrevious`, `sort` (by an asked measure or grouped dimension), `limit` (1-100, default 20). |
 | Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
 
@@ -344,12 +478,22 @@ It checks that every measure runs and returns a number or null, every grouping r
 groups add up to the total (except many-to-many), `isEmpty` plus `isNotEmpty` equals the total,
 open dimensions filter by label to their group's count, closed dimensions filter by value, an
 empty tenant and an empty tenant list see nothing (tenant isolation), and day buckets in a
-far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods.
+far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods. Fields marked
+with `access` are checked like any other.
+
+A dataset without a tenant column has no tenant rows to isolate. Pass `tenant: allTenants`,
+and the kit replaces the isolation checks with one that an empty tenant and an empty tenant
+list are refused with `forbidden`. Every other check runs as usual.
+
+```ts
+await assertDatasetContract({ dataset: maintenance, source, tenant: allTenants })
+```
 
 ## Extending
 
 - **A measure or dimension** is one entry in a dataset. Dimensions are groupable and
-  filterable unless `groupOnly` or `filterOnly` says otherwise. The contract kit covers it
+  filterable unless `groupOnly` or `filterOnly` says otherwise, and every field is open to
+  everyone who may query the dataset unless `access` restricts it. The contract kit covers it
   without a new test.
 - **A dataset** is one `defineDataset` call added to `createAnalytics({ datasets })`.
 - **A computed value** is written with the expression builders (`caseWhen`, `exists`,
@@ -362,15 +506,18 @@ far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods
 
 ## Stable API
 
-Kept stable for publishing: `createAnalytics` and its options, `allTenants`, `analytics.query`,
-`explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
-`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod`),
-`measure.*`, `dimension.*`, `table` / `Table`, the expression builders; the `Dialect`,
-`SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
-`assertDatasetContract`; and the types `AnalyticsQuery`, `AnalyticsResult`, `ResultPeriod`,
-`PeriodInput`, `Tenant`, `TenantId`, `Ratio`, `AnalyticsError` codes and their details
-(`isAnalyticsError`). `ExprNode` and `SelectStatement` are
-exported for dialect authors and may grow new node kinds.
+Kept stable for publishing: `createAnalytics` and its options (with `authorize`,
+`authorizeField` and `cache`), `allTenants`, `analytics.query`, `explain`, `querySchema`,
+`resultSchema`, `listDatasets`; `AnalyticsResultSchema`, `analyticsToolGuidance`,
+`AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod` and `tenantColumn: null`),
+`measure.*` and `dimension.*` (with `access`), `table` / `Table`, the expression builders; the
+`Dialect`, `SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`,
+`checkDatasetContract` / `assertDatasetContract`; `measurr/shapes` (`toKpi`, `toTimeseries`,
+`toDistribution`, `toPivot`, `toLeaderboard`) and `measurr/handler` (`queryBatch`,
+`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.
 
 ## Install
 

package/dist/analytics.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { CompiledStatement, Dialect } from './compile.js';
-import type { AnyDataset, AnyDimension } from './dataset.js';
+import type { AnyDataset, AnyDimension, Dataset } from './dataset.js';
 import { type Tenant } from './plan.js';
 import { type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
 export type Row = Record<string, unknown>;
@@ -50,9 +50,15 @@ export type AnalyticsQueryEvent = {
     /** Rows returned; 0 on error. */
     rows: number;
     outcome: 'success' | 'error';
+    /** Whether `cache` answered the query; absent without a cache or when it never got that far. */
+    cache?: 'hit' | 'miss';
     /** What the query threw, on error. */
     error?: unknown;
 };
+/** The measure and dimension keys of a dataset (of any dataset, for a union). */
+export type FieldKey<D> = D extends Dataset<string, infer M, infer Dm> ? keyof (M & Dm) & string : never;
+/** The access keys a dataset's measures and dimensions are marked with. */
+export type AccessKey<D> = D extends Dataset<string, infer M, infer Dm> ? NonNullable<(M & Dm)[keyof (M & Dm)]['access']> : never;
 export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
     datasets: DS;
     /** Databases by name; a dataset's `source` picks one, or the only one is used. */
@@ -69,6 +75,14 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
      * `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every query.
      */
     authorize?: ((dataset: DS[number], ctx: Ctx) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Whether `ctx` may use the measure or dimension `key` of `dataset`, which is marked with
+     * `access`. Called only for marked fields, once per access key: a ratio also needs the
+     * access of the measures it divides. Required when any field is marked. It decides which
+     * fields `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every
+     * query. `access` is the union of the keys the datasets use, so a new key shows up here.
+     */
+    authorizeField?: ((dataset: DS[number], key: FieldKey<DS[number]>, access: AccessKey<DS[number]>, ctx: Ctx) => boolean | Promise<boolean>) | undefined;
     /** IANA timezone periods and time buckets resolve in. UTC when omitted. */
     timezone?: ((ctx: Ctx) => string | null | undefined | Promise<string | null | undefined>) | undefined;
     /** The clock periods and `minutesAgo` resolve against. */
@@ -78,6 +92,33 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
      * throws or rejects with is swallowed, so it can never fail a query.
      */
     onQuery?: ((event: AnalyticsQueryEvent, ctx: Ctx) => unknown) | undefined;
+    /**
+     * Where finished results are kept and looked up. What it throws or rejects with is
+     * swallowed: a failing cache is a miss, never a failed query.
+     */
+    cache?: AnalyticsCache<Ctx, DS[number]['key']> | undefined;
+};
+/**
+ * A store for finished results, such as Redis. Keys name the dataset and hash everything that
+ * decides the result: the query with its defaults, the tenant scope, the timezone and the
+ * resolved days. A query is parsed and authorized before the cache is asked, so a cached result
+ * never reaches a caller who may not run the query. Results are plain JSON.
+ */
+export type AnalyticsCache<Ctx, Key extends string = string> = {
+    /**
+     * The stored result, or null/undefined for a miss. Return a miss to bypass the cache for a
+     * caller (a refresh button); its fresh result is still stored. A stored value that is not a
+     * result of this dataset counts as a miss, so a changed definition does not break queries.
+     */
+    get(key: string, entry: {
+        dataset: Key;
+        ctx: Ctx;
+    }): unknown;
+    /** Stores a result; pick the time to live per `dataset`. */
+    set(key: string, result: QueryResult<Row, Row>, entry: {
+        dataset: Key;
+        ctx: Ctx;
+    }): unknown;
 };
 export type DatasetCatalogEntry<Key extends string = string> = {
     key: Key;
@@ -91,6 +132,8 @@ export type DatasetCatalogEntry<Key extends string = string> = {
         key: string;
         label: string;
         description: string | undefined;
+        /** `count`: a whole number, never null. `ratio`: 0-1 (`share`, `ratio`). `number`: the rest. */
+        valueType: 'count' | 'number' | 'ratio';
     }[];
     dimensions: {
         key: string;
@@ -123,15 +166,15 @@ export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
         key: K;
     }>>>;
     /**
-     * The input schema for the datasets `authorize` allows `ctx`, for a tool built per caller.
-     * Rejects with `forbidden` when none are allowed.
+     * The input schema for the datasets `ctx` may query, without the fields `authorizeField`
+     * refuses it, for a tool built per caller. Rejects with `forbidden` when none are allowed.
      */
     querySchema(options: {
         ctx: Ctx;
     }): Promise<z.ZodType<DatasetQuery<DS[number]>>>;
     /** The result schema for one dataset. */
     resultSchema(dataset: DS[number]['key']): z.ZodType<QueryResult<Row, Row>>;
-    /** The datasets `authorize` allows `ctx`, with their measures and dimensions. */
+    /** The datasets `ctx` may query, with the measures and dimensions it may use. */
     listDatasets(ctx: Ctx): Promise<DatasetCatalogEntry<DS[number]['key']>[]>;
 };
 export type AnalyticsQuery<A> = A extends Analytics<infer DS, never> ? DatasetQuery<DS[number]> : never;

package/dist/dataset.d.ts

@@ -5,9 +5,19 @@ declare const ratioBrand: unique symbol;
 export type Ratio = number & {
     readonly [ratioBrand]: 'zeroToOne';
 };
-type Described = {
+type Described<Access extends string = string> = {
     label: string;
     description?: string | undefined;
+    /**
+     * Restricts the field to callers `authorizeField` allows for this access key (a string the
+     * app defines, such as `'staff'`). Unmarked fields are open to everyone who may query the
+     * dataset.
+     */
+    access?: Access | undefined;
+};
+/** Keeps a field's access key literal, so `authorizeField` is typed with the keys in use. */
+export type Marked<Access extends string> = {
+    readonly access: Access | undefined;
 };
 /**
  * `count` results are never null. `number` results (sum, avg, median) are null for an empty
@@ -19,6 +29,7 @@ export type AggregateMeasure<R extends 'count' | 'number' = 'count' | 'number'>
     readonly result: R;
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly node: Extract<ExprNode, {
         kind: 'aggregate';
     }>;
@@ -28,6 +39,7 @@ export type ShareMeasure = {
     readonly result: 'ratio';
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly numerator: ExprNode;
     readonly denominator: ExprNode | null;
 };
@@ -36,6 +48,8 @@ export type RatioMeasure<A extends string = string, B extends string = string> =
     readonly result: 'ratio';
     readonly label: string;
     readonly description: string | undefined;
+    /** A ratio also needs the access of the measures it divides. */
+    readonly access: string | undefined;
     readonly numerator: A;
     readonly denominator: B;
 };
@@ -46,32 +60,32 @@ export type MeasureValue<M> = M extends {
 } ? number : M extends {
     result: 'number';
 } ? number | null : Ratio | null;
-type Filtered = Described & {
+type Filtered<Access extends string> = Described<Access> & {
     where?: Expr<'boolean'> | undefined;
 };
 export declare const measure: {
     /** Number of rows, optionally only those matching `where`. */
-    count(options: Filtered): AggregateMeasure<'count'>;
+    count<Access extends string = never>(options: Filtered<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
     /** Number of rows matching `condition`. */
-    countWhere(condition: Expr<'boolean'>, options: Described): AggregateMeasure<'count'>;
+    countWhere<Access extends string = never>(condition: Expr<'boolean'>, options: Described<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
     /** Number of distinct non-null values of `expr`. */
-    countDistinct(expr: Expr<SqlType>, options: Filtered): AggregateMeasure<'count'>;
-    sum(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
-    avg(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
-    median(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
+    countDistinct<Access extends string = never>(expr: Expr<SqlType>, options: Filtered<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
+    sum<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
+    avg<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
+    median<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
     /**
      * The share of rows matching `numerator` among rows matching `denominator` (all rows when
      * omitted). A `Ratio` from 0 to 1.
      */
-    share(options: Described & {
+    share<Access extends string = never>(options: Described<Access> & {
         numerator: Expr<'boolean'>;
         denominator?: Expr<'boolean'> | undefined;
-    }): ShareMeasure;
+    }): ShareMeasure & Marked<NoInfer<Access>>;
     /**
      * One measure of this dataset over another, computed after aggregation. Both keys must be
      * measures of the same dataset; `defineDataset` checks them.
      */
-    ratio<const A extends string, const B extends string>(numerator: A, denominator: B, options: Described): RatioMeasure<A, B>;
+    ratio<const A extends string, const B extends string, Access extends string = never>(numerator: A, denominator: B, options: Described<Access>): RatioMeasure<A, B> & Marked<NoInfer<Access>>;
 };
 /**
  * How a dimension filters:
@@ -82,22 +96,22 @@ export declare const measure: {
  * - `time`: time buckets keyed by ISO date - `between`, `isEmpty`, `isNotEmpty`.
  */
 export type DimensionCategory = 'closed' | 'open' | 'numeric' | 'time';
-type DimensionOptions<G extends boolean = boolean, F extends boolean = boolean> = Described & {
+type DimensionOptions<G extends boolean = boolean, F extends boolean = boolean, Access extends string = string> = Described<Access> & {
     /** Only offered for grouping. */
     groupOnly?: G | undefined;
     /** Only offered for filtering. */
     filterOnly?: F | undefined;
 };
 /** Time dimensions name themselves after their unit unless given a label. */
-type TimeDimensionOptions<G extends boolean, F extends boolean, Key> = Omit<DimensionOptions<G, F>, 'label'> & {
+type TimeDimensionOptions<G extends boolean, F extends boolean, Key, Access extends string> = Omit<DimensionOptions<G, F, Access>, 'label'> & {
     label?: string | undefined;
     labelFor?: ((key: Key) => string) | undefined;
 };
 /**
  * `groupOnly: true` makes `filterable` the literal `false` (and `filterOnly`, `groupable`), so
- * queries cannot filter or group by what the dimension does not offer.
+ * queries cannot filter or group by what the dimension does not offer. `access` stays literal.
  */
-export type DimensionAccess<G extends boolean, F extends boolean> = {
+export type DimensionAccess<G extends boolean, F extends boolean, Access extends string = never> = Marked<Access> & {
     readonly groupable: [F] extends [true] ? false : boolean;
     readonly filterable: [G] extends [true] ? false : boolean;
 };
@@ -105,6 +119,7 @@ type DimensionBase<C extends DimensionCategory, Key> = {
     readonly category: C;
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly groupable: boolean;
     readonly filterable: boolean;
     /** Phantom: the key type in result rows. */
@@ -187,29 +202,29 @@ export declare const dimension: {
      * every value, so adding an enum value fails typecheck until it has a label, and a column
      * typed with values outside `values` fails too. A nullable column gives null keys.
      */
-    enum<const E extends Record<string, string>, V extends string | null, G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'string', V> & CoversValues<V, E[keyof E]>, values: E, options: DimensionOptions<G, F> & EmptyOption & {
+    enum<const E extends Record<string, string>, V extends string | null, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(expr: Expr<'string', V> & CoversValues<V, E[keyof E]>, values: E, options: DimensionOptions<G, F, Access> & EmptyOption & {
         labels: Record<E[keyof E], string>;
-    }): EnumDimension<E[keyof E], EmptyOf<V>> & DimensionAccess<G, F>;
+    }): EnumDimension<E[keyof E], EmptyOf<V>> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A value computed from other columns with the expression builders, usually `caseWhen`.
      * `values` lists every value the expression can produce, with its label; a plain value of
      * the expression missing from `values` fails typecheck. A `caseWhen` without `otherwise`
      * gives null keys.
      */
-    computed<V extends string | null, const K extends string, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & EmptyOption & {
+    computed<V extends string | null, const K extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & EmptyOption & {
         expr: Expr<'string', V> & CoversValues<V, NoInfer<K>>;
         values: Record<K, string>;
-    }): EnumDimension<K, EmptyOf<V>> & DimensionAccess<G, F>;
+    }): EnumDimension<K, EmptyOf<V>> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A to-one relation such as a team. The key type comes from the `key` column, so a branded
      * id column types the key in filters and rows. Rows without a related record get the
      * `empty` label and a null key.
      */
-    relation<Key extends string | number, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+    relation<Key extends string | number, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & {
         key: Expr<Key extends number ? 'number' : 'string', Key | null>;
         name: Expr<'string'>;
         empty?: string | undefined;
-    }): RelationDimension<Key> & DimensionAccess<G, F>;
+    }): RelationDimension<Key> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A to-many relation through a link table, such as tags. Grouping counts a row once per
      * related value, so totals for such a grouping come from a separate query. Filtering
@@ -218,7 +233,7 @@ export declare const dimension: {
      * `through.table` is the link table as a standalone `table()` (further joins hang off it),
      * and `through.on` links it to the dataset's table.
      */
-    manyToMany<Row = unknown, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+    manyToMany<Row = unknown, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & {
         through: {
             table: Table<Row>;
             on: Expr<'boolean'>;
@@ -228,15 +243,15 @@ export declare const dimension: {
         /** Explains the overlap to the reader of a grouped result. */
         note?: string | undefined;
         empty?: string | undefined;
-    }): ManyToManyDimension & DimensionAccess<G, F>;
+    }): ManyToManyDimension & DimensionAccess<G, F, NoInfer<Access>>;
     /** A numeric column, grouped by its exact values and filtered with `between`. */
-    number<G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'number'>, options: DimensionOptions<G, F> & {
+    number<G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(expr: Expr<'number'>, options: DimensionOptions<G, F, Access> & {
         labelFor?: ((key: number) => string) | undefined;
-    }): NumberDimension & DimensionAccess<G, F>;
+    }): NumberDimension & DimensionAccess<G, F, NoInfer<Access>>;
     /** Day, ISO week (starting Monday) or month of a time field, in the tenant's timezone. */
-    timeBucket<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, unit: TimeBucketUnit, options?: TimeDimensionOptions<G, F, string>): TimeBucketDimension<T> & DimensionAccess<G, F>;
+    timeBucket<const T extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(time: T, unit: TimeBucketUnit, options?: TimeDimensionOptions<G, F, string, Access>): TimeBucketDimension<T> & DimensionAccess<G, F, NoInfer<Access>>;
     /** ISO weekday (1 = Monday) or hour (0-23) of a time field, in the tenant's timezone. */
-    timePart<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, part: TimePartName, options?: TimeDimensionOptions<G, F, number>): TimePartDimension<T> & DimensionAccess<G, F>;
+    timePart<const T extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(time: T, part: TimePartName, options?: TimeDimensionOptions<G, F, number, Access>): TimePartDimension<T> & DimensionAccess<G, F, NoInfer<Access>>;
 };
 export type TimeField = {
     readonly column: ExprNode;
@@ -248,7 +263,8 @@ export type Dataset<K extends string = string, M extends Record<string, AnyMeasu
     readonly description: string;
     readonly from: TableRef;
     readonly source: string | undefined;
-    readonly tenantColumn: ExprNode;
+    /** Null for a dataset without tenants, which only `allTenants` may query. */
+    readonly tenantColumn: ExprNode | null;
     readonly scope: ExprNode | null;
     readonly time: Readonly<Record<T, TimeField>>;
     readonly defaultTime: T;
@@ -285,8 +301,12 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
     };
     /** Which source (database) the dataset runs on; the default when there is one source. */
     source?: string | undefined;
-    /** The column every query is filtered by; the value comes from `tenant(ctx)`. */
-    tenantColumn: Expr<SqlType>;
+    /**
+     * The column every query is filtered by; the value comes from `tenant(ctx)`. `null` for a
+     * dataset whose rows belong to no tenant (staff work, platform-wide records): only a caller
+     * whose `tenant(ctx)` is `allTenants` may query it, and everyone else is refused.
+     */
+    tenantColumn: Expr<SqlType> | null;
     /** Always applied, for example excluding test rows. */
     scope?: Expr<'boolean'> | undefined;
     time: Record<T, {

package/dist/handler.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Serving queries from any server framework: several queries in one request (all at once or
+ * as each finishes), and engine errors as HTTP errors. Framework-neutral; an oRPC or tRPC
+ * procedure wraps these in a few lines.
+ */
+import { type Analytics, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails } from './analytics.js';
+import type { AnyDataset } from './dataset.js';
+import type { DatasetQuery, ResultOf } from './query.js';
+/** Why one query of a batch failed. Errors other than `AnalyticsError` are not described. */
+export type BatchError = {
+    code: AnalyticsErrorCode | 'internal';
+    message: string;
+};
+export type BatchResult<DS extends readonly AnyDataset[], Q> = {
+    results: {
+        [K in keyof Q]?: ResultOf<DS[number], Q[K]>;
+    };
+    errors: {
+        [K in keyof Q]?: BatchError;
+    };
+};
+export type BatchChunk<DS extends readonly AnyDataset[], Q> = {
+    [K in keyof Q & string]: {
+        key: K;
+        result: ResultOf<DS[number], Q[K]>;
+    } | {
+        key: K;
+        error: BatchError;
+    };
+}[keyof Q & string];
+type Queries<DS extends readonly AnyDataset[]> = Record<string, DatasetQuery<DS[number]>>;
+/**
+ * Runs named queries in parallel. One query failing does not fail the others: its error is
+ * under its name. Each query is authorized, cached and reported like a single `query`.
+ */
+export declare function queryBatch<DS extends readonly AnyDataset[], Ctx, const Q extends Queries<DS>>(analytics: Analytics<DS, Ctx>, queries: Q, ctx: Ctx): Promise<BatchResult<DS, Q>>;
+/** Runs named queries in parallel and yields each as it finishes, for a streaming endpoint. */
+export declare function streamBatch<DS extends readonly AnyDataset[], Ctx, const Q extends Queries<DS>>(analytics: Analytics<DS, Ctx>, queries: Q, ctx: Ctx): AsyncGenerator<BatchChunk<DS, Q>, void, undefined>;
+export type HttpError = {
+    status: 400 | 401 | 403;
+    /** The status name oRPC and tRPC use for it. */
+    code: 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN';
+    message: string;
+    /** For a bad request: the engine's code and details, so a model can fix its query. */
+    data?: {
+        code: AnalyticsErrorCode;
+        details: AnalyticsErrorDetails[AnalyticsErrorCode];
+    };
+};
+/**
+ * An engine error as an HTTP error: `forbidden` is 403, `missing_tenant` 401, the rest are
+ * 400 with the code and details. Messages are safe to show; for `unknown_value` they list the
+ * valid values.
+ */
+export declare function toHttpError(error: AnalyticsError): HttpError;
+export {};