measurr 0.2.0 → 0.4.0

package/dist/testing.d.ts

@@ -6,6 +6,7 @@
 import { type AnalyticsSource } from './analytics.js';
 import { type AnyDataset } from './dataset.js';
 import type { PeriodInput } from './period.js';
+import { type TenantId, allTenants } from './plan.js';
 export type ContractCheck = {
     name: string;
     ok: boolean;
@@ -18,8 +19,11 @@ export type ContractReport = {
 export type ContractOptions = {
     dataset: AnyDataset;
     source: AnalyticsSource;
-    /** A tenant with seeded rows in the period. */
-    tenant: string | number;
+    /**
+     * A tenant with seeded rows in the period. `allTenants` for a dataset without a tenant
+     * column, which no single tenant may query.
+     */
+    tenant: TenantId | typeof allTenants;
     /** A tenant with no rows; defaults to a sentinel that no real tenant uses. */
     emptyTenant?: string | number;
     /** A timezone far from UTC makes bucketing mistakes visible. Defaults to Pacific/Auckland. */
@@ -30,8 +34,9 @@ export type ContractOptions = {
 };
 /**
  * Checks that every measure, grouping and filter compiles and runs, that groups add up to the
- * total, that labels resolve, that another tenant's rows never count, and that day buckets
- * agree with periods in the timezone.
+ * total, that labels resolve, that another tenant's rows never count (or, for a dataset
+ * without a tenant column, that a scoped caller is refused), and that day buckets agree with
+ * periods in the timezone. Fields marked with `access` are checked like any other.
  */
 export declare function checkDatasetContract(options: ContractOptions): Promise<ContractReport>;
 /** Runs `checkDatasetContract` and throws with every failed check listed. */

package/dist/testing.js

@@ -1,9 +1,11 @@
 import {
   MAX_MEASURES,
+  allTenants2,
+  isAnalyticsError2,
   createAnalytics2,
   measure2,
   dimension2
-} from "./index-dj3369zz.js";
+} from "./index-4rmjas9h.js";
 
 // src/testing.ts
 var COUNT = "__contractCount";
@@ -31,6 +33,7 @@ async function checkDatasetContract(options) {
     datasets: [probe],
     sources: { main: options.source },
     tenant: (ctx) => ctx.tenant,
+    authorizeField: () => true,
     timezone: () => timezone,
     ...options.now && { now: options.now }
   });
@@ -55,10 +58,11 @@ async function checkDatasetContract(options) {
   };
   const total = (await run({ measures: [COUNT] })).totals[COUNT] ?? 0;
   if (total === 0) {
+    const scope = options.tenant === allTenants2 ? "The dataset" : `Tenant ${options.tenant}`;
     checks.push({
       name: "seeded rows",
       ok: false,
-      message: `Tenant ${options.tenant} has no rows in the period; the checks below prove little`
+      message: `${scope} has no rows in the period; the checks below prove little`
     });
   }
   for (const key of Object.keys(dataset.measures)) {
@@ -128,26 +132,35 @@ async function checkDatasetContract(options) {
       });
     }
   }
-  await check("tenant isolation", async () => {
-    const measures = Object.keys(probe.measures);
-    const leaked = [];
-    for (let start = 0;start < measures.length; start += MAX_MEASURES) {
-      const batch = measures.slice(start, start + MAX_MEASURES);
-      const other = await run({ measures: batch }, emptyTenant);
-      leaked.push(...Object.entries(other.totals).filter(([, value]) => value !== 0 && value !== null));
-    }
-    if (leaked.length > 0) {
-      return `an empty tenant sees ${leaked.map(([key, value]) => `${key}=${value}`).join(", ")}`;
-    }
-    for (const [key, entry] of dimensions) {
-      if (!entry.groupable)
-        continue;
-      const grouped = await run({ measures: [COUNT], groupBy: [key] }, emptyTenant);
-      if (grouped.rows.length > 0)
-        return `an empty tenant sees ${grouped.rows.length} ${key} groups`;
-    }
-    return;
-  });
+  for (const [name, tenant] of [
+    ["an empty tenant", emptyTenant],
+    ["an empty tenant list", []]
+  ]) {
+    await check(`tenant isolation: ${name}`, async () => {
+      if (!dataset.tenantColumn) {
+        const refused = await run({ measures: [COUNT] }, tenant).then(() => false, (error) => isAnalyticsError2(error, "forbidden"));
+        return refused ? undefined : `${name} may query a dataset without a tenant column`;
+      }
+      const measures = Object.keys(probe.measures);
+      const leaked = [];
+      for (let start = 0;start < measures.length; start += MAX_MEASURES) {
+        const batch = measures.slice(start, start + MAX_MEASURES);
+        const result = await run({ measures: batch }, tenant);
+        leaked.push(...Object.entries(result.totals).filter(([, value]) => value !== 0 && value !== null));
+      }
+      if (leaked.length > 0) {
+        return `${name} sees ${leaked.map(([key, value]) => `${key}=${value}`).join(", ")}`;
+      }
+      for (const [key, entry] of dimensions) {
+        if (!entry.groupable)
+          continue;
+        const grouped = await run({ measures: [COUNT], groupBy: [key] }, tenant);
+        if (grouped.rows.length > 0)
+          return `${name} sees ${grouped.rows.length} ${key} groups`;
+      }
+      return;
+    });
+  }
   for (const time of Object.keys(dataset.time)) {
     await check(`day buckets of ${time} in ${timezone}`, async () => {
       const days = await run({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "measurr",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "A small typed semantic layer: datasets of measures and dimensions compiled to one SQL statement per dialect.",
 	"type": "module",
 	"module": "./dist/index.js",

package/src/analytics.ts

@@ -1,11 +1,17 @@
 import { z } from 'zod'
 import type { CompiledStatement, Dialect, SelectStatement } from './compile.js'
-import type { AnyDataset, AnyDimension } from './dataset.js'
+import type {
+	AnyDataset,
+	AnyDimension,
+	AnyMeasure,
+	Dataset
+} from './dataset.js'
 import {
 	type NormalizedQuery,
 	type ParsedQuery,
 	type PlanContext,
 	type Tenant,
+	type TenantId,
 	allTenants,
 	normalizeQuery,
 	planLookup,
@@ -110,14 +116,25 @@ export type AnalyticsQueryEvent = {
 	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. */
 	sources: Record<string, AnalyticsSource>
 	/**
-	 * The tenant every query is scoped to. Queries without one (null, undefined, '') are
-	 * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
-	 * every tenant's rows.
+	 * The tenant every query is scoped to, or a list of them (an empty list matches no rows).
+	 * Queries without one (null, undefined, '', a list holding one of those) are refused.
+	 * Return `allTenants` to drop the tenant filter, only for callers allowed to see every
+	 * tenant's rows.
 	 */
 	tenant: (ctx: Ctx) => Tenant | null | undefined
 	/**
@@ -127,6 +144,21 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
 	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?:
 		| ((
@@ -181,15 +213,15 @@ export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
 		datasets?: readonly K[] | undefined
 	}): z.ZodType<DatasetQuery<Extract<DS[number], { 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']>[]>
 }
 
@@ -201,13 +233,21 @@ export type AnalyticsResult<A, Q> =
 
 type ShapedResult = QueryResult<Row, Row>
 
+/** A measure or dimension marked with `access`, with every access key it needs. */
+type RestrictedField = {
+	kind: 'measure' | 'dimension'
+	key: string
+	access: readonly string[]
+}
+
 /** A parsed, authorized query with everything the hooks decide resolved. */
 type Prepared = {
 	dataset: AnyDataset
 	query: NormalizedQuery
 	tenant: Tenant
 	timezone: string
-	period: ResolvedPeriod
+	/** Null for all time. */
+	period: ResolvedPeriod | null
 	previous: ResolvedPeriod | null
 	now: Date
 }
@@ -219,6 +259,7 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 	const sourceNames = Object.keys(options.sources)
 	const byKey = new Map<string, AnyDataset>()
 	const sourceOf = new Map<string, AnalyticsSource>()
+	const restrictedOf = new Map<string, RestrictedField[]>()
 
 	for (const dataset of datasets) {
 		if (byKey.has(dataset.key))
@@ -228,6 +269,14 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 		const source = resolveSource(dataset, options.sources, sourceNames)
 		sourceOf.set(dataset.key, source)
 		compileEverything(dataset, source.dialect)
+
+		const restricted = restrictedFields(dataset)
+		if (restricted.length > 0 && !options.authorizeField) {
+			throw new Error(
+				`Dataset ${dataset.key} marks fields with access, but createAnalytics has no authorizeField`
+			)
+		}
+		restrictedOf.set(dataset.key, restricted)
 	}
 
 	const now = options.now ?? (() => new Date())
@@ -247,12 +296,18 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 		return source
 	}
 
-	const querySchemaFor = (keys: readonly string[] | undefined) => {
-		const selected = keys ? keys.map(datasetOf) : datasets
-		const selectionKey = selected
-			.map((dataset) => dataset.key)
-			.sort()
-			.join(',')
+	/** One schema per set of datasets (or views of them without some fields). */
+	const querySchemaFor = (selected: readonly AnyDataset[]) => {
+		const keyOf = (dataset: AnyDataset) => {
+			if (byKey.get(dataset.key) === dataset) return dataset.key
+
+			const fields = [
+				...Object.keys(dataset.measures),
+				...Object.keys(dataset.dimensions)
+			]
+			return `${dataset.key}(${fields.join(' ')})`
+		}
+		const selectionKey = selected.map(keyOf).sort().join(',')
 
 		let schema = querySchemas.get(selectionKey)
 		if (!schema) {
@@ -271,14 +326,54 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 		return schema
 	}
 
-	const allowedDatasets = async (ctx: Ctx) => {
-		const { authorize } = options
-		if (!authorize) return datasets
+	/** The marked fields of `dataset` that `ctx` may not use. */
+	const deniedFields = async (
+		dataset: AnyDataset,
+		ctx: Ctx
+	): Promise<RestrictedField[]> => {
+		const restricted = restrictedOf.get(dataset.key) ?? []
+		// Keys and access marks are read from the datasets themselves, so they fit the hook.
+		const authorizeField = options.authorizeField as
+			| ((
+					dataset: AnyDataset,
+					key: string,
+					access: string,
+					ctx: Ctx
+			  ) => boolean | Promise<boolean>)
+			| undefined
+		// createAnalytics refuses marked fields without the hook; deny them all regardless.
+		if (restricted.length === 0 || !authorizeField) return restricted
+
+		const mayUse = async (field: RestrictedField) => {
+			const answers = await Promise.all(
+				field.access.map((access) =>
+					authorizeField(dataset, field.key, access, ctx)
+				)
+			)
+			return answers.every(Boolean)
+		}
 
-		const allowed = await Promise.all(
-			datasets.map((dataset) => authorize(dataset, ctx))
+		const allowed = await Promise.all(restricted.map(mayUse))
+		return restricted.filter((_, index) => !allowed[index])
+	}
+
+	/**
+	 * The datasets `ctx` may query, each without the fields it may not use. A dataset without
+	 * a tenant column needs `allTenants`, and one without a usable measure is left out.
+	 */
+	const allowedDatasets = async (ctx: Ctx): Promise<AnyDataset[]> => {
+		const everyTenant = options.tenant(ctx) === allTenants
+		const views = await Promise.all(
+			datasets.map(async (dataset) => {
+				if (!dataset.tenantColumn && !everyTenant) return null
+				if (options.authorize && !(await options.authorize(dataset, ctx)))
+					return null
+
+				const view = withoutFields(dataset, await deniedFields(dataset, ctx))
+				return Object.keys(view.measures).length > 0 ? view : null
+			})
 		)
-		return datasets.filter((_, index) => allowed[index])
+		return views.filter((view) => view !== null)
 	}
 
 	const querySchemaForCtx = async (ctx: Ctx) => {
@@ -286,12 +381,12 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 		if (allowed.length === 0) {
 			throw new AnalyticsError('forbidden', 'No dataset is allowed')
 		}
-		return querySchemaFor(allowed.map((dataset) => dataset.key))
+		return querySchemaFor(allowed)
 	}
 
 	/** Parse, authorize, and resolve everything that comes from hooks. */
 	const prepare = async (input: unknown, ctx: Ctx): Promise<Prepared> => {
-		const parsed = querySchemaFor(undefined).safeParse(input)
+		const parsed = querySchemaFor(datasets).safeParse(input)
 		if (!parsed.success) {
 			throw new AnalyticsError(
 				'invalid_query',
@@ -300,7 +395,8 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			)
 		}
 
-		const dataset = datasetOf((parsed.data as ParsedQuery).dataset)
+		const parsedQuery = parsed.data as ParsedQuery
+		const dataset = datasetOf(parsedQuery.dataset)
 		if (options.authorize && !(await options.authorize(dataset, ctx))) {
 			throw new AnalyticsError(
 				'forbidden',
@@ -308,6 +404,24 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			)
 		}
 
+		// Sorting names only asked measures and grouped dimensions, so these cover it.
+		const dimensionsUsed = [
+			...(parsedQuery.groupBy ?? []),
+			...(parsedQuery.filters ?? []).map((filter) => filter.dimension)
+		]
+		const refused = (await deniedFields(dataset, ctx)).filter((field) =>
+			field.kind === 'measure'
+				? parsedQuery.measures.includes(field.key)
+				: dimensionsUsed.includes(field.key)
+		)
+		if (refused.length > 0) {
+			const names = refused.map((field) => `${field.kind} ${field.key}`)
+			throw new AnalyticsError(
+				'forbidden',
+				`Not allowed to use ${names.join(', ')} of ${dataset.key}`
+			)
+		}
+
 		const tenant: unknown = options.tenant(ctx)
 		if (!isTenant(tenant)) {
 			throw new AnalyticsError(
@@ -315,6 +429,13 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 				'Refusing to query without a tenant'
 			)
 		}
+		// Never drop a narrower scope: rows without a tenant are only for every-tenant callers.
+		if (!dataset.tenantColumn && tenant !== allTenants) {
+			throw new AnalyticsError(
+				'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)) {
@@ -324,18 +445,21 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			)
 		}
 
-		const query = normalizeQuery(dataset, parsed.data as ParsedQuery)
+		const query = normalizeQuery(dataset, parsedQuery)
 		const at = now()
-		let period: ResolvedPeriod
+		let period: ResolvedPeriod | null
 		try {
-			period = resolvePeriod(query.period, timezone, at)
+			period =
+				'all' in query.period ? null : resolvePeriod(query.period, timezone, at)
 		} catch (error) {
 			if (error instanceof PeriodError) {
 				throw new AnalyticsError('invalid_period', error.message)
 			}
 			throw error
 		}
-		const previous = query.compareToPrevious ? previousPeriod(period) : null
+		// The schema refuses compareToPrevious with an all-time period.
+		const previous =
+			query.compareToPrevious && period ? previousPeriod(period) : null
 
 		return { dataset, query, tenant, timezone, period, previous, now: at }
 	}
@@ -357,7 +481,7 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			dialect
 		)
 
-		const runPeriod = async (target: ResolvedPeriod) => {
+		const runPeriod = async (target: ResolvedPeriod | null) => {
 			const statements = periodStatements(dataset, query, {
 				tenant,
 				timezone,
@@ -373,27 +497,26 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect)
 			const totalsRow = (rawTotals ?? rawRows)[0] ?? {}
 			const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect)
-			const periodOut = { from: target.from, to: target.to, timezone }
 
-			return { period: periodOut, rows, totals, truncated }
+			return { rows, totals, truncated }
 		}
 
+		const range = ({ from, to }: ResolvedPeriod) => ({ from, to, timezone })
 		const [current, before] = await Promise.all([
 			runPeriod(period),
-			previous ? runPeriod(previous) : null
+			previous &&
+				runPeriod(previous).then(({ rows, totals }) => ({
+					period: range(previous),
+					rows,
+					totals
+				}))
 		])
 
 		return {
-			period: current.period,
+			period: period ? range(period) : { all: true, timezone },
 			rows: current.rows,
 			totals: current.totals,
-			...(before && {
-				previous: {
-					period: before.period,
-					rows: before.rows,
-					totals: before.totals
-				}
-			}),
+			...(before && { previous: before }),
 			notes: resultNotes(dataset, query),
 			truncated: current.truncated
 		}
@@ -473,10 +596,9 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 		) =>
 			schemaOptions && 'ctx' in schemaOptions
 				? querySchemaForCtx(schemaOptions.ctx)
-				: querySchemaFor(schemaOptions?.datasets)) as Analytics<
-			DS,
-			Ctx
-		>['querySchema'],
+				: querySchemaFor(
+						schemaOptions?.datasets?.map(datasetOf) ?? datasets
+					)) as Analytics<DS, Ctx>['querySchema'],
 		resultSchema: (key) => resultSchemaFor(key) as z.ZodType<ShapedResult>,
 		listDatasets: async (ctx) =>
 			(await allowedDatasets(ctx)).map(
@@ -487,12 +609,20 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 }
 
 /**
- * Fails closed: only a non-empty string, a finite number or `allTenants` scopes a query, even
- * when a JavaScript caller's hook returns something its type does not allow.
+ * Fails closed: only a non-empty string, a finite number, a list of those or `allTenants`
+ * scopes a query, even when a JavaScript caller's hook returns something its type does not
+ * allow.
  */
 function isTenant(value: unknown): value is Tenant {
 	return (
 		value === allTenants ||
+		isTenantId(value) ||
+		(Array.isArray(value) && value.every(isTenantId))
+	)
+}
+
+function isTenantId(value: unknown): value is TenantId {
+	return (
 		(typeof value === 'string' && value !== '') ||
 		(typeof value === 'number' && Number.isFinite(value))
 	)
@@ -539,7 +669,7 @@ function resolveSource(
 function compileEverything(dataset: AnyDataset, dialect: Dialect): void {
 	const now = new Date(0)
 	const context: PlanContext = {
-		tenant: 'tenant',
+		tenant: dataset.tenantColumn ? 'tenant' : allTenants,
 		timezone: 'UTC',
 		period: resolvePeriod({ last: { days: 1 } }, 'UTC', now),
 		now,
@@ -651,6 +781,60 @@ function decodeKey(value: unknown, dialect: Dialect): string | number {
 	return dialect.decodeNumber(value) ?? String(value)
 }
 
+/**
+ * Every marked field of `dataset` with the access keys it needs: its own, and for a ratio
+ * those of the measures it divides, which it would leak otherwise.
+ */
+function restrictedFields(dataset: AnyDataset): RestrictedField[] {
+	const measures: Record<string, AnyMeasure> = dataset.measures
+	// defineDataset refuses ratio cycles.
+	const accessOf = (key: string): string[] => {
+		const entry = measures[key]
+		if (!entry) return []
+		const own = entry.access === undefined ? [] : [entry.access]
+		return entry.kind === 'ratio'
+			? [...own, ...accessOf(entry.numerator), ...accessOf(entry.denominator)]
+			: own
+	}
+
+	return [
+		...Object.keys(measures).map((key) => ({
+			kind: 'measure' as const,
+			key,
+			access: [...new Set(accessOf(key))]
+		})),
+		...Object.entries<AnyDimension>(dataset.dimensions).map(([key, entry]) => ({
+			kind: 'dimension' as const,
+			key,
+			access: entry.access === undefined ? [] : [entry.access]
+		}))
+	].filter((field) => field.access.length > 0)
+}
+
+/** `dataset` without the given fields; the dataset itself when there are none. */
+function withoutFields(
+	dataset: AnyDataset,
+	fields: readonly RestrictedField[]
+): AnyDataset {
+	if (fields.length === 0) return dataset
+
+	const keep = <Field>(
+		kind: RestrictedField['kind'],
+		entries: Record<string, Field>
+	): Record<string, Field> =>
+		Object.fromEntries(
+			Object.entries(entries).filter(
+				([key]) =>
+					!fields.some((field) => field.kind === kind && field.key === key)
+			)
+		)
+	return {
+		...dataset,
+		measures: keep('measure', dataset.measures),
+		dimensions: keep('dimension', dataset.dimensions)
+	}
+}
+
 function catalogEntry(dataset: AnyDataset): DatasetCatalogEntry {
 	return {
 		key: dataset.key,