@hypequery/datasets 0.0.0-canary-20260520183507

package/dist/executor.js

@@ -0,0 +1,244 @@
+/**
+ * MetricExecutor — resolves metrics to SQL and executes them.
+ *
+ * Supports two modes:
+ * 1. **Query builder** (recommended) — pass a `QueryBuilderFactoryLike` and the
+ *    executor builds queries via the builder's fluent API, then calls `.execute()`.
+ * 2. **Raw adapter** (deprecated) — pass a `MetricAdapter` with a `rawQuery` function
+ *    and the executor generates SQL strings manually.
+ *
+ * The executor stays DB-agnostic via duck-typed protocol interfaces.
+ */
+import { validateSQLIdentifier } from './sql-utils.js';
+import { validateFilterValue } from './validation.js';
+import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveFilterField, resolveTenantFilterColumn, } from './query-planner.js';
+// =============================================================================
+// VALIDATION
+// =============================================================================
+function validateQuery(metric, query) {
+    const errors = [];
+    const ref = metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+    const ds = ref.dataset;
+    const dimensionNames = Object.keys(ds.dimensions);
+    const filterNames = Object.keys(ds.filters).length > 0
+        ? Object.keys(ds.filters)
+        : dimensionNames;
+    const grain = metric.__type === 'grained_metric_ref' ? metric.grain : query.by;
+    const orderableFields = new Set([
+        ...(query.dimensions ?? []),
+        ref.name,
+        ...(grain ? ['period'] : []),
+    ]);
+    if (metric.__type === 'grained_metric_ref' && query.by && query.by !== metric.grain) {
+        errors.push(`Metric "${ref.name}" is already grained by "${metric.grain}" and cannot be queried with by="${query.by}".`);
+    }
+    // Validate dimensions
+    for (const dim of query.dimensions ?? []) {
+        if (!dimensionNames.includes(dim)) {
+            errors.push(`Unknown dimension "${dim}". Available: ${dimensionNames.join(', ')}`);
+        }
+    }
+    // Validate filters
+    for (const filter of query.filters ?? []) {
+        if (!filterNames.includes(filter.field)) {
+            errors.push(`Unknown filter field "${filter.field}". Available: ${filterNames.join(', ')}`);
+            continue;
+        }
+        const filterDefinition = ds.filters[filter.field];
+        if (filterDefinition?.operators && !filterDefinition.operators.includes(filter.operator)) {
+            errors.push(`Filter "${filter.field}" does not allow operator "${filter.operator}". Allowed: ${filterDefinition.operators.join(', ')}`);
+            continue;
+        }
+        const resolvedField = ds.filters[filter.field]?.field ?? filter.field;
+        const fieldType = ds.dimensions[resolvedField]?.fieldType;
+        if (fieldType) {
+            const filterError = validateFilterValue(filter, fieldType);
+            if (filterError) {
+                errors.push(filterError);
+            }
+        }
+    }
+    // Validate order by fields against the metric output shape
+    for (const order of query.orderBy ?? []) {
+        if (!orderableFields.has(order.field)) {
+            errors.push(`Unknown orderBy field "${order.field}". Available: ${Array.from(orderableFields).join(', ')}`);
+        }
+    }
+    // Validate grain requires timeKey
+    if (query.by && !ds.timeKey) {
+        errors.push(`Cannot use "by" grain — dataset "${ds.name}" has no timeKey.`);
+    }
+    // Validate limits
+    if (ds.limits) {
+        if (ds.limits.maxDimensions && (query.dimensions?.length ?? 0) > ds.limits.maxDimensions) {
+            errors.push(`Too many dimensions (${query.dimensions?.length}). Max: ${ds.limits.maxDimensions}`);
+        }
+        if (ds.limits.maxMeasures && 1 > ds.limits.maxMeasures) {
+            errors.push(`Too many measures (1). Max: ${ds.limits.maxMeasures}`);
+        }
+        if (ds.limits.maxFilters && (query.filters?.length ?? 0) > ds.limits.maxFilters) {
+            errors.push(`Too many filters (${query.filters?.length}). Max: ${ds.limits.maxFilters}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+export class MetricExecutor {
+    builderFactory;
+    constructor(options) {
+        this.builderFactory = options.builderFactory;
+    }
+    getBuilderFactory() {
+        return this.builderFactory;
+    }
+    /**
+     * Execute a metric query. Generates SQL, applies tenant/filter context, executes.
+     */
+    async run(metric, query = {}, context) {
+        const validation = this.validate(metric, query);
+        if (!validation.valid) {
+            throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
+        }
+        const start = Date.now();
+        return this.runViaBuilder(metric, query, context, start);
+    }
+    /**
+     * Generate SQL without executing.
+     */
+    toSQL(metric, query = {}, context) {
+        const ref = metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+        const grain = metric.__type === 'grained_metric_ref' ? metric.grain : query.by ?? undefined;
+        const spec = ref.spec;
+        if (spec.__type === 'derived_metric_spec') {
+            return this.buildDerivedSQLViaBuilder(ref, spec, query, grain, context).sql;
+        }
+        const builder = this.buildBaseQuery(ref, spec, ref.dataset, query, grain, context);
+        return builder.toSQLWithParams().sql;
+    }
+    /**
+     * Validate a metric query against the metric's contract.
+     */
+    validate(metric, query) {
+        return validateQuery(metric, query);
+    }
+    // ---------------------------------------------------------------------------
+    // Query builder path
+    // ---------------------------------------------------------------------------
+    async runViaBuilder(metric, query, context, start) {
+        const ref = metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+        const grain = metric.__type === 'grained_metric_ref' ? metric.grain : query.by ?? undefined;
+        const spec = ref.spec;
+        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        if (spec.__type === 'derived_metric_spec') {
+            // Derived metrics: build CTE via builder, outer query via string, execute via rawQuery
+            const { sql, params } = this.buildDerivedSQLViaBuilder(ref, spec, query, grain, context);
+            const data = await activeBuilderFactory.rawQuery(sql, params);
+            const timingMs = Date.now() - start;
+            return { data, meta: { sql, timingMs, tenant: context?.runtime?.tenant?.id } };
+        }
+        // Base metrics: fully use the builder's execute()
+        const builder = this.buildBaseQuery(ref, spec, ref.dataset, query, grain, context);
+        const { sql } = builder.toSQLWithParams();
+        const data = await builder.execute();
+        const timingMs = Date.now() - start;
+        return { data, meta: { sql, timingMs, tenant: context?.runtime?.tenant?.id } };
+    }
+    buildBaseQuery(ref, spec, ds, query, grain, context) {
+        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        let qb = activeBuilderFactory.table(ds.source);
+        const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain);
+        if (selectParts.length > 0) {
+            qb = qb.select(selectParts);
+        }
+        // Aggregation (appends to select, auto-sets groupBy on non-agg columns)
+        qb = applyAggregationSpec(qb, ds, spec, ref.name);
+        // Explicit groupBy (ensures period + dims are grouped even if aggregation auto-groupBy misses them)
+        if (groupByParts.length > 0) {
+            qb = qb.groupBy(groupByParts);
+        }
+        // Tenant auto-injection
+        const tenantColumn = resolveTenantFilterColumn(ds, context);
+        const tenantId = context?.runtime?.tenant?.id;
+        const tenantHandledByBuilder = context?.runtime?.tenant?.handledByBuilder === true;
+        if (tenantId && tenantColumn && !tenantHandledByBuilder) {
+            qb = qb.where(tenantColumn, 'eq', tenantId);
+        }
+        // User filters
+        for (const filter of query.filters ?? []) {
+            const resolvedField = resolveFilterField(ds, filter.field);
+            qb = qb.where(resolvedField, filter.operator, filter.value);
+        }
+        // Order, limit, offset
+        qb = appendOrderLimitOffset(qb, query.orderBy, grain, query.limit, query.offset);
+        return qb;
+    }
+    buildDerivedSQLViaBuilder(ref, spec, query, grain, context) {
+        const activeBuilderFactory = context?.runtime?.builderFactory ?? this.builderFactory;
+        const ds = ref.dataset;
+        // Build the CTE inner query using the builder
+        let cteBuilder = activeBuilderFactory.table(ds.source);
+        const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain);
+        if (selectParts.length > 0) {
+            cteBuilder = cteBuilder.select(selectParts);
+        }
+        // Base aggregations
+        const refAliases = {};
+        for (const [alias, baseMetric] of Object.entries(spec.uses)) {
+            const baseSpec = baseMetric.spec;
+            if (baseSpec.__type !== 'aggregation_spec') {
+                throw new Error(`Derived metric "${ref.name}" references non-base metric "${alias}".`);
+            }
+            cteBuilder = applyAggregationSpec(cteBuilder, ds, baseSpec, alias);
+            refAliases[alias] = alias;
+        }
+        if (groupByParts.length > 0) {
+            cteBuilder = cteBuilder.groupBy(groupByParts);
+        }
+        // Filters on CTE
+        const tenantColumn = resolveTenantFilterColumn(ds, context);
+        const tenantId = context?.runtime?.tenant?.id;
+        const tenantHandledByBuilder = context?.runtime?.tenant?.handledByBuilder === true;
+        if (tenantId && tenantColumn && !tenantHandledByBuilder) {
+            cteBuilder = cteBuilder.where(tenantColumn, 'eq', tenantId);
+        }
+        for (const filter of query.filters ?? []) {
+            const resolvedField = resolveFilterField(ds, filter.field);
+            cteBuilder = cteBuilder.where(resolvedField, filter.operator, filter.value);
+        }
+        const { sql: cteSql, parameters: cteParams } = cteBuilder.toSQLWithParams();
+        // Outer query: trivial SELECT from the CTE — stays as string concat
+        // because table('base') would fail schema typing
+        const outerSelectParts = [];
+        if (grain)
+            outerSelectParts.push('period');
+        for (const dim of query.dimensions ?? []) {
+            validateSQLIdentifier(dim, 'dimension name');
+            outerSelectParts.push(dim);
+        }
+        const formulaExpr = spec.formula(refAliases);
+        validateSQLIdentifier(ref.name, 'metric name');
+        outerSelectParts.push(`${formulaExpr.toSQL()} AS ${ref.name}`);
+        let sql = `WITH base AS (${cteSql}) SELECT ${outerSelectParts.join(', ')} FROM base`;
+        // ORDER BY
+        if (query.orderBy && query.orderBy.length > 0) {
+            const orderParts = query.orderBy.map(o => {
+                validateSQLIdentifier(o.field, 'order by field');
+                return `${o.field} ${o.direction.toUpperCase()}`;
+            });
+            sql += ` ORDER BY ${orderParts.join(', ')}`;
+        }
+        else if (grain) {
+            sql += ' ORDER BY period';
+        }
+        if (query.limit != null) {
+            // Ensure limit is a safe integer
+            const limit = Math.floor(Math.abs(query.limit));
+            sql += ` LIMIT ${limit}`;
+        }
+        if (query.offset != null) {
+            // Ensure offset is a safe integer
+            const offset = Math.floor(Math.abs(query.offset));
+            sql += ` OFFSET ${offset}`;
+        }
+        return { sql, params: cteParams };
+    }
+}

package/dist/field.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Dimension helpers — lightweight semantic markers for dataset dimensions.
+ *
+ * @example
+ * ```ts
+ * import { dimension } from '@hypequery/serve';
+ *
+ * const Orders = dataset("orders", {
+ *   source: "orders",
+ *   dimensions: {
+ *     id: dimension.string(),
+ *     amount: dimension.number({ label: "Amount" }),
+ *     createdAt: dimension.timestamp({ label: "Created At" }),
+ *   },
+ * });
+ * ```
+ */
+import type { DimensionDefinition, DimensionOptions } from './types.js';
+export declare const dimension: {
+    readonly string: (opts?: DimensionOptions) => DimensionDefinition<"string">;
+    readonly number: (opts?: DimensionOptions) => DimensionDefinition<"number">;
+    readonly boolean: (opts?: DimensionOptions) => DimensionDefinition<"boolean">;
+    readonly timestamp: (opts?: DimensionOptions) => DimensionDefinition<"timestamp">;
+};
+//# sourceMappingURL=field.d.ts.map

package/dist/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;AAenF,eAAO,MAAM,SAAS;6BAZL,gBAAgB;6BAAhB,gBAAgB;8BAAhB,gBAAgB;gCAAhB,gBAAgB;CAiBvB,CAAC"}

package/dist/field.js

@@ -0,0 +1,35 @@
+/**
+ * Dimension helpers — lightweight semantic markers for dataset dimensions.
+ *
+ * @example
+ * ```ts
+ * import { dimension } from '@hypequery/serve';
+ *
+ * const Orders = dataset("orders", {
+ *   source: "orders",
+ *   dimensions: {
+ *     id: dimension.string(),
+ *     amount: dimension.number({ label: "Amount" }),
+ *     createdAt: dimension.timestamp({ label: "Created At" }),
+ *   },
+ * });
+ * ```
+ */
+function createFieldHelper(fieldType) {
+    return (opts) => ({
+        __type: 'field_definition',
+        fieldType,
+        label: opts?.label,
+        description: opts?.description,
+        column: opts?.column,
+        sql: opts?.sql,
+        filterable: opts?.filterable,
+        groupable: opts?.groupable,
+    });
+}
+export const dimension = {
+    string: createFieldHelper('string'),
+    number: createFieldHelper('number'),
+    boolean: createFieldHelper('boolean'),
+    timestamp: createFieldHelper('timestamp'),
+};

package/dist/formulas.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Formula helpers for derived metrics.
+ *
+ * These are symbolic — they build FormulaExpr objects that get compiled to SQL
+ * by the MetricExecutor. They do not produce raw SQL strings directly.
+ *
+ * @example
+ * ```ts
+ * const avgOrderValue = Orders.metric("avgOrderValue", {
+ *   uses: { revenue: totalRevenue, orders: orderCount },
+ *   formula: ({ revenue, orders }) => divide(revenue, nullIfZero(orders)),
+ * });
+ * ```
+ */
+import type { FormulaExpr } from './types.js';
+export declare function divide(a: string | FormulaExpr, b: string | FormulaExpr): FormulaExpr;
+export declare function multiply(a: string | FormulaExpr, b: string | FormulaExpr): FormulaExpr;
+export declare function subtract(a: string | FormulaExpr, b: string | FormulaExpr): FormulaExpr;
+export declare function add(a: string | FormulaExpr, b: string | FormulaExpr): FormulaExpr;
+export declare function nullIfZero(a: string | FormulaExpr): FormulaExpr;
+export declare function coalesce(a: string | FormulaExpr, fallback: number | string | FormulaExpr): FormulaExpr;
+export declare function round(a: string | FormulaExpr, decimals?: number): FormulaExpr;
+export declare function floor(a: string | FormulaExpr): FormulaExpr;
+export declare function ceil(a: string | FormulaExpr): FormulaExpr;
+//# sourceMappingURL=formulas.d.ts.map

package/dist/formulas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formulas.d.ts","sourceRoot":"","sources":["../src/formulas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgB9C,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAEpF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAEtF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAEtF;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAEjF;AAMD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAE/D;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAGtG;AAMD,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,QAAQ,GAAE,MAAU,GAAG,WAAW,CAEhF;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAE1D;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAEzD"}

package/dist/formulas.js

@@ -0,0 +1,60 @@
+/**
+ * Formula helpers for derived metrics.
+ *
+ * These are symbolic — they build FormulaExpr objects that get compiled to SQL
+ * by the MetricExecutor. They do not produce raw SQL strings directly.
+ *
+ * @example
+ * ```ts
+ * const avgOrderValue = Orders.metric("avgOrderValue", {
+ *   uses: { revenue: totalRevenue, orders: orderCount },
+ *   formula: ({ revenue, orders }) => divide(revenue, nullIfZero(orders)),
+ * });
+ * ```
+ */
+function expr(sqlFn) {
+    return { __type: 'formula_expr', toSQL: sqlFn };
+}
+/** Check if a value is a FormulaExpr. */
+function resolveArg(a) {
+    if (typeof a === 'string')
+        return a;
+    return a.toSQL();
+}
+// ---------------------------------------------------------------------------
+// Arithmetic
+// ---------------------------------------------------------------------------
+export function divide(a, b) {
+    return expr(() => `(${resolveArg(a)}) / (${resolveArg(b)})`);
+}
+export function multiply(a, b) {
+    return expr(() => `(${resolveArg(a)}) * (${resolveArg(b)})`);
+}
+export function subtract(a, b) {
+    return expr(() => `(${resolveArg(a)}) - (${resolveArg(b)})`);
+}
+export function add(a, b) {
+    return expr(() => `(${resolveArg(a)}) + (${resolveArg(b)})`);
+}
+// ---------------------------------------------------------------------------
+// Null handling
+// ---------------------------------------------------------------------------
+export function nullIfZero(a) {
+    return expr(() => `NULLIF(${resolveArg(a)}, 0)`);
+}
+export function coalesce(a, fallback) {
+    const fb = typeof fallback === 'number' ? String(fallback) : resolveArg(fallback);
+    return expr(() => `COALESCE(${resolveArg(a)}, ${fb})`);
+}
+// ---------------------------------------------------------------------------
+// Rounding
+// ---------------------------------------------------------------------------
+export function round(a, decimals = 0) {
+    return expr(() => `ROUND(${resolveArg(a)}, ${decimals})`);
+}
+export function floor(a) {
+    return expr(() => `FLOOR(${resolveArg(a)})`);
+}
+export function ceil(a) {
+    return expr(() => `CEIL(${resolveArg(a)})`);
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { dataset } from './dataset.js';
+export { dimension } from './field.js';
+export { measure } from './measure.js';
+export { belongsTo, hasMany, hasOne } from './relationships.js';
+export { sum, count, countDistinct, avg, min, max } from './aggregations.js';
+export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
+export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
+export { createDatasetRegistry } from './registry.js';
+export { MetricExecutor } from './executor.js';
+export type { MetricExecutorOptions } from './executor.js';
+export type { ValidationResult } from './validation.js';
+export { validateFilterValue, matchesFieldType } from './validation.js';
+export type { QueryBuilderLike, QueryBuilderFactoryLike } from './query-builder-protocol.js';
+export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
+export { GRAIN_FUNCTIONS } from './constants.js';
+export { resolveDimensionExpression, resolveFilterField, buildDimensionSelectionPlan, applyAggregationSpec, applyMeasureDefinition, appendOrderLimitOffset, resolveTenantFilterColumn, } from './query-planner.js';
+export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, MetricResultMeta, MetricResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetQueryConfig, DatasetQueryContract, DatasetQueryRef, DatasetLimits, DatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAG7E,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG7F,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+// Dataset definition
+export { dataset } from './dataset.js';
+// Dimension helpers
+export { dimension } from './field.js';
+// Measure helpers
+export { measure } from './measure.js';
+// Relationship helpers
+export { belongsTo, hasMany, hasOne } from './relationships.js';
+// Aggregation helpers
+export { sum, count, countDistinct, avg, min, max } from './aggregations.js';
+// Formula helpers
+export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
+// Semantic query helpers
+export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
+// Registry
+export { createDatasetRegistry } from './registry.js';
+// Executor
+export { MetricExecutor } from './executor.js';
+export { validateFilterValue, matchesFieldType } from './validation.js';
+// SQL utilities
+export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
+// Constants
+export { GRAIN_FUNCTIONS } from './constants.js';
+// Query planning helpers
+export { resolveDimensionExpression, resolveFilterField, buildDimensionSelectionPlan, applyAggregationSpec, applyMeasureDefinition, appendOrderLimitOffset, resolveTenantFilterColumn, } from './query-planner.js';

package/dist/measure.d.ts

@@ -0,0 +1,10 @@
+import type { MeasureDefinition, MeasureOptions } from './types.js';
+export declare const measure: {
+    readonly sum: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    readonly count: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    readonly countDistinct: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    readonly avg: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    readonly min: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    readonly max: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+};
+//# sourceMappingURL=measure.d.ts.map

package/dist/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAaxF,eAAO,MAAM,OAAO;0BAVH,MAAM,SAAS,cAAc,KAAG,iBAAiB;4BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;oCAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;CAiBxD,CAAC"}

package/dist/measure.js

@@ -0,0 +1,18 @@
+function createMeasureHelper(aggregation) {
+    return (field, opts) => ({
+        __type: 'measure_definition',
+        aggregation,
+        field,
+        sql: opts?.sql,
+        label: opts?.label,
+        description: opts?.description,
+    });
+}
+export const measure = {
+    sum: createMeasureHelper('sum'),
+    count: createMeasureHelper('count'),
+    countDistinct: createMeasureHelper('countDistinct'),
+    avg: createMeasureHelper('avg'),
+    min: createMeasureHelper('min'),
+    max: createMeasureHelper('max'),
+};

package/dist/query-builder-protocol.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Duck-typed protocol interfaces for query builders.
+ *
+ * These interfaces define the minimal contract that a query builder must satisfy
+ * to work with the MetricExecutor. The @hypequery/clickhouse `createQueryBuilder`
+ * return value satisfies `QueryBuilderFactoryLike` structurally — no explicit
+ * `implements` is needed.
+ *
+ * This keeps @hypequery/serve DB-agnostic while enabling first-class builder usage.
+ */
+/** A chainable query builder instance (what `.table(name)` returns). */
+export interface QueryBuilderLike {
+    select(columns: string[] | string): QueryBuilderLike;
+    sum(column: string, alias?: string): QueryBuilderLike;
+    count(column: string, alias?: string): QueryBuilderLike;
+    countDistinct(column: string, alias?: string): QueryBuilderLike;
+    avg(column: string, alias?: string): QueryBuilderLike;
+    min(column: string, alias?: string): QueryBuilderLike;
+    max(column: string, alias?: string): QueryBuilderLike;
+    where(column: string, operator: string, value: unknown): QueryBuilderLike;
+    groupBy(columns: string | string[]): QueryBuilderLike;
+    orderBy(column: string, direction?: 'ASC' | 'DESC'): QueryBuilderLike;
+    limit(count: number): QueryBuilderLike;
+    offset(count: number): QueryBuilderLike;
+    toSQLWithParams(): {
+        sql: string;
+        parameters: unknown[];
+    };
+    execute(): Promise<Record<string, unknown>[]>;
+}
+/** A query builder factory (what `createQueryBuilder(config)` returns). */
+export interface QueryBuilderFactoryLike {
+    table(name: string): QueryBuilderLike;
+    rawQuery<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+//# sourceMappingURL=query-builder-protocol.d.ts.map

package/dist/query-builder-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAGrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAG1E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAGtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGxC,eAAe,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1D,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC/C;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtF"}

package/dist/query-builder-protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Duck-typed protocol interfaces for query builders.
+ *
+ * These interfaces define the minimal contract that a query builder must satisfy
+ * to work with the MetricExecutor. The @hypequery/clickhouse `createQueryBuilder`
+ * return value satisfies `QueryBuilderFactoryLike` structurally — no explicit
+ * `implements` is needed.
+ *
+ * This keeps @hypequery/serve DB-agnostic while enabling first-class builder usage.
+ */
+export {};

package/dist/query-helpers.d.ts

@@ -0,0 +1,30 @@
+import type { MetricFilter, MetricOrderBy } from './types.js';
+export declare function eq<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function neq<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function gt<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function gte<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function lt<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function lte<TField extends string>(field: TField, value: unknown): MetricFilter;
+export declare function inList<TField extends string>(field: TField, value: unknown[]): MetricFilter;
+export declare function notInList<TField extends string>(field: TField, value: unknown[]): MetricFilter;
+export declare function between<TField extends string>(field: TField, lower: unknown, upper: unknown): MetricFilter;
+export declare function like<TField extends string>(field: TField, value: string): MetricFilter;
+export declare function asc<TField extends string>(field: TField): MetricOrderBy;
+export declare function desc<TField extends string>(field: TField): MetricOrderBy;
+export declare const filter: {
+    readonly eq: typeof eq;
+    readonly neq: typeof neq;
+    readonly gt: typeof gt;
+    readonly gte: typeof gte;
+    readonly lt: typeof lt;
+    readonly lte: typeof lte;
+    readonly inList: typeof inList;
+    readonly notInList: typeof notInList;
+    readonly between: typeof between;
+    readonly like: typeof like;
+};
+export declare const order: {
+    readonly asc: typeof asc;
+    readonly desc: typeof desc;
+};
+//# sourceMappingURL=query-helpers.d.ts.map

package/dist/query-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-helpers.d.ts","sourceRoot":"","sources":["../src/query-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAU9D,wBAAgB,EAAE,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAErF;AAED,wBAAgB,GAAG,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAEtF;AAED,wBAAgB,EAAE,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAErF;AAED,wBAAgB,GAAG,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAEtF;AAED,wBAAgB,EAAE,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAErF;AAED,wBAAgB,GAAG,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAEtF;AAED,wBAAgB,MAAM,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,YAAY,CAE3F;AAED,wBAAgB,SAAS,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,YAAY,CAE9F;AAED,wBAAgB,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAE1G;AAED,wBAAgB,IAAI,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEtF;AAED,wBAAgB,GAAG,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAEvE;AAED,wBAAgB,IAAI,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAExE;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAC;AAEX,eAAO,MAAM,KAAK;;;CAGR,CAAC"}

package/dist/query-helpers.js

@@ -0,0 +1,55 @@
+function createFilter(field, operator, value) {
+    return { field, operator, value };
+}
+export function eq(field, value) {
+    return createFilter(field, 'eq', value);
+}
+export function neq(field, value) {
+    return createFilter(field, 'neq', value);
+}
+export function gt(field, value) {
+    return createFilter(field, 'gt', value);
+}
+export function gte(field, value) {
+    return createFilter(field, 'gte', value);
+}
+export function lt(field, value) {
+    return createFilter(field, 'lt', value);
+}
+export function lte(field, value) {
+    return createFilter(field, 'lte', value);
+}
+export function inList(field, value) {
+    return createFilter(field, 'in', value);
+}
+export function notInList(field, value) {
+    return createFilter(field, 'notIn', value);
+}
+export function between(field, lower, upper) {
+    return createFilter(field, 'between', [lower, upper]);
+}
+export function like(field, value) {
+    return createFilter(field, 'like', value);
+}
+export function asc(field) {
+    return { field, direction: 'asc' };
+}
+export function desc(field) {
+    return { field, direction: 'desc' };
+}
+export const filter = {
+    eq,
+    neq,
+    gt,
+    gte,
+    lt,
+    lte,
+    inList,
+    notInList,
+    between,
+    like,
+};
+export const order = {
+    asc,
+    desc,
+};

package/dist/query-planner.d.ts

@@ -0,0 +1,13 @@
+import type { AggregationSpec, DatasetInstance, ExecutionContext, MeasureDefinition, MetricOrderBy, TimeGrain } from "./types.js";
+import type { QueryBuilderLike } from "./query-builder-protocol.js";
+export declare function resolveDimensionExpression(ds: DatasetInstance, dimensionName: string): string;
+export declare function resolveFilterField(ds: DatasetInstance, filterField: string): string;
+export declare function buildDimensionSelectionPlan(ds: DatasetInstance, dimensions: string[], grain: TimeGrain | undefined): {
+    selectParts: string[];
+    groupByParts: string[];
+};
+export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetInstance, spec: AggregationSpec, alias: string): QueryBuilderLike;
+export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetInstance, name: string, definition: MeasureDefinition): QueryBuilderLike;
+export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit?: number, offset?: number): QueryBuilderLike;
+export declare function resolveTenantFilterColumn(_ds: DatasetInstance, context?: ExecutionContext): string | undefined;
+//# sourceMappingURL=query-planner.d.ts.map

package/dist/query-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,eAAe,EACnB,aAAa,EAAE,MAAM,GACpB,MAAM,CAGR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,eAAe,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAGR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,GAC3B;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,eAAe,EACnB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAmBlB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,eAAe,EACnB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,GAC5B,gBAAgB,CAmBlB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB,CAiBlB;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAEpB"}