measurr 0.2.0 → 0.4.0

package/src/plan.ts

@@ -6,11 +6,7 @@ import type {
 } from './compile.js'
 import type { AnyDataset, AnyDimension, AnyMeasure } from './dataset.js'
 import type { ExprNode, ParamValue } from './expr.js'
-import {
-	DEFAULT_PERIOD,
-	type PeriodInput,
-	type ResolvedPeriod
-} from './period.js'
+import type { PeriodInput, ResolvedPeriod } from './period.js'
 import { DEFAULT_LIMIT } from './query.js'
 
 /** A parsed query with every default filled in and duplicates removed. */
@@ -65,7 +61,7 @@ export function normalizeQuery(
 		// Order matters: the first grouped dimension leads the rows.
 		groupBy: [...new Set(parsed.groupBy ?? [])],
 		filters,
-		period: parsed.period ?? DEFAULT_PERIOD,
+		period: parsed.period ?? dataset.defaultPeriod,
 		time: parsed.time ?? dataset.defaultTime,
 		compareToPrevious: parsed.compareToPrevious ?? false,
 		sort: parsed.sort
@@ -81,14 +77,17 @@ export function normalizeQuery(
  */
 export const allTenants: unique symbol = Symbol('measurr.allTenants')
 
-/** One tenant's id, or `allTenants`. */
-export type Tenant = string | number | typeof allTenants
+export type TenantId = string | number
+
+/** One tenant's id, a list of them (an empty list matches no rows), or `allTenants`. */
+export type Tenant = TenantId | readonly TenantId[] | typeof allTenants
 
 /** What the planner needs besides the query: values from the hooks and resolved labels. */
 export type PlanContext = {
 	tenant: Tenant
 	timezone: string
-	period: ResolvedPeriod
+	/** Null for an all-time period: no time filter. */
+	period: ResolvedPeriod | null
 	/** The moment the query runs. */
 	now: Date
 	/** Keys for filters on open dimensions, after label resolution, by dimension. */
@@ -215,17 +214,33 @@ function baseWhere(
 	tenant: Tenant,
 	period: { time: string; start: Date; end: Date } | null
 ): ExprNode[] {
-	const where: ExprNode[] =
-		tenant === allTenants
-			? []
-			: [
-					{
+	const where: ExprNode[] = []
+	if (tenant !== allTenants) {
+		// `analytics.query` refuses this first; the planner fails closed on its own too.
+		if (!dataset.tenantColumn) {
+			throw new Error(
+				`Dataset ${dataset.key} has no tenant column; only allTenants may query it`
+			)
+		}
+		const ids = typeof tenant === 'object' ? [...new Set(tenant)] : [tenant]
+		const [only] = ids
+		// One id compiles exactly like the scalar; an empty list renders as a false condition.
+		where.push(
+			ids.length === 1 && only !== undefined
+				? {
 						kind: 'compare',
 						op: '=',
 						left: dataset.tenantColumn,
-						right: param(tenant)
+						right: param(only)
 					}
-				]
+				: {
+						kind: 'in',
+						item: dataset.tenantColumn,
+						values: ids.map(param),
+						negated: false
+					}
+		)
+	}
 	if (dataset.scope) where.push(dataset.scope)
 
 	if (period) {
@@ -357,11 +372,15 @@ export function planQuery(
 	}
 
 	const where = [
-		...baseWhere(dataset, context.tenant, {
-			time: query.time,
-			start: context.period.start,
-			end: context.period.end
-		}),
+		...baseWhere(
+			dataset,
+			context.tenant,
+			context.period && {
+				time: query.time,
+				start: context.period.start,
+				end: context.period.end
+			}
+		),
 		...query.filters.map((filter) => filterNode(dataset, filter, context))
 	]
 

package/src/query.ts

@@ -109,10 +109,31 @@ export type ResultTotals<M, MeasureKey extends string> = Simplify<{
 	[Key in MeasureKey & keyof M]: MeasureValue<M[Key]>
 }>
 
-export type QueryResult<Row, Totals> = {
-	period: { from: string; to: string; timezone: string }
+/** The days a result covers: local days `from` to `to` (inclusive), or all time. */
+export type ResultPeriod =
+	| { from: string; to: string; timezone: string }
+	| { all: true; timezone: string }
+
+/** The period query `Q` names; null or none means the dataset's `Default`. */
+type QueryPeriod<Q, Default> = Q extends unknown
+	? 'period' extends keyof Q
+		? OrDefault<Q['period' & keyof Q], Default>
+		: Default
+	: never
+type OrDefault<P, Default> = P extends null | undefined ? Default : P
+type PeriodShape<P> = P extends { all: true }
+	? Extract<ResultPeriod, { all: true }>
+	: Exclude<ResultPeriod, { all: true }>
+
+export type QueryResult<
+	Row,
+	Totals,
+	Period extends ResultPeriod = ResultPeriod
+> = {
+	period: Period
 	rows: Row[]
 	totals: Totals
+	/** Only for a range: an all-time period has no previous period. */
 	previous?: {
 		period: { from: string; to: string; timezone: string }
 		rows: Row[]
@@ -124,9 +145,13 @@ export type QueryResult<Row, Totals> = {
 
 /** The typed result of query `Q` against the datasets `DS`. */
 export type ResultOf<DS, Q> =
-	DS extends Dataset<infer K, infer M, infer Dm, string>
+	DS extends Dataset<infer K, infer M, infer Dm, string, infer P>
 		? Q extends { dataset: K; measures: readonly (infer Mk extends string)[] }
-			? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>>
+			? QueryResult<
+					ResultRow<M, Dm, Mk, GroupKeys<Q>>,
+					ResultTotals<M, Mk>,
+					PeriodShape<QueryPeriod<Q, P>>
+				>
 			: never
 		: never
 
@@ -135,24 +160,29 @@ export type ResultOf<DS, Q> =
 
 const isoDate = z.iso.date().describe('A date, YYYY-MM-DD.')
 
-export const periodSchema = z
-	.union([
-		z.object({
-			last: z.object({
-				days: z
-					.number()
-					.int()
-					.min(1)
-					.max(MAX_PERIOD_DAYS)
-					.describe('Number of days, ending today.')
-			})
-		}),
-		z.object({ from: isoDate, to: isoDate.describe('Last day, inclusive.') }),
-		z.object({ preset: z.enum(PERIOD_PRESETS) })
-	])
-	.describe(
-		'Which days to count, in the organization timezone. Defaults to the last 30 days. At most two years.'
-	)
+const periodSchema = z.union([
+	z.object({
+		last: z.object({
+			days: z
+				.number()
+				.int()
+				.min(1)
+				.max(MAX_PERIOD_DAYS)
+				.describe('Number of days, ending today.')
+		})
+	}),
+	z.object({ from: isoDate, to: isoDate.describe('Last day, inclusive.') }),
+	z.object({ preset: z.enum(PERIOD_PRESETS) }),
+	z.object({ all: z.literal(true) }).describe('Every row, with no time filter.')
+])
+
+/** How the schema names a dataset's default period, so a model knows what omitting it means. */
+function describePeriod(period: PeriodInput): string {
+	if ('all' in period) return 'all time (no time filter)'
+	if ('last' in period) return `the last ${period.last.days} days`
+	if ('from' in period) return `${period.from} to ${period.to}`
+	return period.preset
+}
 
 function describeList(
 	entries: [string, { label: string; description?: string | undefined }][]
@@ -285,7 +315,11 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 					.describe('Every filter must match.')
 			}),
 			// Nullable as well: LLM tool callers send null for a field they leave out.
-			period: periodSchema.nullish(),
+			period: periodSchema
+				.describe(
+					`Which days to count, in the organization timezone. Defaults to ${describePeriod(dataset.defaultPeriod)}. A range covers at most two years.`
+				)
+				.nullish(),
 			...(timeKeys && {
 				time: z
 					.enum(timeKeys)
@@ -297,7 +331,9 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 			compareToPrevious: z
 				.boolean()
 				.optional()
-				.describe('Also return the previous period of the same length.'),
+				.describe(
+					'Also return the previous period of the same length. Not for all-time periods.'
+				),
 			sort: z
 				.object({
 					by: z.enum(sortKeys),
@@ -328,6 +364,15 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 					message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(', ')}`
 				})
 			}
+
+			const period = query.period ?? dataset.defaultPeriod
+			if (query.compareToPrevious && 'all' in period) {
+				context.addIssue({
+					code: 'custom',
+					path: ['compareToPrevious'],
+					message: 'An all-time period has no previous period to compare with'
+				})
+			}
 		})
 }
 
@@ -339,11 +384,15 @@ export function buildQuerySchema(datasets: readonly AnyDataset[]) {
 	return z.discriminatedUnion('dataset', [first, ...rest])
 }
 
-const periodOutput = z.object({
+const rangeOutput = z.object({
 	from: z.string(),
 	to: z.string(),
 	timezone: z.string()
 })
+const periodOutput = z.union([
+	rangeOutput,
+	z.object({ all: z.literal(true), timezone: z.string() })
+])
 const measureValue = z.number().nullable()
 const dimensionValue = z.object({
 	key: z.union([z.string(), z.number()]).nullable(),
@@ -360,7 +409,7 @@ function resultSchemaOf<Row extends z.ZodType, Totals extends z.ZodType>(
 		rows: z.array(row),
 		totals,
 		previous: z
-			.object({ period: periodOutput, rows: z.array(row), totals })
+			.object({ period: rangeOutput, rows: z.array(row), totals })
 			.optional(),
 		notes: z.array(z.string()),
 		truncated: z.boolean()

package/src/testing.ts

@@ -3,7 +3,11 @@
  * Framework-free: `checkDatasetContract` returns a report and `assertDatasetContract` throws
  * with every failure listed, so it works from `bun:test`, vitest or a script.
  */
-import { type AnalyticsSource, createAnalytics } from './analytics.js'
+import {
+	type AnalyticsSource,
+	createAnalytics,
+	isAnalyticsError
+} from './analytics.js'
 import {
 	type AnyDataset,
 	type AnyDimension,
@@ -11,6 +15,7 @@ import {
 	measure
 } from './dataset.js'
 import type { PeriodInput } from './period.js'
+import { type Tenant, type TenantId, allTenants } from './plan.js'
 import { MAX_MEASURES } from './query.js'
 
 export type ContractCheck = {
@@ -23,8 +28,11 @@ export type ContractReport = { ok: boolean; checks: ContractCheck[] }
 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. */
@@ -46,8 +54,9 @@ type ProbeResult = {
 
 /**
  * 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 async function checkDatasetContract(
 	options: ContractOptions
@@ -78,14 +87,15 @@ export async function checkDatasetContract(
 	const analytics = createAnalytics({
 		datasets: [probe],
 		sources: { main: options.source },
-		tenant: (ctx: { tenant: string | number }) => ctx.tenant,
+		tenant: (ctx: { tenant: Tenant }) => ctx.tenant,
+		authorizeField: () => true,
 		timezone: () => timezone,
 		...(options.now && { now: options.now })
 	})
 
 	const run = async (
 		query: Record<string, unknown>,
-		tenant: string | number = options.tenant
+		tenant: Tenant = options.tenant
 	): Promise<ProbeResult> => {
 		const input = { dataset: dataset.key, period, limit: 100, ...query }
 		return (await analytics.query(input as never, {
@@ -112,10 +122,12 @@ export async function checkDatasetContract(
 
 	const total = (await run({ measures: [COUNT] })).totals[COUNT] ?? 0
 	if (total === 0) {
+		const scope =
+			options.tenant === allTenants ? '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`
 		})
 	}
 
@@ -204,33 +216,47 @@ export async function checkDatasetContract(
 		}
 	}
 
-	await check('tenant isolation', async () => {
-		const measures = Object.keys(probe.measures)
-		const leaked: [string, number | null][] = []
-		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
+	// An empty tenant list is a scope that matches nothing, never a missing filter.
+	for (const [name, tenant] of [
+		['an empty tenant', emptyTenant],
+		['an empty tenant list', []]
+	] as const) {
+		await check(`tenant isolation: ${name}`, async () => {
+			// Rows without a tenant cannot be isolated; a scoped caller must be refused instead.
+			if (!dataset.tenantColumn) {
+				const refused = await run({ measures: [COUNT] }, tenant).then(
+					() => false,
+					(error: unknown) => isAnalyticsError(error, 'forbidden')
 				)
-			)
-		}
-		if (leaked.length > 0) {
-			return `an empty tenant sees ${leaked.map(([key, value]) => `${key}=${value}`).join(', ')}`
-		}
+				return refused
+					? undefined
+					: `${name} may query a dataset without a tenant column`
+			}
 
-		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 undefined
-	})
+			const measures = Object.keys(probe.measures)
+			const leaked: [string, number | null][] = []
+			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 undefined
+		})
+	}
 
 	for (const time of Object.keys(dataset.time)) {
 		await check(`day buckets of ${time} in ${timezone}`, async () => {