measurr 0.1.0

package/src/query.ts

@@ -0,0 +1,399 @@
+import { z } from 'zod'
+import type {
+	AnyDataset,
+	AnyDimension,
+	AnyMeasure,
+	Dataset,
+	DimensionValue,
+	MeasureValue
+} from './dataset.js'
+import {
+	MAX_PERIOD_DAYS,
+	type PeriodInput,
+	type PeriodPreset
+} from './period.js'
+
+export const MAX_MEASURES = 4
+export const MAX_GROUP_BY = 2
+export const MAX_LIMIT = 100
+export const DEFAULT_LIMIT = 20
+
+const PERIOD_PRESETS = [
+	'today',
+	'yesterday',
+	'thisWeek',
+	'lastWeek',
+	'thisMonth',
+	'lastMonth',
+	'thisYear'
+] as const satisfies readonly PeriodPreset[]
+
+// ---------------------------------------------------------------------------------------------
+// Static types
+
+type EmptinessFilter<Name> = { dimension: Name; op: 'isEmpty' | 'isNotEmpty' }
+
+type FilterFor<Name extends string, Dim> = Dim extends {
+	category: 'closed'
+	keyType?: infer K
+}
+	?
+			| { dimension: Name; op: 'in' | 'notIn'; values: readonly K[] }
+			| EmptinessFilter<Name>
+	: Dim extends { category: 'open' }
+		? // Open sets take keys or labels; labels are resolved at query time.
+				| { dimension: Name; op: 'in' | 'notIn'; values: readonly string[] }
+				| EmptinessFilter<Name>
+		: Dim extends { category: 'numeric' }
+			?
+					| { dimension: Name; op: 'between'; from: number; to: number }
+					| EmptinessFilter<Name>
+			:
+					| { dimension: Name; op: 'between'; from: string; to: string }
+					| EmptinessFilter<Name>
+
+/** Dimensions a query may group by: all but `filterOnly` ones. */
+export type GroupableKey<Dm> = {
+	[K in keyof Dm & string]: Dm[K] extends { groupable: false } ? never : K
+}[keyof Dm & string]
+
+/** Dimensions a query may filter by: all but `groupOnly` ones. */
+export type FilterableKey<Dm> = {
+	[K in keyof Dm & string]: Dm[K] extends { filterable: false } ? never : K
+}[keyof Dm & string]
+
+export type DatasetFilter<Dm> = {
+	[Name in FilterableKey<Dm>]: FilterFor<Name, Dm[Name]>
+}[FilterableKey<Dm>]
+
+/** The query one dataset accepts. Distributes over a union of datasets. */
+export type DatasetQuery<DS> =
+	DS extends Dataset<infer K, infer M, infer Dm, infer T>
+		? {
+				dataset: K
+				measures: readonly (keyof M & string)[]
+				groupBy?: readonly GroupableKey<Dm>[] | undefined
+				filters?: readonly DatasetFilter<Dm>[] | undefined
+				/** Null or omitted: the default period. */
+				period?: PeriodInput | null | undefined
+				time?: T | undefined
+				compareToPrevious?: boolean | undefined
+				sort?:
+					| {
+							by: (keyof M & string) | GroupableKey<Dm>
+							direction?: 'asc' | 'desc' | undefined
+					  }
+					| undefined
+				limit?: number | undefined
+			}
+		: never
+
+type GroupKeys<Q> = Q extends { groupBy: readonly (infer G extends string)[] }
+	? G
+	: never
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+export type ResultRow<
+	M,
+	Dm,
+	MeasureKey extends string,
+	GroupKey extends string
+> = Simplify<
+	{ [G in GroupKey & keyof Dm]: DimensionValue<Dm[G]> } & {
+		[Key in MeasureKey & keyof M]: MeasureValue<M[Key]>
+	}
+>
+
+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 }
+	rows: Row[]
+	totals: Totals
+	previous?: {
+		period: { from: string; to: string; timezone: string }
+		rows: Row[]
+		totals: Totals
+	}
+	notes: string[]
+	truncated: boolean
+}
+
+/** 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>
+		? Q extends { dataset: K; measures: readonly (infer Mk extends string)[] }
+			? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>>
+			: never
+		: never
+
+// ---------------------------------------------------------------------------------------------
+// Runtime schemas
+
+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.'
+	)
+
+function describeList(
+	entries: [string, { label: string; description?: string | undefined }][]
+) {
+	return entries
+		.map(
+			([key, entry]) =>
+				`${key}: ${entry.label}${entry.description ? ` (${entry.description})` : ''}`
+		)
+		.join(' · ')
+}
+
+function nonEmpty(values: string[]): [string, ...string[]] | null {
+	const [first, ...rest] = values
+	return first === undefined ? null : [first, ...rest]
+}
+
+function filterSchema(key: string, dim: AnyDimension) {
+	const dimension = z.literal(key)
+	const description = `${dim.label}${dim.description ? `: ${dim.description}` : ''}`
+	const emptiness = z.object({
+		dimension,
+		op: z.enum(['isEmpty', 'isNotEmpty'])
+	})
+
+	switch (dim.category) {
+		case 'closed': {
+			const labels: [string, { label: string }][] = Object.entries(
+				dim.values
+			).map(([value, label]) => [value, { label }])
+			const keys = nonEmpty(labels.map(([value]) => value))
+			if (!keys) throw new Error(`Dimension ${key} lists no values`)
+
+			const values = z.array(z.enum(keys)).min(1).describe(describeList(labels))
+			return z
+				.discriminatedUnion('op', [
+					z.object({ dimension, op: z.enum(['in', 'notIn']), values }),
+					emptiness
+				])
+				.describe(description)
+		}
+		case 'open':
+			return z
+				.discriminatedUnion('op', [
+					z.object({
+						dimension,
+						op: z.enum(['in', 'notIn']),
+						values: z
+							.array(z.string())
+							.min(1)
+							.describe('Keys or names; names match case-insensitively.')
+					}),
+					emptiness
+				])
+				.describe(description)
+		case 'numeric':
+			return z
+				.discriminatedUnion('op', [
+					z.object({
+						dimension,
+						op: z.literal('between'),
+						from: z.number(),
+						to: z.number()
+					}),
+					emptiness
+				])
+				.describe(`${description} (inclusive range)`)
+		case 'time':
+			return z
+				.discriminatedUnion('op', [
+					z.object({
+						dimension,
+						op: z.literal('between'),
+						from: isoDate,
+						to: isoDate
+					}),
+					emptiness
+				])
+				.describe(`${description} (bucket start dates, inclusive)`)
+	}
+}
+
+/** The input schema branch for one dataset. */
+export function datasetQuerySchema(dataset: AnyDataset) {
+	const measures: [string, AnyMeasure][] = Object.entries(dataset.measures)
+	const dimensions: [string, AnyDimension][] = Object.entries(
+		dataset.dimensions
+	)
+	const groupable = dimensions.filter(([, dim]) => dim.groupable)
+	const filterable = dimensions.filter(([, dim]) => dim.filterable)
+
+	const measureKeys = nonEmpty(measures.map(([key]) => key))
+	if (!measureKeys) 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 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({
+			dataset: z
+				.literal(dataset.key)
+				.describe(`${dataset.label}. ${dataset.description}`),
+			measures: z
+				.array(z.enum(measureKeys))
+				.min(1)
+				.max(MAX_MEASURES)
+				.describe(describeList(measures)),
+			...(groupKeys && {
+				groupBy: z
+					.array(z.enum(groupKeys))
+					.max(MAX_GROUP_BY)
+					.optional()
+					.describe([describeList(groupable), ...notes].join('\n'))
+			}),
+			...(firstFilter && {
+				filters: z
+					.array(
+						z.discriminatedUnion('dimension', [firstFilter, ...otherFilters])
+					)
+					.optional()
+					.describe('Every filter must match.')
+			}),
+			// Nullable as well: LLM tool callers send null for a field they leave out.
+			period: periodSchema.nullish(),
+			...(timeKeys && {
+				time: z
+					.enum(timeKeys)
+					.optional()
+					.describe(
+						`Which time field the period applies to; time dimensions name their own. Defaults to ${dataset.defaultTime}. ${describeList(Object.entries(dataset.time))}`
+					)
+			}),
+			compareToPrevious: z
+				.boolean()
+				.optional()
+				.describe('Also return the previous period of the same length.'),
+			sort: z
+				.object({
+					by: z.enum(sortKeys),
+					direction: z.enum(['asc', 'desc']).optional()
+				})
+				.optional()
+				.describe(
+					'One of the asked measures or grouped dimensions. Defaults to time order when grouped by time, otherwise the first measure, descending.'
+				),
+			limit: z
+				.number()
+				.int()
+				.min(1)
+				.max(MAX_LIMIT)
+				.optional()
+				.describe(`Maximum number of groups. Defaults to ${DEFAULT_LIMIT}.`)
+		})
+		.superRefine((query, context) => {
+			// Sorting by something the query does not return would be silently ignored.
+			// groupBy is spread in conditionally above, which hides its type here.
+			const { groupBy } = query as { groupBy?: string[] | undefined }
+			const by = query.sort?.by
+			const returned: string[] = [...query.measures, ...(groupBy ?? [])]
+			if (by !== undefined && !returned.includes(by)) {
+				context.addIssue({
+					code: 'custom',
+					path: ['sort', 'by'],
+					message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(', ')}`
+				})
+			}
+		})
+}
+
+/** A discriminated union on `dataset`, one branch per dataset. */
+export function buildQuerySchema(datasets: readonly AnyDataset[]) {
+	const [first, ...rest] = datasets.map(datasetQuerySchema)
+	if (!first) throw new Error('querySchema needs at least one dataset')
+
+	return z.discriminatedUnion('dataset', [first, ...rest])
+}
+
+const periodOutput = z.object({
+	from: z.string(),
+	to: z.string(),
+	timezone: z.string()
+})
+const measureValue = z.number().nullable()
+const dimensionValue = z.object({
+	key: z.union([z.string(), z.number()]).nullable(),
+	label: z.string()
+})
+
+/** The envelope every result shares; only the row and totals shapes differ per dataset. */
+function resultSchemaOf<Row extends z.ZodType, Totals extends z.ZodType>(
+	row: Row,
+	totals: Totals
+) {
+	return z.object({
+		period: periodOutput,
+		rows: z.array(row),
+		totals,
+		previous: z
+			.object({ period: periodOutput, rows: z.array(row), totals })
+			.optional(),
+		notes: z.array(z.string()),
+		truncated: z.boolean()
+	})
+}
+
+/** The result schema for one dataset. Row fields exist only for grouped dimensions. */
+export function datasetResultSchema(dataset: AnyDataset) {
+	const measures = Object.fromEntries(
+		Object.entries(dataset.measures).map(([key, entry]) => [
+			key,
+			measureValue.optional().describe((entry as AnyMeasure).label)
+		])
+	)
+	const dimensions = Object.fromEntries(
+		Object.entries(dataset.dimensions).map(([key, entry]) => [
+			key,
+			dimensionValue.optional().describe((entry as AnyDimension).label)
+		])
+	)
+
+	return resultSchemaOf(
+		z.object({ ...dimensions, ...measures }),
+		z.object(measures)
+	)
+}
+
+/**
+ * Any dataset's result, without the per-dataset keys (`analytics.resultSchema(key)` has
+ * those): rows hold `{ key, label }` per grouped dimension and a number or null per measure.
+ * For contracts that must not depend on the dataset list, such as an LLM tool's output.
+ */
+export const AnalyticsResultSchema = resultSchemaOf(
+	z.record(z.string(), z.union([dimensionValue, measureValue])),
+	z.record(z.string(), measureValue)
+)

package/src/testing.ts

@@ -0,0 +1,283 @@
+/**
+ * The contract test kit: the same checks for every dataset, run against a seeded database.
+ * 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 AnyDataset,
+	type AnyDimension,
+	dimension,
+	measure
+} from './dataset.js'
+import type { PeriodInput } from './period.js'
+import { MAX_MEASURES } from './query.js'
+
+export type ContractCheck = {
+	name: string
+	ok: boolean
+	message: string | undefined
+}
+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 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. */
+	timezone?: string
+	/** Defaults to the last 365 days. */
+	period?: PeriodInput
+	now?: () => Date
+}
+
+const COUNT = '__contractCount'
+const dayKey = (time: string) => `__contractDay_${time}`
+
+type ProbeRow = Record<string, { key: unknown; label: string } | number | null>
+type ProbeResult = {
+	rows: ProbeRow[]
+	totals: Record<string, number | null>
+	truncated: boolean
+}
+
+/**
+ * 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.
+ */
+export async function checkDatasetContract(
+	options: ContractOptions
+): Promise<ContractReport> {
+	const { dataset } = options
+	const timezone = options.timezone ?? 'Pacific/Auckland'
+	const period = options.period ?? { last: { days: 365 } }
+	const emptyTenant =
+		options.emptyTenant ??
+		(typeof options.tenant === 'number' ? -1 : '__contract_empty_tenant__')
+
+	const probe: AnyDataset = {
+		...dataset,
+		measures: {
+			...dataset.measures,
+			[COUNT]: measure.count({ label: 'Rows' })
+		},
+		dimensions: {
+			...dataset.dimensions,
+			...Object.fromEntries(
+				Object.keys(dataset.time).map((time) => [
+					dayKey(time),
+					dimension.timeBucket(time, 'day')
+				])
+			)
+		}
+	}
+	const analytics = createAnalytics({
+		datasets: [probe],
+		sources: { main: options.source },
+		tenant: (ctx: { tenant: string | number }) => ctx.tenant,
+		timezone: () => timezone,
+		...(options.now && { now: options.now })
+	})
+
+	const run = async (
+		query: Record<string, unknown>,
+		tenant: string | number = options.tenant
+	): Promise<ProbeResult> => {
+		const input = { dataset: dataset.key, period, limit: 100, ...query }
+		return (await analytics.query(input as never, {
+			tenant
+		})) as unknown as ProbeResult
+	}
+
+	const checks: ContractCheck[] = []
+	const check = async (
+		name: string,
+		body: () => Promise<string | undefined>
+	) => {
+		try {
+			const problem = await body()
+			checks.push({ name, ok: problem === undefined, message: problem })
+		} catch (error) {
+			checks.push({
+				name,
+				ok: false,
+				message: error instanceof Error ? error.message : String(error)
+			})
+		}
+	}
+
+	const total = (await run({ measures: [COUNT] })).totals[COUNT] ?? 0
+	if (total === 0) {
+		checks.push({
+			name: 'seeded rows',
+			ok: false,
+			message: `Tenant ${options.tenant} has no rows in the period; the checks below prove little`
+		})
+	}
+
+	for (const key of Object.keys(dataset.measures)) {
+		await check(`measure ${key}`, async () => {
+			const value = (await run({ measures: [key] })).totals[key]
+			if (value !== null && typeof value !== 'number')
+				return `returned ${String(value)}`
+			if (typeof value === 'number' && Number.isNaN(value))
+				return 'returned NaN'
+			return undefined
+		})
+	}
+
+	const dimensions = Object.entries<AnyDimension>(dataset.dimensions)
+	for (const [key, entry] of dimensions) {
+		if (entry.groupable) {
+			await check(`group by ${key}`, async () => {
+				const result = await run({ measures: [COUNT], groupBy: [key] })
+				if (entry.kind === 'manyToMany' || result.truncated) return undefined
+
+				const sum = result.rows.reduce(
+					(acc, row) => acc + Number(row[COUNT] ?? 0),
+					0
+				)
+				return sum === total
+					? undefined
+					: `groups add up to ${sum}, the total is ${total}`
+			})
+		}
+
+		if (entry.filterable) {
+			await check(`filter ${key} by emptiness`, async () => {
+				const empty = await run({
+					measures: [COUNT],
+					filters: [{ dimension: key, op: 'isEmpty' }]
+				})
+				const notEmpty = await run({
+					measures: [COUNT],
+					filters: [{ dimension: key, op: 'isNotEmpty' }]
+				})
+				const sum = (empty.totals[COUNT] ?? 0) + (notEmpty.totals[COUNT] ?? 0)
+				return sum === total
+					? undefined
+					: `isEmpty + isNotEmpty is ${sum}, the total is ${total}`
+			})
+		}
+
+		if (entry.filterable && entry.groupable && entry.category === 'open') {
+			await check(`filter ${key} by label`, async () => {
+				const grouped = await run({ measures: [COUNT], groupBy: [key] })
+				const first = grouped.rows.find((row) => {
+					const value = row[key]
+					return (
+						typeof value === 'object' && value !== null && value.key !== null
+					)
+				})
+				const value = first?.[key]
+				if (!first || typeof value !== 'object' || value === null)
+					return undefined
+
+				const filtered = await run({
+					measures: [COUNT],
+					filters: [{ dimension: key, op: 'in', values: [value.label] }]
+				})
+				const expected = Number(first[COUNT])
+				const actual = filtered.totals[COUNT]
+				return actual === expected
+					? undefined
+					: `filtering by the label "${value.label}" counts ${actual}, its group counts ${expected}`
+			})
+		}
+
+		if (entry.filterable && entry.category === 'closed') {
+			await check(`filter ${key} by value`, async () => {
+				const [first] = Object.keys(
+					entry.kind === 'enum' || entry.kind === 'computed' ? entry.values : {}
+				)
+				if (first === undefined) return 'lists no values'
+				await run({
+					measures: [COUNT],
+					filters: [{ dimension: key, op: 'in', values: [first] }]
+				})
+				return undefined
+			})
+		}
+	}
+
+	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
+				)
+			)
+		}
+		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 undefined
+	})
+
+	for (const time of Object.keys(dataset.time)) {
+		await check(`day buckets of ${time} in ${timezone}`, async () => {
+			const days = await run({
+				measures: [COUNT],
+				groupBy: [dayKey(time)],
+				time,
+				sort: { by: COUNT, direction: 'desc' }
+			})
+
+			for (const row of days.rows.slice(0, 5)) {
+				const bucket = row[dayKey(time)]
+				if (
+					typeof bucket !== 'object' ||
+					bucket === null ||
+					typeof bucket.key !== 'string'
+				)
+					continue
+
+				const day = await run({
+					measures: [COUNT],
+					time,
+					period: { from: bucket.key, to: bucket.key }
+				})
+				if (day.totals[COUNT] !== row[COUNT]) {
+					return `the ${bucket.key} bucket counts ${row[COUNT]}, the period ${bucket.key} counts ${day.totals[COUNT]}`
+				}
+			}
+			return undefined
+		})
+	}
+
+	return { ok: checks.every((entry) => entry.ok), checks }
+}
+
+/** Runs `checkDatasetContract` and throws with every failed check listed. */
+export async function assertDatasetContract(
+	options: ContractOptions
+): Promise<ContractReport> {
+	const report = await checkDatasetContract(options)
+	const failed = report.checks.filter((entry) => !entry.ok)
+	if (failed.length > 0) {
+		const lines = failed.map((entry) => `- ${entry.name}: ${entry.message}`)
+		throw new Error(
+			`Dataset ${options.dataset.key} breaks the contract:\n${lines.join('\n')}`
+		)
+	}
+
+	return report
+}