measurr 0.1.0

package/dist/query.d.ts

@@ -0,0 +1,619 @@
+import { z } from 'zod';
+import type { AnyDataset, Dataset, DimensionValue, MeasureValue } from './dataset.js';
+import { type PeriodInput } from './period.js';
+export declare const MAX_MEASURES = 4;
+export declare const MAX_GROUP_BY = 2;
+export declare const MAX_LIMIT = 100;
+export declare const DEFAULT_LIMIT = 20;
+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';
+} ? {
+    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;
+export declare const periodSchema: z.ZodUnion<readonly [z.ZodObject<{
+    last: z.ZodObject<{
+        days: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodISODate;
+    to: z.ZodISODate;
+}, z.core.$strip>, z.ZodObject<{
+    preset: z.ZodEnum<{
+        lastMonth: "lastMonth";
+        lastWeek: "lastWeek";
+        thisMonth: "thisMonth";
+        thisWeek: "thisWeek";
+        thisYear: "thisYear";
+        today: "today";
+        yesterday: "yesterday";
+    }>;
+}, z.core.$strip>]>;
+/** The input schema branch for one dataset. */
+export declare function datasetQuerySchema(dataset: AnyDataset): z.ZodObject<{
+    dataset: z.ZodLiteral<string>;
+    measures: z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    groupBy?: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    filters?: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">, ...(z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">)[]], "dimension">>>;
+    period: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        last: z.ZodObject<{
+            days: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        preset: z.ZodEnum<{
+            lastMonth: "lastMonth";
+            lastWeek: "lastWeek";
+            thisMonth: "thisMonth";
+            thisWeek: "thisWeek";
+            thisYear: "thisYear";
+            today: "today";
+            yesterday: "yesterday";
+        }>;
+    }, z.core.$strip>]>>>;
+    time?: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    compareToPrevious: z.ZodOptional<z.ZodBoolean>;
+    sort: z.ZodOptional<z.ZodObject<{
+        by: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+    }, z.core.$strip>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** A discriminated union on `dataset`, one branch per dataset. */
+export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    dataset: z.ZodLiteral<string>;
+    measures: z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    groupBy?: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    filters?: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">, ...(z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">)[]], "dimension">>>;
+    period: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        last: z.ZodObject<{
+            days: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        preset: z.ZodEnum<{
+            lastMonth: "lastMonth";
+            lastWeek: "lastWeek";
+            thisMonth: "thisMonth";
+            thisWeek: "thisWeek";
+            thisYear: "thisYear";
+            today: "today";
+            yesterday: "yesterday";
+        }>;
+    }, z.core.$strip>]>>>;
+    time?: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    compareToPrevious: z.ZodOptional<z.ZodBoolean>;
+    sort: z.ZodOptional<z.ZodObject<{
+        by: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+    }, z.core.$strip>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, ...z.ZodObject<{
+    dataset: z.ZodLiteral<string>;
+    measures: z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    groupBy?: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    filters?: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">, ...(z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            in: "in";
+            notIn: "notIn";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op"> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodLiteral<"between">;
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        dimension: z.ZodLiteral<string>;
+        op: z.ZodEnum<{
+            isEmpty: "isEmpty";
+            isNotEmpty: "isNotEmpty";
+        }>;
+    }, z.core.$strip>], "op">)[]], "dimension">>>;
+    period: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        last: z.ZodObject<{
+            days: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        from: z.ZodISODate;
+        to: z.ZodISODate;
+    }, z.core.$strip>, z.ZodObject<{
+        preset: z.ZodEnum<{
+            lastMonth: "lastMonth";
+            lastWeek: "lastWeek";
+            thisMonth: "thisMonth";
+            thisWeek: "thisWeek";
+            thisYear: "thisYear";
+            today: "today";
+            yesterday: "yesterday";
+        }>;
+    }, z.core.$strip>]>>>;
+    time?: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    compareToPrevious: z.ZodOptional<z.ZodBoolean>;
+    sort: z.ZodOptional<z.ZodObject<{
+        by: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+    }, z.core.$strip>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>[]], "dataset">;
+/** The result schema for one dataset. Row fields exist only for grouped dimensions. */
+export declare function datasetResultSchema(dataset: AnyDataset): z.ZodObject<{
+    period: z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        timezone: z.ZodString;
+    }, z.core.$strip>;
+    rows: z.ZodArray<z.ZodObject<{
+        [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>> | z.ZodOptional<z.ZodObject<{
+            key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    totals: z.ZodObject<{
+        [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>;
+    previous: z.ZodOptional<z.ZodObject<{
+        period: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>;
+        rows: z.ZodArray<z.ZodObject<{
+            [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>> | z.ZodOptional<z.ZodObject<{
+                key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                label: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        totals: z.ZodObject<{
+            [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    notes: z.ZodArray<z.ZodString>;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * 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 declare const AnalyticsResultSchema: z.ZodObject<{
+    period: z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        timezone: z.ZodString;
+    }, z.core.$strip>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        label: z.ZodString;
+    }, z.core.$strip>, z.ZodNullable<z.ZodNumber>]>>>;
+    totals: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>;
+    previous: z.ZodOptional<z.ZodObject<{
+        period: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>;
+        rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodNullable<z.ZodNumber>]>>>;
+        totals: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    notes: z.ZodArray<z.ZodString>;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+export {};

package/dist/testing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 } from './analytics.js';
+import { type AnyDataset } from './dataset.js';
+import type { PeriodInput } from './period.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;
+};
+/**
+ * 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 declare function checkDatasetContract(options: ContractOptions): Promise<ContractReport>;
+/** Runs `checkDatasetContract` and throws with every failed check listed. */
+export declare function assertDatasetContract(options: ContractOptions): Promise<ContractReport>;