hazo_dataviz 0.3.0

package/dist/lib/runners/in_memory.js

@@ -0,0 +1,303 @@
+import { HazoError } from 'hazo_core';
+// ---------------------------------------------------------------------------
+// Time-grain bucketing
+// ---------------------------------------------------------------------------
+function isoWeek(d) {
+    // ISO 8601: week starts Monday; week 1 = week containing first Thursday
+    const thursday = new Date(d);
+    thursday.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 6) % 7) + 3);
+    const yearStart = new Date(Date.UTC(thursday.getUTCFullYear(), 0, 1));
+    const weekNum = Math.ceil(((thursday.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    return `${thursday.getUTCFullYear()}-W${String(weekNum).padStart(2, '0')}`;
+}
+function bucketDate(value, grain) {
+    const d = value instanceof Date ? value : new Date(String(value));
+    if (isNaN(d.getTime()))
+        return String(value);
+    const y = d.getUTCFullYear();
+    const m = d.getUTCMonth(); // 0-based
+    switch (grain) {
+        case 'day':
+            return `${y}-${String(m + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')}`;
+        case 'week':
+            return isoWeek(d);
+        case 'month':
+            return `${y}-${String(m + 1).padStart(2, '0')}`;
+        case 'quarter':
+            return `${y}-Q${Math.floor(m / 3) + 1}`;
+        case 'year':
+            return String(y);
+    }
+}
+// ---------------------------------------------------------------------------
+// Aggregation helpers (SQL null semantics — nulls are skipped)
+// ---------------------------------------------------------------------------
+function numericValues(vals) {
+    return vals.filter((v) => v !== null && v !== undefined && typeof v === 'number' && !isNaN(v));
+}
+function aggregate(vals, agg, rawVals) {
+    if (agg === 'count')
+        return vals.filter((v) => v !== null && v !== undefined).length;
+    const nums = numericValues(vals);
+    if (nums.length === 0)
+        return null;
+    switch (agg) {
+        case 'sum': return nums.reduce((a, b) => a + b, 0);
+        case 'avg': return nums.reduce((a, b) => a + b, 0) / nums.length;
+        case 'min': return Math.min(...nums);
+        case 'max': return Math.max(...nums);
+        case 'last': {
+            // last = value at max raw value in the group (rawVals = temporal dim values)
+            if (!rawVals || rawVals.length === 0)
+                return nums[nums.length - 1] ?? null;
+            let maxRaw = rawVals[0];
+            let lastVal = vals[0];
+            for (let i = 1; i < rawVals.length; i++) {
+                const rv = rawVals[i];
+                const curr = typeof rv === 'string' || typeof rv === 'number' ? rv : String(rv);
+                const max = typeof maxRaw === 'string' || typeof maxRaw === 'number' ? maxRaw : String(maxRaw);
+                if (curr > max) {
+                    maxRaw = rv;
+                    lastVal = vals[i];
+                }
+            }
+            return lastVal ?? null;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Filter application
+// ---------------------------------------------------------------------------
+function applyFilter(row, filter) {
+    const val = row[filter.field];
+    const { op, value } = filter;
+    switch (op) {
+        case 'is_null': return val === null || val === undefined;
+        case 'eq': return val === value;
+        case 'neq': return val !== value;
+        case 'gt': return typeof val === 'number' && typeof value === 'number' && val > value;
+        case 'gte': return typeof val === 'number' && typeof value === 'number' && val >= value;
+        case 'lt': return typeof val === 'number' && typeof value === 'number' && val < value;
+        case 'lte': return typeof val === 'number' && typeof value === 'number' && val <= value;
+        case 'in': return Array.isArray(value) && value.includes(val);
+        case 'between': {
+            if (!Array.isArray(value) || value.length !== 2)
+                return false;
+            const [lo, hi] = value;
+            if (typeof val !== 'number' || typeof lo !== 'number' || typeof hi !== 'number')
+                return false;
+            return val >= lo && val <= hi;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Runner factory
+// ---------------------------------------------------------------------------
+export function createInMemoryRunner(descriptor, rows) {
+    return async function runQuery(query) {
+        // --- Validate query fields against descriptor ---
+        const allDimFields = Object.entries(descriptor.fields)
+            .filter(([, f]) => f.role === 'dimension')
+            .map(([k]) => k);
+        const allMeasureFields = Object.entries(descriptor.fields)
+            .filter(([, f]) => f.role === 'measure')
+            .map(([k]) => k);
+        for (const dimField of query.dimensions) {
+            if (!(dimField in descriptor.fields)) {
+                throw new HazoError({
+                    code: 'HAZO_DATAVIZ_UNKNOWN_FIELD',
+                    pkg: 'hazo_dataviz',
+                    message: `Unknown field: ${dimField}`,
+                });
+            }
+            if (!allDimFields.includes(dimField)) {
+                throw new HazoError({
+                    code: 'HAZO_DATAVIZ_FIELD_ROLE_MISMATCH',
+                    pkg: 'hazo_dataviz',
+                    message: `Field "${dimField}" is a measure, cannot be used as a dimension`,
+                });
+            }
+        }
+        for (const ref of query.measures) {
+            if (!(ref.field in descriptor.fields)) {
+                throw new HazoError({
+                    code: 'HAZO_DATAVIZ_UNKNOWN_FIELD',
+                    pkg: 'hazo_dataviz',
+                    message: `Unknown field: ${ref.field}`,
+                });
+            }
+            if (!allMeasureFields.includes(ref.field)) {
+                throw new HazoError({
+                    code: 'HAZO_DATAVIZ_FIELD_ROLE_MISMATCH',
+                    pkg: 'hazo_dataviz',
+                    message: `Field "${ref.field}" is a dimension, cannot be used as a measure`,
+                });
+            }
+        }
+        // --- Validate timeGrain ---
+        let temporalDimField = null;
+        if (query.timeGrain) {
+            const temporalDims = query.dimensions.filter((d) => {
+                const f = descriptor.fields[d];
+                return f?.role === 'dimension' && f.type === 'time';
+            });
+            if (temporalDims.length === 0) {
+                throw new HazoError({
+                    code: 'HAZO_DATAVIZ_INVALID_TIME_GRAIN',
+                    pkg: 'hazo_dataviz',
+                    message: 'timeGrain requires a temporal dimension in the query',
+                });
+            }
+            temporalDimField = temporalDims[0];
+            const fieldDef = descriptor.fields[temporalDimField];
+            if (fieldDef.role === 'dimension' && fieldDef.type === 'time') {
+                const declared = fieldDef.timeGrains ?? [];
+                if (!declared.includes(query.timeGrain)) {
+                    throw new HazoError({
+                        code: 'HAZO_DATAVIZ_INVALID_TIME_GRAIN',
+                        pkg: 'hazo_dataviz',
+                        message: `Time grain "${query.timeGrain}" not declared for field "${temporalDimField}". Declared: ${declared.join(', ')}`,
+                    });
+                }
+            }
+        }
+        // --- 1. Filter ---
+        let filtered = rows;
+        if (query.filters && query.filters.length > 0) {
+            filtered = rows.filter((row) => query.filters.every((f) => applyFilter(row, f)));
+        }
+        // Empty result after filter — not an error
+        if (filtered.length === 0) {
+            const columns = buildColumns(query, descriptor);
+            return { rows: [], columns, query };
+        }
+        // --- 2. Time-grain bucket ---
+        if (query.timeGrain && temporalDimField) {
+            const grain = query.timeGrain;
+            const field = temporalDimField;
+            filtered = filtered.map((row) => ({
+                ...row,
+                [field]: bucketDate(row[field], grain),
+            }));
+        }
+        // --- 3. Group ---
+        const groups = new Map();
+        // Find temporal dim for 'last' semantics — use the raw (pre-bucketed) values per group
+        // We capture raw values before bucketing by referencing the original rows in parallel
+        const rawRows = rows; // original, pre-filter; we need pre-bucket temporal values
+        // Recompute filtered indices for raw temporal capture
+        let filteredIndices = [];
+        if (query.filters && query.filters.length > 0) {
+            rows.forEach((row, i) => {
+                if (query.filters.every((f) => applyFilter(row, f)))
+                    filteredIndices.push(i);
+            });
+        }
+        else {
+            filteredIndices = rows.map((_, i) => i);
+        }
+        filteredIndices.forEach((origIdx, filteredIdx) => {
+            const row = filtered[filteredIdx];
+            const rawRow = rawRows[origIdx];
+            const groupKey = query.dimensions.map((d) => `${d}=${String(row[d])}`).join('|');
+            if (!groups.has(groupKey)) {
+                const dimValues = {};
+                for (const d of query.dimensions) {
+                    dimValues[d] = row[d];
+                }
+                const measureArrays = {};
+                const rawTemporalValues = {};
+                for (const ref of query.measures) {
+                    measureArrays[ref.field] = [];
+                    rawTemporalValues[ref.field] = [];
+                }
+                groups.set(groupKey, { dimValues, measureArrays, rawTemporalValues });
+            }
+            const group = groups.get(groupKey);
+            for (const ref of query.measures) {
+                group.measureArrays[ref.field].push(row[ref.field]);
+                // Capture raw temporal value for 'last' agg
+                if (temporalDimField) {
+                    group.rawTemporalValues[ref.field].push(rawRow[temporalDimField]);
+                }
+            }
+        });
+        // --- 4. Aggregate ---
+        let resultRows = [];
+        for (const group of groups.values()) {
+            const resultRow = { ...group.dimValues };
+            for (const ref of query.measures) {
+                const fieldDef = descriptor.fields[ref.field];
+                const agg = ref.agg ?? (fieldDef.role === 'measure' ? fieldDef.agg : 'count');
+                const vals = group.measureArrays[ref.field] ?? [];
+                const rawTemporalVals = group.rawTemporalValues[ref.field];
+                resultRow[ref.field] = aggregate(vals, agg, agg === 'last' ? rawTemporalVals : undefined);
+            }
+            resultRows.push(resultRow);
+        }
+        // --- 5. Sort + Limit ---
+        if (query.sort && query.sort.length > 0) {
+            resultRows.sort((a, b) => {
+                for (const s of query.sort) {
+                    const av = a[s.field];
+                    const bv = b[s.field];
+                    const av2 = av === null || av === undefined ? '' : String(av);
+                    const bv2 = bv === null || bv === undefined ? '' : String(bv);
+                    if (av2 < bv2)
+                        return s.dir === 'asc' ? -1 : 1;
+                    if (av2 > bv2)
+                        return s.dir === 'asc' ? 1 : -1;
+                }
+                return 0;
+            });
+        }
+        else {
+            // Default: temporal dim asc if present, else first measure desc
+            if (temporalDimField) {
+                const f = temporalDimField;
+                resultRows.sort((a, b) => {
+                    const av = String(a[f] ?? '');
+                    const bv = String(b[f] ?? '');
+                    return av < bv ? -1 : av > bv ? 1 : 0;
+                });
+            }
+            else if (query.measures.length > 0) {
+                const firstMeasure = query.measures[0].field;
+                resultRows.sort((a, b) => {
+                    const av = typeof a[firstMeasure] === 'number' ? a[firstMeasure] : 0;
+                    const bv = typeof b[firstMeasure] === 'number' ? b[firstMeasure] : 0;
+                    return bv - av; // desc
+                });
+            }
+        }
+        if (query.limit !== undefined) {
+            resultRows = resultRows.slice(0, query.limit);
+        }
+        const columns = buildColumns(query, descriptor);
+        return { rows: resultRows, columns, query };
+    };
+}
+function buildColumns(query, descriptor) {
+    const columns = [];
+    for (const dimField of query.dimensions) {
+        const fieldDef = descriptor.fields[dimField];
+        columns.push({
+            key: dimField,
+            role: 'dimension',
+            label: dimField,
+            format: fieldDef?.role === 'dimension' ? fieldDef.format : undefined,
+        });
+    }
+    for (const ref of query.measures) {
+        const fieldDef = descriptor.fields[ref.field];
+        const agg = ref.agg ?? (fieldDef?.role === 'measure' ? fieldDef.agg : undefined);
+        columns.push({
+            key: ref.field,
+            role: 'measure',
+            label: ref.field,
+            format: fieldDef?.role === 'measure' ? fieldDef.format : undefined,
+            agg,
+        });
+    }
+    return columns;
+}

package/dist/lib/shape.d.ts

@@ -0,0 +1,11 @@
+import type { DatasetDescriptor } from '../schema/descriptor.js';
+import type { Query } from '../schema/query.js';
+export interface QueryShape {
+    temporalDims: string[];
+    categoricalDims: string[];
+    dimCount: number;
+    measureCount: number;
+    splitDim?: string;
+}
+export declare function classifyShape(descriptor: DatasetDescriptor, query: Query): QueryShape;
+//# sourceMappingURL=shape.d.ts.map

package/dist/lib/shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.d.ts","sourceRoot":"","sources":["../../src/lib/shape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,GAAG,UAAU,CA2BrF"}

package/dist/lib/shape.js

@@ -0,0 +1,27 @@
+export function classifyShape(descriptor, query) {
+    const temporalDims = [];
+    const categoricalDims = [];
+    for (const dim of query.dimensions) {
+        const field = descriptor.fields[dim];
+        if (field?.role === 'dimension') {
+            if (field.type === 'time') {
+                temporalDims.push(dim);
+            }
+            else {
+                categoricalDims.push(dim);
+            }
+        }
+        else {
+            // Field not found or not a dimension — treat as categorical (defensive)
+            categoricalDims.push(dim);
+        }
+    }
+    const splitDim = query.dimensions.length >= 2 ? query.dimensions[1] : undefined;
+    return {
+        temporalDims,
+        categoricalDims,
+        dimCount: query.dimensions.length,
+        measureCount: query.measures.length,
+        splitDim,
+    };
+}

package/dist/schema/descriptor.d.ts

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+export declare const AggSchema: z.ZodEnum<{
+    sum: "sum";
+    avg: "avg";
+    min: "min";
+    max: "max";
+    last: "last";
+    count: "count";
+}>;
+export type Agg = z.infer<typeof AggSchema>;
+export declare const TimeGrainSchema: z.ZodEnum<{
+    day: "day";
+    week: "week";
+    month: "month";
+    quarter: "quarter";
+    year: "year";
+}>;
+export type TimeGrain = z.infer<typeof TimeGrainSchema>;
+export declare const FormatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"currency">;
+    ccy: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"percent">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"number">;
+    decimals: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"compact">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"date">;
+    dateFormat: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type Format = z.infer<typeof FormatSchema>;
+export declare const FieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"measure">;
+    agg: z.ZodEnum<{
+        sum: "sum";
+        avg: "avg";
+        min: "min";
+        max: "max";
+        last: "last";
+        count: "count";
+    }>;
+    format: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"currency">;
+        ccy: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"percent">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"number">;
+        decimals: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"compact">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"date">;
+        dateFormat: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>, z.ZodObject<{
+    role: z.ZodLiteral<"dimension">;
+    type: z.ZodEnum<{
+        category: "category";
+        time: "time";
+    }>;
+    timeGrains: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        quarter: "quarter";
+        year: "year";
+    }>>>;
+    format: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"currency">;
+        ccy: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"percent">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"number">;
+        decimals: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"compact">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"date">;
+        dateFormat: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>], "role">;
+export type Field = z.infer<typeof FieldSchema>;
+declare const JoinSpecSchema: z.ZodObject<{
+    key: z.ZodString;
+    with: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type JoinSpec = z.infer<typeof JoinSpecSchema>;
+export declare const DatasetDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    grain: z.ZodArray<z.ZodString>;
+    fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        role: z.ZodLiteral<"measure">;
+        agg: z.ZodEnum<{
+            sum: "sum";
+            avg: "avg";
+            min: "min";
+            max: "max";
+            last: "last";
+            count: "count";
+        }>;
+        format: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"currency">;
+            ccy: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"percent">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"number">;
+            decimals: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"compact">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"date">;
+            dateFormat: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        role: z.ZodLiteral<"dimension">;
+        type: z.ZodEnum<{
+            category: "category";
+            time: "time";
+        }>;
+        timeGrains: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+            quarter: "quarter";
+            year: "year";
+        }>>>;
+        format: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"currency">;
+            ccy: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"percent">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"number">;
+            decimals: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"compact">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"date">;
+            dateFormat: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>], "role">>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        measures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        split: z.ZodOptional<z.ZodString>;
+        viz: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    joinable: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        with: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type DatasetDescriptor = z.infer<typeof DatasetDescriptorSchema>;
+export declare function parseDescriptor(input: unknown): DatasetDescriptor;
+export {};
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/schema/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../src/schema/descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,SAAS;;;;;;;EAAwD,CAAC;AAC/E,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAE5C,eAAO,MAAM,eAAe;;;;;;EAAsD,CAAC;AACnF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAQxD,eAAO,MAAM,YAAY;;;;;;;;;;;;;2BAMvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAelD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAA2E,CAAC;AACpG,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,QAAA,MAAM,cAAc;;;iBAGlB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAStD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CASjE"}

package/dist/schema/descriptor.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { fromZodValidation } from 'hazo_core';
+export const AggSchema = z.enum(['sum', 'avg', 'min', 'max', 'last', 'count']);
+export const TimeGrainSchema = z.enum(['day', 'week', 'month', 'quarter', 'year']);
+const FormatCurrencySchema = z.object({ kind: z.literal('currency'), ccy: z.string().min(1) });
+const FormatPercentSchema = z.object({ kind: z.literal('percent') });
+const FormatNumberSchema = z.object({ kind: z.literal('number'), decimals: z.number().int().min(0).optional() });
+const FormatCompactSchema = z.object({ kind: z.literal('compact') });
+const FormatDateSchema = z.object({ kind: z.literal('date'), dateFormat: z.string().optional() });
+export const FormatSchema = z.discriminatedUnion('kind', [
+    FormatCurrencySchema,
+    FormatPercentSchema,
+    FormatNumberSchema,
+    FormatCompactSchema,
+    FormatDateSchema,
+]);
+const MeasureFieldSchema = z.object({
+    role: z.literal('measure'),
+    agg: AggSchema,
+    format: FormatSchema.optional(),
+});
+const DimensionFieldSchema = z.object({
+    role: z.literal('dimension'),
+    type: z.enum(['category', 'time']),
+    timeGrains: z.array(TimeGrainSchema).optional(),
+    format: FormatSchema.optional(),
+});
+export const FieldSchema = z.discriminatedUnion('role', [MeasureFieldSchema, DimensionFieldSchema]);
+const JoinSpecSchema = z.object({
+    key: z.string().min(1),
+    with: z.string().optional(),
+});
+const DefaultsSchema = z.object({
+    measures: z.array(z.string()).optional(),
+    dimensions: z.array(z.string()).optional(),
+    split: z.string().optional(),
+    viz: z.string().optional(),
+});
+export const DatasetDescriptorSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    grain: z.array(z.string()).min(1),
+    fields: z.record(z.string(), FieldSchema),
+    defaults: DefaultsSchema.optional(),
+    joinable: z.array(JoinSpecSchema).optional(),
+});
+export function parseDescriptor(input) {
+    const result = DatasetDescriptorSchema.safeParse(input);
+    if (!result.success) {
+        throw fromZodValidation(result.error, {
+            pkg: 'hazo_dataviz',
+            code: 'HAZO_DATAVIZ_INVALID_DESCRIPTOR',
+        });
+    }
+    return result.data;
+}

package/dist/schema/query.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+export declare const FilterOpSchema: z.ZodEnum<{
+    in: "in";
+    eq: "eq";
+    neq: "neq";
+    gt: "gt";
+    gte: "gte";
+    lt: "lt";
+    lte: "lte";
+    between: "between";
+    is_null: "is_null";
+}>;
+export type FilterOp = z.infer<typeof FilterOpSchema>;
+export declare const MeasureRefSchema: z.ZodObject<{
+    field: z.ZodString;
+    agg: z.ZodOptional<z.ZodEnum<{
+        sum: "sum";
+        avg: "avg";
+        min: "min";
+        max: "max";
+        last: "last";
+        count: "count";
+    }>>;
+}, z.core.$strip>;
+export type MeasureRef = z.infer<typeof MeasureRefSchema>;
+export declare const FilterSchema: z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<{
+        in: "in";
+        eq: "eq";
+        neq: "neq";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+        between: "between";
+        is_null: "is_null";
+    }>;
+    value: z.ZodUnknown;
+}, z.core.$strip>;
+export type Filter = z.infer<typeof FilterSchema>;
+export declare const SortSchema: z.ZodObject<{
+    field: z.ZodString;
+    dir: z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>;
+}, z.core.$strip>;
+export type Sort = z.infer<typeof SortSchema>;
+export declare const QuerySchema: z.ZodObject<{
+    measures: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        agg: z.ZodOptional<z.ZodEnum<{
+            sum: "sum";
+            avg: "avg";
+            min: "min";
+            max: "max";
+            last: "last";
+            count: "count";
+        }>>;
+    }, z.core.$strip>>;
+    dimensions: z.ZodArray<z.ZodString>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            in: "in";
+            eq: "eq";
+            neq: "neq";
+            gt: "gt";
+            gte: "gte";
+            lt: "lt";
+            lte: "lte";
+            between: "between";
+            is_null: "is_null";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    timeGrain: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        quarter: "quarter";
+        year: "year";
+    }>>;
+    sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        dir: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Query = z.infer<typeof QuerySchema>;
+export declare function parseQuery(input: unknown): Query;
+//# sourceMappingURL=query.d.ts.map

package/dist/schema/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/schema/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,cAAc;;;;;;;;;;EAEzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAG3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;iBAIvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,eAAO,MAAM,UAAU;;;;;;iBAGrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUvB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAShD"}