@hypequery/datasets 0.20.0 → 0.22.0

package/dist/utils/clickhouse-dataset-sql-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse-dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,EAAE,iBAGxC,CAAC"}

package/dist/utils/clickhouse-dataset-sql-dialect.js

@@ -0,0 +1,6 @@
+import { quoteSQLIdentifier } from '../sql-utils.js';
+/** Preserve the existing ClickHouse spelling and escaping byte for byte. */
+export const clickhouseDatasetSqlDialect = Object.freeze({
+    name: 'clickhouse',
+    quoteIdentifier: quoteSQLIdentifier,
+});

package/dist/utils/compile-dataset-query.d.ts

@@ -0,0 +1,10 @@
+import type { DatasetCompilation } from '../dataset-compilation.js';
+import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+export interface PreparedDatasetQuery {
+    readonly compilation: DatasetCompilation;
+    execute(): Promise<Record<string, unknown>[]>;
+}
+/** The one dispatch point for dataset preview and query-builder execution. */
+export declare function prepareDatasetQuery(dataset: AnyDatasetInstance, input: DatasetQuery, options: DatasetQueryExecutionOptions, mode?: 'execution' | 'logical'): PreparedDatasetQuery;
+//# sourceMappingURL=compile-dataset-query.d.ts.map

package/dist/utils/compile-dataset-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-dataset-query.d.ts","sourceRoot":"","sources":["../../src/utils/compile-dataset-query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAA2D,MAAM,2BAA2B,CAAC;AAC7H,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC/C;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,WAAW,GAAG,SAAuB,GAC1C,oBAAoB,CA4DtB"}

package/dist/utils/compile-dataset-query.js

@@ -0,0 +1,71 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
+import { buildDatasetQueryBuilder } from './build-dataset-query-builder.js';
+import { baseMeasureNames } from './dataset-measures.js';
+import { buildDerivedDatasetSql, hasSelectedDerivedMeasure } from './dataset-derived-query.js';
+import { measureDependencyNames } from './measure-dependencies.js';
+import { overfetchLimit } from './pagination.js';
+import { resolveResultLimit } from './result-limits.js';
+import { buildTimeMeasureDatasetSql } from './time-measure-dataset-sql.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+/** The one dispatch point for dataset preview and query-builder execution. */
+export function prepareDatasetQuery(dataset, input, options, mode = 'execution') {
+    const query = structuredClone({
+        ...input,
+        limit: mode === 'execution' ? resolveResultLimit(input.limit, dataset.limits).limit : input.limit,
+    });
+    // Preserve omission while validating/planning: maxMeasures constrains an
+    // explicit selection, not the dataset's default set of base measures.
+    const measures = query.measures ?? baseMeasureNames(dataset.measures);
+    const executionLimit = mode === 'execution' ? overfetchLimit(query.limit) : query.limit;
+    const executionOptions = { ...options, executionLimit };
+    const preflightStatements = [];
+    let statement;
+    let execute;
+    let plan;
+    const abortSignal = options.context?.abortSignal;
+    if (selectedTimeMeasures(dataset, query).size) {
+        plan = 'time';
+        const compiled = buildTimeMeasureDatasetSql(dataset, query, executionOptions);
+        statement = compiled;
+        preflightStatements.push({ sql: compiled.timeAxisSql, parameters: compiled.parameters });
+        execute = async () => {
+            await options.builderFactory.rawQuery(compiled.timeAxisSql, compiled.parameters, { abortSignal });
+            return options.builderFactory.rawQuery(compiled.sql, compiled.parameters, { abortSignal });
+        };
+    }
+    else if (hasSelectedDerivedMeasure(dataset, query)) {
+        plan = 'derived';
+        statement = buildDerivedDatasetSql(dataset, query, executionOptions, buildDatasetQueryBuilder);
+        execute = () => options.builderFactory.rawQuery(statement.sql, statement.parameters, { abortSignal });
+    }
+    else {
+        plan = 'aggregate';
+        const builder = buildDatasetQueryBuilder(dataset, query, executionOptions);
+        statement = builder.toSQLWithParams();
+        // Retain builder execution: custom builders may carry adapter settings.
+        execute = () => builder.execute({ abortSignal });
+    }
+    const description = Object.freeze({
+        kind: 'dataset-compilation', version: 1, dataset: dataset.name, plan,
+        dimensions: Object.freeze([...(query.dimensions ?? [])]),
+        measures: Object.freeze([...measures]),
+        measureDependencies: Object.freeze(measureDependencyNames(queryMeasureDefinitions(dataset, measures), measures)),
+        filters: Object.freeze((query.filters ?? []).map(({ field, operator }) => Object.freeze({ field, operator }))),
+        segments: Object.freeze([...(query.segments ?? [])]),
+        by: query.by, timezone: query.timezone,
+        effectiveLimit: query.limit, executionLimit, offset: query.offset ?? 0,
+        parameterCount: statement.parameters.length,
+        preflightStatementCount: preflightStatements.length,
+    });
+    const compilation = Object.freeze({
+        sql: statement.sql,
+        parameters: Object.freeze(structuredClone(statement.parameters)),
+        query: Object.freeze(structuredClone({ ...query, measures })),
+        preflightStatements: Object.freeze(preflightStatements.map(preflight => Object.freeze({
+            sql: preflight.sql, parameters: Object.freeze(structuredClone(preflight.parameters)),
+        }))),
+        describe: () => description,
+        toJSON: () => description,
+    });
+    return { compilation, execute };
+}

package/dist/utils/composite-time-measure-sql.d.ts

@@ -0,0 +1,10 @@
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+import type { TimeMeasureAxis } from './time-measure-axis.js';
+/** Aggregate each dependency in its evaluation context, then evaluate formulas. */
+export declare function buildCompositeTimeMeasureSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, axis: TimeMeasureAxis): {
+    sql: string;
+    parameters: unknown[];
+    timeAxisSql: string;
+};
+//# sourceMappingURL=composite-time-measure-sql.d.ts.map

package/dist/utils/composite-time-measure-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-time-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/composite-time-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW9D,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,4BAA4B,EAAE,IAAI,EAAE,eAAe;;;;EAgDrJ"}

package/dist/utils/composite-time-measure-sql.js

@@ -0,0 +1,61 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
+import { quoteSQLIdentifier } from '../sql-utils.js';
+import { isDerivedMeasure, isWindowMeasure } from './dataset-measures.js';
+import { buildMeasureEvaluationGraph, evaluationFormula } from './measure-evaluation-graph.js';
+import { buildTimeMeasureSourceSql } from './time-measure-source-sql.js';
+import { buildTimeMeasureAxisSql } from './time-measure-axis-sql.js';
+import { timeMeasureContextCtes, timeMeasureContextGuard } from './time-measure-context-sql.js';
+import { timeMeasureLeafSql } from './time-measure-leaf-sql.js';
+import { derivedProjection } from './derived-measure-sql.js';
+import { buildTimeMeasureResultSql } from './time-measure-result-sql.js';
+/** Aggregate each dependency in its evaluation context, then evaluate formulas. */
+export function buildCompositeTimeMeasureSql(ds, query, options, axis) {
+    const graph = buildMeasureEvaluationGraph(queryMeasureDefinitions(ds, query.measures ?? []), query.measures ?? []);
+    const leaves = graph.nodes.filter(node => !isDerivedMeasure(node.definition));
+    const baseNames = new Set(leaves.map(node => isWindowMeasure(node.definition) ? node.definition.measure : node.name));
+    const source = buildTimeMeasureSourceSql(ds, query, baseNames, axis.filters, options);
+    const timeAxis = buildTimeMeasureAxisSql(source, axis);
+    const contexts = timeMeasureContextCtes(graph.contexts, axis);
+    const inputs = leaves.map(node => {
+        const window = isWindowMeasure(node.definition) ? node.definition : undefined;
+        const base = source.bases.find(base => base.name === (window?.measure ?? node.name));
+        return { node, ...timeMeasureLeafSql(node.id, node.context, base, window, axis, source.dimensions) };
+    });
+    const keys = source.dimensions.map(dim => dim.alias);
+    const combinations = keys.length ? ` CROSS JOIN (SELECT DISTINCT ${keys.join(', ')} FROM (${inputs.map(input => `SELECT ${keys.join(', ')} FROM ${input.population}`).join(' UNION ALL ')})) AS _hq_combinations` : '';
+    const guardCtes = [...source.ctes, ...timeAxis.ctes, ...contexts, ...inputs.flatMap(input => input.ctes)];
+    const ctes = [...guardCtes,
+        `_hq_skeleton AS (SELECT * FROM _hq_series${combinations})`];
+    let previous = '_hq_skeleton';
+    for (const input of inputs) {
+        const { node } = input;
+        const output = `_hq_value${node.id}`;
+        const next = `_hq_evaluated${node.id}`;
+        const value = input.count ? `coalesce(m.${output}, 0)` : `m.${output}`;
+        if (input.cumulative) {
+            const partition = keys.length ? `tuple(${keys.map(key => `s.${key}`).join(', ')})` : 'tuple(0)';
+            const lookup = `_hq_lookup${node.id}`;
+            ctes.push(`${lookup} AS (SELECT s.*, c._hq_eval_end, ${partition} AS _hq_partition FROM ${previous} AS s INNER JOIN _hq_context${input.context} AS c ON s._hq_period = c._hq_period)`);
+            ctes.push(`${next} AS (SELECT s.* EXCEPT (_hq_eval_end, _hq_partition), ${value} AS ${output} FROM ${lookup} AS s LEFT ASOF JOIN ${input.aggregate} AS m ON s._hq_partition = m._hq_partition AND s._hq_eval_end > m._hq_time)`);
+        }
+        else {
+            const condition = ['s._hq_period = m._hq_period', ...keys.map(key => `isNotDistinctFrom(s.${key}, m.${key})`)];
+            ctes.push(`${next} AS (SELECT s.*, ${value} AS ${output} FROM ${previous} AS s LEFT JOIN ${input.aggregate} AS m ON ${condition.join(' AND ')})`);
+        }
+        previous = next;
+    }
+    for (const node of graph.nodes.filter(node => isDerivedMeasure(node.definition))) {
+        const next = `_hq_formula${node.id}`;
+        ctes.push(`${next} AS (SELECT *, ${derivedProjection(`_hq_value${node.id}`, evaluationFormula(node))} FROM ${previous})`);
+        previous = next;
+    }
+    const projections = ['v._hq_period AS period', ...source.dimensions.map(dim => `v.${dim.alias} AS ${quoteSQLIdentifier(dim.name)}`),
+        ...Object.entries(graph.outputs).map(([name, id]) => `v._hq_value${id} AS ${quoteSQLIdentifier(name)}`)];
+    ctes.push(`_hq_values AS (SELECT ${projections.join(', ')} FROM ${previous} AS v)`);
+    const guard = [timeAxis.guard, timeAxis.rangeGuard, ...graph.contexts.map(context => timeMeasureContextGuard(context, axis)), ...inputs.map(input => input.guard)].join(' + ');
+    return {
+        sql: buildTimeMeasureResultSql(ds, query, options, source.dimensions, ctes, guard, true),
+        parameters: source.parameters,
+        timeAxisSql: `WITH ${guardCtes.join(',\n')} SELECT ${guard} AS _hq_validated FROM _hq_bounds`,
+    };
+}

package/dist/utils/dataset-derived-query.d.ts

@@ -1,4 +1,4 @@
-import type { AnyDatasetInstance, DatasetQuery, DatasetQueryResult } from '../types.js';
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
 import type { QueryBuilderLike } from '../query-builder-protocol.js';
 import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
 type BuildBaseQuery = (dataset: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions) => QueryBuilderLike;
@@ -7,6 +7,5 @@ export declare function buildDerivedDatasetSql(ds: AnyDatasetInstance, query: Da
     sql: string;
     parameters: unknown[];
 };
-export declare function runDerivedDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, buildBaseQuery: BuildBaseQuery): Promise<DatasetQueryResult>;
 export {};
 //# sourceMappingURL=dataset-derived-query.d.ts.map

package/dist/utils/dataset-derived-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CA2CxC;AAED,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAgB7B"}
+{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CA4CxC"}

package/dist/utils/dataset-derived-query.js

@@ -1,9 +1,10 @@
-import { derivedProjection } from './derived-measure-sql.js';
+import { queryMeasureDefinitions } from './relationship-measures.js';
+import { semanticOrderDirection } from './semantic-query-syntax.js';
+import { measureDependencyNames } from './measure-dependencies.js';
+import { derivedExpressionSql } from './derived-measure-sql.js';
 import { baseMeasureNames, getBaseMeasure, getDerivedMeasure } from './dataset-measures.js';
-import { quoteSQLIdentifier } from '../sql-utils.js';
+import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
 import { validateDatasetQueryInput } from './dataset-query-validation.js';
-import { overfetchLimit } from './pagination.js';
-import { toDatasetQueryResult } from './dataset-query-result.js';
 export function hasSelectedDerivedMeasure(ds, query) {
     return (query.measures ?? []).some(name => getDerivedMeasure(ds.measures, name) !== undefined);
 }
@@ -12,13 +13,13 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     if (!validation.valid) {
         throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
     }
+    const dialect = resolveDatasetSqlDialect(options.builderFactory);
     const selected = query.measures ?? baseMeasureNames(ds.measures);
-    const baseMeasures = new Set(selected.filter(name => getBaseMeasure(ds.measures, name) !== undefined));
-    for (const name of selected) {
+    const baseMeasures = measureDependencyNames(queryMeasureDefinitions(ds, selected), selected).filter(name => name.includes('.') || getBaseMeasure(ds.measures, name));
+    const resolve = (name) => {
         const derived = getDerivedMeasure(ds.measures, name);
-        if (derived)
-            Object.values(derived.uses).forEach(base => baseMeasures.add(base));
-    }
+        return derived ? `(${derivedExpressionSql(derived, resolve)})` : dialect.quoteIdentifier(name);
+    };
     const inner = buildBaseQuery(ds, {
         ...query,
         measures: [...baseMeasures],
@@ -29,21 +30,21 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     const { sql: innerSql, parameters } = inner.toSQLWithParams();
     const projections = [];
     if (query.by)
-        projections.push(quoteSQLIdentifier('period'));
+        projections.push(dialect.quoteIdentifier('period'));
     for (const dimension of query.dimensions ?? [])
-        projections.push(quoteSQLIdentifier(dimension));
+        projections.push(dialect.quoteIdentifier(dimension));
     for (const name of selected) {
         const derived = getDerivedMeasure(ds.measures, name);
         projections.push(derived
-            ? derivedProjection(name, derived)
-            : quoteSQLIdentifier(name));
+            ? `${derivedExpressionSql(derived, resolve)} AS ${dialect.quoteIdentifier(name)}`
+            : dialect.quoteIdentifier(name));
     }
     let sql = `WITH base AS (${innerSql}) SELECT ${projections.join(', ')} FROM base`;
     if (query.orderBy?.length) {
-        sql += ` ORDER BY ${query.orderBy.map(order => (`${quoteSQLIdentifier(order.field)} ${order.direction === 'asc' ? 'ASC' : 'DESC'}`)).join(', ')}`;
+        sql += ` ORDER BY ${query.orderBy.map(order => (`${dialect.quoteIdentifier(order.field)} ${semanticOrderDirection(order.direction)}`)).join(', ')}`;
     }
     else if (query.by) {
-        sql += ` ORDER BY ${quoteSQLIdentifier('period')} ASC`;
+        sql += ` ORDER BY ${dialect.quoteIdentifier('period')} ASC`;
     }
     const limit = options.executionLimit ?? query.limit;
     if (limit !== undefined)
@@ -52,18 +53,3 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
         sql += ` OFFSET ${query.offset}`;
     return { sql, parameters };
 }
-export async function runDerivedDatasetQuery(ds, query, options, buildBaseQuery) {
-    const start = Date.now();
-    const { sql, parameters } = buildDerivedDatasetSql(ds, query, {
-        ...options,
-        executionLimit: overfetchLimit(query.limit),
-    }, buildBaseQuery);
-    const rows = await options.builderFactory.rawQuery(sql, parameters, { abortSignal: options.context?.abortSignal });
-    return toDatasetQueryResult(rows, {
-        dataset: ds,
-        query,
-        sql,
-        timingMs: Date.now() - start,
-        context: options.context,
-    });
-}

package/dist/utils/dataset-filter-types.d.ts

@@ -0,0 +1,28 @@
+import type { DatasetInstance, DimensionDefinition, MetricFilter, MetricFilterOperator, RelationshipDefinition, SemanticFilterDefinition, SemanticFiltersDefinition } from '../types.js';
+/** The generated allowlist mirrors normalizeFilters; explicit maps replace it. */
+export type NormalizedDatasetFilters<TDimensions extends Record<string, DimensionDefinition>, TFilters extends SemanticFiltersDefinition | undefined> = TFilters extends SemanticFiltersDefinition ? TFilters : {
+    [K in keyof TDimensions as TDimensions[K] extends {
+        filterable: false;
+    } ? never : K]: SemanticFilterDefinition & {
+        field: K & string;
+    };
+};
+type FilterOperators<TDefinition> = TDefinition extends {
+    operators: readonly (infer TOperator extends MetricFilterOperator)[];
+} ? TOperator : MetricFilterOperator;
+type LocalFilterFor<TFilters extends SemanticFiltersDefinition> = {
+    [K in keyof TFilters & string]: K extends `${string}.${string}` ? never : MetricFilter<K, unknown, FilterOperators<TFilters[K]>>;
+}[keyof TFilters & string];
+type RelationshipFilterFor<TRelationships extends Record<string, RelationshipDefinition>> = {
+    [R in keyof TRelationships & string]: TRelationships[R] extends RelationshipDefinition<infer TTarget, infer TKind> ? TKind extends 'hasMany' ? never : TTarget extends DatasetInstance<any, any, any, any> ? {
+        [K in keyof TTarget['filters'] & keyof TTarget['dimensions'] & string]: TTarget['dimensions'][K] extends {
+            sql: string;
+        } ? never : K extends TTarget['filters'][K]['field'] ? MetricFilter<`${R}.${K}`, unknown, FilterOperators<TTarget['filters'][K]>> : never;
+    }[keyof TTarget['filters'] & keyof TTarget['dimensions'] & string] : never : never;
+}[keyof TRelationships & string];
+/** Filter names and operator policies exposed by a dataset and its to-one targets. */
+export type DatasetFilterFor<TDataset extends DatasetInstance<any, any, any, any>> = LocalFilterFor<TDataset['filters']> | RelationshipFilterFor<TDataset['relationships']>;
+/** Names in the normalized filter allowlist, including one-hop relationship filters. */
+export type DatasetFilterNames<TDataset extends DatasetInstance<any, any, any, any>> = DatasetFilterFor<TDataset>['field'];
+export {};
+//# sourceMappingURL=dataset-filter-types.d.ts.map

package/dist/utils/dataset-filter-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-filter-types.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-filter-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,kFAAkF;AAClF,MAAM,MAAM,wBAAwB,CAClC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,QAAQ,SAAS,yBAAyB,GAAG,SAAS,IACpD,QAAQ,SAAS,yBAAyB,GAAG,QAAQ,GAAG;KACzD,CAAC,IAAI,MAAM,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS;QAAE,UAAU,EAAE,KAAK,CAAA;KAAE,GAAG,KAAK,GAAG,CAAC,GAAG,wBAAwB,GAAG;QAC/G,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;KACnB;CACF,CAAC;AAEF,KAAK,eAAe,CAAC,WAAW,IAAI,WAAW,SAAS;IACtD,SAAS,EAAE,SAAS,CAAC,MAAM,SAAS,SAAS,oBAAoB,CAAC,EAAE,CAAC;CACtE,GAAG,SAAS,GAAG,oBAAoB,CAAC;AAErC,KAAK,cAAc,CAAC,QAAQ,SAAS,yBAAyB,IAAI;KAC/D,CAAC,IAAI,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,GAC3D,KAAK,GACL,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3D,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC;AAE3B,KAAK,qBAAqB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,IAAI;KACzF,CAAC,IAAI,MAAM,cAAc,GAAG,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,sBAAsB,CAAC,MAAM,OAAO,EAAE,MAAM,KAAK,CAAC,GAC9G,KAAK,SAAS,SAAS,GAAG,KAAK,GAC7B,OAAO,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACjD;SACC,CAAC,IAAI,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,GACnE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,KAAK,GACpD,CAAC,SAAS,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GACtC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1E,KAAK;KACd,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,GAChE,KAAK,GACT,KAAK;CACV,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC;AAEjC,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,CAAC,QAAQ,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAC7E,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GACnC,qBAAqB,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC;AAErD,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IACjF,gBAAgB,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC"}

package/dist/utils/dataset-filter-types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/dataset-query-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAiB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAmKlB"}
+{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAiB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAuKlB"}

package/dist/utils/dataset-query-validation.js

@@ -1,3 +1,5 @@
+import { resolveRelationshipMeasure } from './relationship-measures.js';
+import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 import { queryTimezoneErrors } from './query-timezone.js';
 import { baseMeasureNames } from './dataset-measures.js';
 import { validateFilterValue } from '../validation.js';
@@ -8,11 +10,16 @@ import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './r
 import { segmentSelectionErrors } from './segments.js';
 import { analyzeTimeMeasureAxis } from './time-measure-axis.js';
 export function validateDatasetQueryInput(ds, query, context) {
-    const errors = queryTimezoneErrors(query.timezone);
+    const errors = [...semanticQuerySyntaxErrors(query), ...queryTimezoneErrors(query.timezone)];
     const dimensionNames = Object.keys(ds.dimensions);
     const measureNames = Object.keys(ds.measures);
     const selectedDimensions = query.dimensions ?? [];
     const selectedMeasures = query.measures ?? baseMeasureNames(ds.measures);
+    for (const name of selectedDimensions) {
+        if (selectedMeasures.includes(name)) {
+            errors.push(`Output "${name}" cannot be selected as both a dimension and a measure. Select one or give the definitions distinct names.`);
+        }
+    }
     const filterNames = Object.keys(ds.filters);
     const orderableFields = new Set([
         ...selectedDimensions,
@@ -47,7 +54,12 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (query.measures) {
         for (const measure of query.measures) {
             if (isQualifiedField(measure)) {
-                errors.push(`Measure "${measure}" is relationship-qualified. Measures can only be defined on the base dataset "${ds.name}", not traversed through relationships.`);
+                try {
+                    resolveRelationshipMeasure(ds, measure);
+                }
+                catch (error) {
+                    errors.push(error.message);
+                }
                 continue;
             }
             if (!measureNames.includes(measure)) {
@@ -95,7 +107,7 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (query.orderBy) {
         const invalid = [];
         for (const order of query.orderBy) {
-            if (isQualifiedField(order.field)) {
+            if (isQualifiedField(order.field) && !selectedMeasures.includes(order.field)) {
                 const resolution = resolveQualifiedField(ds, order.field);
                 if (resolution?.error) {
                     errors.push(resolution.error);

package/dist/utils/dataset-sql-dialect.d.ts

@@ -0,0 +1,5 @@
+import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+import type { QueryBuilderFactoryInput } from '../query-builder-protocol.js';
+/** Resolve from the active factory, so a runtime builder override carries its dialect. */
+export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialect;
+//# sourceMappingURL=dataset-sql-dialect.d.ts.map

package/dist/utils/dataset-sql-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE7F"}

package/dist/utils/dataset-sql-dialect.js

@@ -0,0 +1,5 @@
+import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
+/** Resolve from the active factory, so a runtime builder override carries its dialect. */
+export function resolveDatasetSqlDialect(factory) {
+    return factory.datasetSqlDialect ?? clickhouseDatasetSqlDialect;
+}

package/dist/utils/dataset-target.d.ts

@@ -0,0 +1,3 @@
+import type { AnyDatasetInstance } from '../types.js';
+export declare function isDatasetInstance(target: unknown): target is AnyDatasetInstance;
+//# sourceMappingURL=dataset-target.d.ts.map

package/dist/utils/dataset-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-target.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,kBAAkB,CAE/E"}

package/dist/utils/dataset-target.js

@@ -0,0 +1,3 @@
+export function isDatasetInstance(target) {
+    return !!target && typeof target === 'object' && '__type' in target && target.__type === 'dataset';
+}

package/dist/utils/derived-measure-sql.d.ts

@@ -1,3 +1,4 @@
 import type { DerivedMeasureDefinition } from '../types.js';
+export declare function derivedExpressionSql(definition: DerivedMeasureDefinition, resolve?: (name: string) => string): string;
 export declare function derivedProjection(name: string, definition: DerivedMeasureDefinition): string;
 //# sourceMappingURL=derived-measure-sql.d.ts.map

package/dist/utils/derived-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derived-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAyC5D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAG5F"}
+{"version":3,"file":"derived-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAyC5D,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,wBAAwB,EAAE,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAA2B,GAAG,MAAM,CAGzI;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,GAAG,MAAM,CAE5F"}

package/dist/utils/derived-measure-sql.js

@@ -1,12 +1,12 @@
 import { quoteSQLIdentifier } from '../sql-utils.js';
-function expressionSql(expression, uses) {
+function expressionSql(expression, uses, resolve) {
     switch (expression.kind) {
         case 'ref': {
             if (!Object.hasOwn(uses, expression.name)) {
                 throw new Error(`Formula references undeclared input "${expression.name}".`);
             }
             const measureName = uses[expression.name];
-            return quoteSQLIdentifier(measureName);
+            return resolve(measureName);
         }
         case 'literal': {
             if (expression.value === null)
@@ -25,10 +25,10 @@ function expressionSql(expression, uses) {
             const operator = operators[expression.operator];
             if (!operator)
                 throw new Error('Formula contains an unsupported binary operator.');
-            return `(${expressionSql(expression.left, uses)} ${operator} ${expressionSql(expression.right, uses)})`;
+            return `(${expressionSql(expression.left, uses, resolve)} ${operator} ${expressionSql(expression.right, uses, resolve)})`;
         }
         case 'function': {
-            const args = expression.args.map(arg => expressionSql(arg, uses));
+            const args = expression.args.map(arg => expressionSql(arg, uses, resolve));
             switch (expression.name) {
                 case 'nullIfZero': return `NULLIF(${args[0]}, 0)`;
                 case 'coalesce': return `COALESCE(${args.join(', ')})`;
@@ -40,7 +40,10 @@ function expressionSql(expression, uses) {
         }
     }
 }
-export function derivedProjection(name, definition) {
+export function derivedExpressionSql(definition, resolve = quoteSQLIdentifier) {
     const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
-    return `${expressionSql(definition.formula(aliases).expression, definition.uses)} AS ${quoteSQLIdentifier(name)}`;
+    return expressionSql(definition.formula(aliases).expression, definition.uses, resolve);
+}
+export function derivedProjection(name, definition) {
+    return `${derivedExpressionSql(definition)} AS ${quoteSQLIdentifier(name)}`;
 }

package/dist/utils/derived-measure-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derived-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,aAAa,CAAC;AAmHrB,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GACjD,IAAI,CAmDN"}
+{"version":3,"file":"derived-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,aAAa,CAAC;AA8FrB,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GACjD,IAAI,CAgDN"}

package/dist/utils/derived-measure-validation.js

@@ -1,3 +1,4 @@
+import { assertMeasureDependenciesAcyclic } from './measure-dependencies.js';
 import { isSafeSQLIdentifier } from '../sql-utils.js';
 import { splitDatasetMeasures } from './dataset-measures.js';
 function fail(datasetName, measureName, detail) {
@@ -71,27 +72,8 @@ function evaluateFormula(datasetName, measureName, definition) {
     }
     return formula;
 }
-function assertAcyclic(datasetName, derivedMeasures) {
-    const visiting = new Set();
-    const visited = new Set();
-    const visit = (name) => {
-        if (visiting.has(name))
-            fail(datasetName, name, 'contains a dependency cycle.');
-        if (visited.has(name))
-            return;
-        if (!Object.hasOwn(derivedMeasures, name))
-            return;
-        const definition = derivedMeasures[name];
-        visiting.add(name);
-        Object.values(definition.uses).forEach(dependency => visit(dependency));
-        visiting.delete(name);
-        visited.add(name);
-    };
-    Object.keys(derivedMeasures).forEach(visit);
-}
 export function validateDerivedMeasures(datasetName, measures) {
-    const { base: baseMeasures, derived: derivedMeasures, windows, shifts } = splitDatasetMeasures(measures);
-    const timeMeasureNames = new Set([...Object.keys(windows), ...Object.keys(shifts)]);
+    const { derived: derivedMeasures } = splitDatasetMeasures(measures);
     for (const [measureName, definition] of Object.entries(derivedMeasures)) {
         if (!isSafeSQLIdentifier(measureName)) {
             fail(datasetName, measureName, 'name is not a safe identifier.');
@@ -103,7 +85,7 @@ export function validateDerivedMeasures(datasetName, measures) {
             fail(datasetName, measureName, 'must declare an input map.');
         }
     }
-    assertAcyclic(datasetName, derivedMeasures);
+    assertMeasureDependenciesAcyclic(datasetName, measures);
     for (const [measureName, definition] of Object.entries(derivedMeasures)) {
         const uses = Object.entries(definition.uses);
         if (uses.length === 0)
@@ -116,10 +98,7 @@ export function validateDerivedMeasures(datasetName, measures) {
             if (typeof dependencyName !== 'string' || dependencyName.includes('.')) {
                 fail(datasetName, measureName, `references cross-dataset measure "${String(dependencyName)}".`);
             }
-            if (Object.hasOwn(derivedMeasures, dependencyName)) {
-                fail(datasetName, measureName, `references derived measure "${dependencyName}"; v1 inputs must be base measures.`);
-            }
-            if (!Object.hasOwn(baseMeasures, dependencyName) && !timeMeasureNames.has(dependencyName)) {
+            if (!Object.hasOwn(measures, dependencyName)) {
                 fail(datasetName, measureName, `references missing measure "${dependencyName}".`);
             }
         }

package/dist/utils/filter-definition.d.ts

@@ -0,0 +1,3 @@
+import type { MetricFilter, MetricFilterOperator } from '../types.js';
+export declare function createFilter<const TField extends string, const TValue, TOperator extends MetricFilterOperator>(field: TField, operator: TOperator, value: TValue): MetricFilter<TField, TValue, TOperator>;
+//# sourceMappingURL=filter-definition.d.ts.map

package/dist/utils/filter-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-definition.d.ts","sourceRoot":"","sources":["../../src/utils/filter-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEtE,wBAAgB,YAAY,CAC1B,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,MAAM,EACZ,SAAS,SAAS,oBAAoB,EACtC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAE5F"}

package/dist/utils/filter-definition.js

@@ -0,0 +1,3 @@
+export function createFilter(field, operator, value) {
+    return { field, operator, value };
+}

package/dist/utils/measure-dependencies.d.ts

@@ -0,0 +1,8 @@
+import type { DatasetMeasureDefinition, MeasureDefinition } from '../types.js';
+export declare function measureDependencies(definition: DatasetMeasureDefinition): string[];
+/** Dependency order, with each shared input visited once. */
+export declare function measureDependencyNames(measures: Readonly<Record<string, DatasetMeasureDefinition>>, selected: readonly string[]): string[];
+export declare function assertMeasureDependenciesAcyclic(dataset: string, measures: Readonly<Record<string, DatasetMeasureDefinition>>): void;
+/** Wrappers inherit aggregation metadata only when their input has one. */
+export declare function inheritedBaseMeasure(measures: Readonly<Record<string, DatasetMeasureDefinition>>, name: string): MeasureDefinition | undefined;
+//# sourceMappingURL=measure-dependencies.d.ts.map

package/dist/utils/measure-dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-dependencies.d.ts","sourceRoot":"","sources":["../../src/utils/measure-dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG/E,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAIlF;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAe1I;AAED,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,GAAG,IAAI,CAGpI;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAK9I"}

package/dist/utils/measure-dependencies.js

@@ -0,0 +1,44 @@
+import { isBaseMeasure, isDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
+export function measureDependencies(definition) {
+    if (isDerivedMeasure(definition))
+        return Object.values(definition.uses);
+    if (isShiftMeasure(definition) || isWindowMeasure(definition))
+        return [definition.measure];
+    return [];
+}
+/** Dependency order, with each shared input visited once. */
+export function measureDependencyNames(measures, selected) {
+    const visited = new Set();
+    const visiting = new Set();
+    const names = [];
+    const visit = (name) => {
+        if (visiting.has(name))
+            throw new Error(`Measure "${name}" contains a dependency cycle.`);
+        if (visited.has(name) || !Object.hasOwn(measures, name))
+            return;
+        visiting.add(name);
+        measureDependencies(measures[name]).forEach(visit);
+        visiting.delete(name);
+        visited.add(name);
+        names.push(name);
+    };
+    selected.forEach(visit);
+    return names;
+}
+export function assertMeasureDependenciesAcyclic(dataset, measures) {
+    try {
+        measureDependencyNames(measures, Object.keys(measures));
+    }
+    catch (error) {
+        throw new Error(`Invalid dataset "${dataset}": ${String(error)}`);
+    }
+}
+/** Wrappers inherit aggregation metadata only when their input has one. */
+export function inheritedBaseMeasure(measures, name) {
+    const definition = measures[name];
+    if (isBaseMeasure(definition))
+        return definition;
+    if (isWindowMeasure(definition) || isShiftMeasure(definition))
+        return inheritedBaseMeasure(measures, definition.measure);
+    return undefined;
+}

package/dist/utils/measure-evaluation-graph.d.ts

@@ -0,0 +1,23 @@
+import type { DatasetMeasureDefinition, DerivedMeasureDefinition, MeasureTimeInterval } from '../types.js';
+export interface MeasureEvaluationContext {
+    id: number;
+    parent?: number;
+    interval?: MeasureTimeInterval;
+}
+export interface MeasureEvaluationNode {
+    id: number;
+    name: string;
+    context: number;
+    definition: DatasetMeasureDefinition;
+    inputs?: Record<string, number>;
+}
+/** A shift changes evaluation context; formulas combine values in that context. */
+export declare function buildMeasureEvaluationGraph(measures: Readonly<Record<string, DatasetMeasureDefinition>>, selected: readonly string[]): {
+    contexts: MeasureEvaluationContext[];
+    nodes: MeasureEvaluationNode[];
+    outputs: {
+        [k: string]: number;
+    };
+};
+export declare function evaluationFormula(node: MeasureEvaluationNode): DerivedMeasureDefinition;
+//# sourceMappingURL=measure-evaluation-graph.d.ts.map

package/dist/utils/measure-evaluation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-evaluation-graph.d.ts","sourceRoot":"","sources":["../../src/utils/measure-evaluation-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAG3G,MAAM,WAAW,wBAAwB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE;AACzG,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,wBAAwB,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE;;;;;;EA+BpI;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,wBAAwB,CAIvF"}