@hypequery/datasets 0.1.0 → 0.2.0

package/dist/utils/dataset-metric-ref.d.ts

@@ -0,0 +1,9 @@
+import type { AggregationSpec, BaseMetricConfig, BaseMetricRef, DatasetInstance, DerivedMetricConfig, DerivedMetricRef, DerivedMetricSpec, DimensionDefinition, MeasureDefinition, MetricRef, RelationshipDefinition } from '../types.js';
+type AnyDimensions = Record<string, DimensionDefinition>;
+type AnyMeasures = Record<string, MeasureDefinition>;
+type AnyRelationships = Record<string, RelationshipDefinition>;
+export declare function isDerivedMetricConfig<TMeasures extends Record<string, MeasureDefinition>, TDatasetName extends string>(config: BaseMetricConfig<TMeasures> | DerivedMetricConfig<TDatasetName>): config is DerivedMetricConfig<TDatasetName>;
+export declare function createMetricRef<TDatasetName extends string, TMetricName extends string, TSpec extends AggregationSpec | DerivedMetricSpec<TDatasetName>, TDataset extends DatasetInstance<AnyDimensions, AnyMeasures, AnyRelationships, TDatasetName>>(ds: TDataset, name: TMetricName, spec: TSpec, label?: string, description?: string): MetricRef<TDatasetName, TMetricName, TSpec, TDataset>;
+export declare function createDerivedMetricSpec<TDatasetName extends string>(config: DerivedMetricConfig<TDatasetName>): DerivedMetricSpec<TDatasetName>;
+export type { BaseMetricRef, DerivedMetricRef };
+//# sourceMappingURL=dataset-metric-ref.d.ts.map

package/dist/utils/dataset-metric-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-metric-ref.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-metric-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEnB,iBAAiB,EACjB,SAAS,EACT,sBAAsB,EAEvB,MAAM,aAAa,CAAC;AAGrB,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AACzD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,qBAAqB,CACnC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,YAAY,SAAS,MAAM,EAE3B,MAAM,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,YAAY,CAAC,GACtE,MAAM,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAE7C;AAED,wBAAgB,eAAe,CAC7B,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,EAC1B,KAAK,SAAS,eAAe,GAAG,iBAAiB,CAAC,YAAY,CAAC,EAC/D,QAAQ,SAAS,eAAe,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAE5F,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,KAAK,EACX,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,CAiCvD;AAED,wBAAgB,uBAAuB,CAAC,YAAY,SAAS,MAAM,EACjE,MAAM,EAAE,mBAAmB,CAAC,YAAY,CAAC,GACxC,iBAAiB,CAAC,YAAY,CAAC,CAMjC;AAED,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/utils/dataset-metric-ref.js

@@ -0,0 +1,39 @@
+import { buildMetricContract } from './dataset-contract.js';
+export function isDerivedMetricConfig(config) {
+    return 'uses' in config && 'formula' in config;
+}
+export function createMetricRef(ds, name, spec, label, description) {
+    const ref = {
+        __type: 'metric_ref',
+        datasetName: ds.name,
+        name,
+        spec,
+        label,
+        description,
+        dataset: ds,
+        by(grain) {
+            if (!ds.timeKey) {
+                throw new Error(`Cannot apply .by("${grain}") to metric "${name}" — dataset "${ds.name}" has no timeKey defined.`);
+            }
+            return {
+                __type: 'grained_metric_ref',
+                metric: ref,
+                grain,
+                contract() {
+                    return buildMetricContract(name, ds, spec, label, description, grain);
+                },
+            };
+        },
+        contract() {
+            return buildMetricContract(name, ds, spec, label, description);
+        },
+    };
+    return ref;
+}
+export function createDerivedMetricSpec(config) {
+    return {
+        __type: 'derived_metric_spec',
+        uses: config.uses,
+        formula: config.formula,
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { AggregationSpec, DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticFiltersDefinition } from '../types.js';
+type AnyMeasures = Record<string, MeasureDefinition>;
+type AnyRelationships = Record<string, RelationshipDefinition>;
+export declare function normalizeDimensions<TDimensions extends Record<string, DimensionDefinition>>(config: DatasetConfig<TDimensions, AnyMeasures, AnyRelationships>): TDimensions;
+export declare function normalizeFilters(dimensions: Record<string, DimensionDefinition>, filters?: SemanticFiltersDefinition): SemanticFiltersDefinition;
+export declare function normalizeMeasures<TMeasures extends Record<string, MeasureDefinition>>(measures: TMeasures | undefined): TMeasures;
+export declare function normalizeRelationships<TRelationships extends Record<string, RelationshipDefinition>>(relationships: TRelationships | undefined): TRelationships;
+export declare function measureToAggregationSpec(measureName: string, definition: MeasureDefinition): AggregationSpec;
+export {};
+//# sourceMappingURL=dataset-normalization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnF,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,GACxC,cAAc,CAEhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAYjB"}

package/dist/utils/dataset-normalization.js

@@ -0,0 +1,35 @@
+export function normalizeDimensions(config) {
+    return config.dimensions;
+}
+export function normalizeFilters(dimensions, filters) {
+    if (filters) {
+        return filters;
+    }
+    return Object.fromEntries(Object.entries(dimensions)
+        .filter(([, definition]) => definition.filterable !== false)
+        .map(([name]) => [
+        name,
+        {
+            __type: 'filter_definition',
+            field: name,
+        },
+    ]));
+}
+export function normalizeMeasures(measures) {
+    return (measures ?? {});
+}
+export function normalizeRelationships(relationships) {
+    return (relationships ?? {});
+}
+export function measureToAggregationSpec(measureName, definition) {
+    if (!definition.field) {
+        throw new Error(`Invalid measure "${measureName}": a backing field is required.`);
+    }
+    return {
+        __type: 'aggregation_spec',
+        aggregation: definition.aggregation,
+        field: definition.field,
+        sql: definition.sql,
+        filters: definition.filters,
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { AnyDatasetInstance, DatasetQuery, ExecutionContext } from '../types.js';
+import { type ValidationResult } from '../validation.js';
+export declare function validateDatasetQueryInput(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): ValidationResult;
+//# sourceMappingURL=dataset-query-validation.d.ts.map

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

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

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

@@ -0,0 +1,96 @@
+import { validateFilterValue } from '../validation.js';
+import { SUPPORTED_TIME_GRAINS, isSupportedTimeGrain } from '../constants.js';
+import { getRuntimeTenantPredicate, validateTenantRuntime, } from './tenant-runtime.js';
+export function validateDatasetQueryInput(ds, query, context) {
+    const errors = [];
+    const dimensionNames = Object.keys(ds.dimensions);
+    const measureNames = Object.keys(ds.measures);
+    const selectedDimensions = query.dimensions ?? [];
+    const selectedMeasures = query.measures ?? measureNames;
+    const filterNames = Object.keys(ds.filters);
+    const orderableFields = new Set([
+        ...selectedDimensions,
+        ...selectedMeasures,
+        ...(query.by ? ['period'] : []),
+    ]);
+    const tenantRuntimeError = validateTenantRuntime(ds, context);
+    if (tenantRuntimeError) {
+        errors.push(tenantRuntimeError);
+    }
+    if (selectedDimensions.length === 0 && selectedMeasures.length === 0) {
+        errors.push(`Dataset "${ds.name}" query must select at least one dimension or measure.`);
+    }
+    if (query.dimensions) {
+        const invalid = query.dimensions.filter(dimension => !dimensionNames.includes(dimension));
+        if (invalid.length > 0) {
+            errors.push(`Unknown dimensions: ${invalid.join(', ')}. Available: ${dimensionNames.join(', ')}`);
+        }
+    }
+    if (query.measures) {
+        const invalid = query.measures.filter(measure => !measureNames.includes(measure));
+        if (invalid.length > 0) {
+            errors.push(`Unknown measures: ${invalid.join(', ')}. Available: ${measureNames.join(', ')}`);
+        }
+    }
+    if (query.filters) {
+        const invalid = query.filters.filter(filter => !filterNames.includes(filter.field));
+        if (invalid.length > 0) {
+            errors.push(`Unknown filter fields: ${invalid.map(filter => filter.field).join(', ')}. Available: ${filterNames.join(', ')}`);
+        }
+        for (const filter of query.filters) {
+            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 resolvedDimension = ds.dimensions[resolvedField];
+            const resolvedColumn = resolvedDimension?.sql
+                ? undefined
+                : resolvedDimension?.column ?? resolvedField;
+            if (getRuntimeTenantPredicate(context) && ds.tenantKey && resolvedColumn === ds.tenantKey) {
+                errors.push(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
+                continue;
+            }
+            const fieldType = resolvedDimension?.fieldType;
+            if (!fieldType) {
+                continue;
+            }
+            const filterError = validateFilterValue(filter, fieldType);
+            if (filterError) {
+                errors.push(filterError);
+            }
+        }
+    }
+    if (query.orderBy) {
+        const invalid = query.orderBy.filter(order => !orderableFields.has(order.field));
+        if (invalid.length > 0) {
+            errors.push(`Unknown orderBy fields: ${invalid.map(order => order.field).join(', ')}. Available: ${Array.from(orderableFields).join(', ')}`);
+        }
+    }
+    if (query.by && !ds.timeKey) {
+        errors.push(`Cannot use "by" grain — dataset "${ds.name}" has no timeKey.`);
+    }
+    if (query.by && !isSupportedTimeGrain(query.by)) {
+        errors.push(`Unsupported time grain "${query.by}". Supported: ${SUPPORTED_TIME_GRAINS.join(', ')}`);
+    }
+    if (query.limit != null && (!Number.isInteger(query.limit) || query.limit < 0)) {
+        errors.push(`Invalid limit: expected a non-negative integer.`);
+    }
+    if (query.offset != null && (!Number.isInteger(query.offset) || query.offset < 0)) {
+        errors.push(`Invalid offset: expected a non-negative integer.`);
+    }
+    if (ds.limits?.maxDimensions && query.dimensions && query.dimensions.length > ds.limits.maxDimensions) {
+        errors.push(`Too many dimensions: ${query.dimensions.length} (max ${ds.limits.maxDimensions})`);
+    }
+    if (ds.limits?.maxMeasures && query.measures && query.measures.length > ds.limits.maxMeasures) {
+        errors.push(`Too many measures: ${query.measures.length} (max ${ds.limits.maxMeasures})`);
+    }
+    if (ds.limits?.maxFilters && query.filters && query.filters.length > ds.limits.maxFilters) {
+        errors.push(`Too many filters: ${query.filters.length} (max ${ds.limits.maxFilters})`);
+    }
+    if (ds.limits?.maxResultSize && query.limit != null && query.limit > ds.limits.maxResultSize) {
+        errors.push(`Too many results requested: ${query.limit} (max ${ds.limits.maxResultSize})`);
+    }
+    return { valid: errors.length === 0, errors };
+}

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

@@ -0,0 +1,6 @@
+import type { AggregationSpec, AnyDatasetInstance, DerivedMetricConfig } from '../types.js';
+export declare function validateBaseMetric(ds: AnyDatasetInstance, metricName: string, spec: AggregationSpec, options?: {
+    allowHiddenField?: boolean;
+}): void;
+export declare function validateDerivedMetric(ds: AnyDatasetInstance, metricName: string, config: DerivedMetricConfig<string>): void;
+//# sourceMappingURL=dataset-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,IAAI,CAwCN;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,IAAI,CAmBN"}

package/dist/utils/dataset-validation.js

@@ -0,0 +1,42 @@
+import { validateFilterValue } from '../validation.js';
+const NUMERIC_FIELD_TYPES = new Set(['number']);
+export function validateBaseMetric(ds, metricName, spec, options) {
+    const dimension = ds.dimensions[spec.field];
+    if (!dimension && !options?.allowHiddenField) {
+        throw new Error(`Invalid metric "${metricName}": dimension "${spec.field}" does not exist on dataset "${ds.name}".`);
+    }
+    if (dimension &&
+        (spec.aggregation === 'sum' || spec.aggregation === 'avg') &&
+        !NUMERIC_FIELD_TYPES.has(dimension.fieldType)) {
+        throw new Error(`Invalid metric "${metricName}": ${spec.aggregation}() requires a numeric dimension, but "${spec.field}" is ${dimension.fieldType}.`);
+    }
+    for (const filter of spec.filters ?? []) {
+        const filterDefinition = ds.filters[filter.field];
+        const resolvedField = filterDefinition?.field ?? filter.field;
+        const fieldType = ds.dimensions[resolvedField]?.fieldType;
+        if (!fieldType) {
+            throw new Error(`Invalid metric "${metricName}": measure filter field "${filter.field}" does not exist on dataset "${ds.name}".`);
+        }
+        if (filterDefinition?.operators && !filterDefinition.operators.includes(filter.operator)) {
+            throw new Error(`Invalid metric "${metricName}": measure filter "${filter.field}" does not allow operator "${filter.operator}".`);
+        }
+        const filterError = validateFilterValue(filter, fieldType);
+        if (filterError) {
+            throw new Error(`Invalid metric "${metricName}": ${filterError}`);
+        }
+    }
+}
+export function validateDerivedMetric(ds, metricName, config) {
+    const usedMetrics = Object.entries(config.uses);
+    if (usedMetrics.length === 0) {
+        throw new Error(`Invalid metric "${metricName}": derived metrics must reference at least one base metric.`);
+    }
+    for (const [alias, metric] of usedMetrics) {
+        if (metric.datasetName !== ds.name) {
+            throw new Error(`Invalid metric "${metricName}": referenced metric "${alias}" belongs to dataset "${metric.datasetName}", expected "${ds.name}".`);
+        }
+        if (metric.spec.__type !== 'aggregation_spec') {
+            throw new Error(`Invalid metric "${metricName}": referenced metric "${alias}" must be a base aggregation on dataset "${ds.name}".`);
+        }
+    }
+}

package/dist/utils/derived-cte-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function extractGroupByExpressions(sql: string): string[];
+export declare function validateDerivedCteGrouping(sql: string, aggregateAliases: string[], intendedGroupBy: string[]): string[];
+//# sourceMappingURL=derived-cte-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derived-cte-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-cte-validation.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EAAE,EAC1B,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,EAAE,CAgCV"}

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

@@ -0,0 +1,32 @@
+export function extractGroupByExpressions(sql) {
+    const match = sql.match(/\bGROUP BY\b\s+(.+?)(?:\bHAVING\b|\bORDER BY\b|\bLIMIT\b|\bOFFSET\b|$)/is);
+    if (!match) {
+        return [];
+    }
+    return match[1]
+        .split(',')
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+export function validateDerivedCteGrouping(sql, aggregateAliases, intendedGroupBy) {
+    const errors = [];
+    const actualGroupBy = extractGroupByExpressions(sql);
+    if (intendedGroupBy.length === 0 && actualGroupBy.length > 0) {
+        errors.push('Derived metric planner emitted GROUP BY for an ungrouped query.');
+    }
+    const duplicates = actualGroupBy.filter((expression, index) => actualGroupBy.indexOf(expression) !== index);
+    if (duplicates.length > 0) {
+        errors.push(`Derived metric planner emitted duplicate GROUP BY expressions: ${Array.from(new Set(duplicates)).join(', ')}`);
+    }
+    const aggregateAliasSet = new Set(aggregateAliases);
+    const aggregateAliasesInGroupBy = actualGroupBy.filter(expression => aggregateAliasSet.has(expression));
+    if (aggregateAliasesInGroupBy.length > 0) {
+        errors.push(`Derived metric planner emitted aggregate aliases in GROUP BY: ${Array.from(new Set(aggregateAliasesInGroupBy)).join(', ')}`);
+    }
+    const intendedGroupBySet = new Set(intendedGroupBy);
+    const unexpectedGroupBy = actualGroupBy.filter(expression => !intendedGroupBySet.has(expression));
+    if (unexpectedGroupBy.length > 0) {
+        errors.push(`Derived metric planner emitted unexpected GROUP BY expressions: ${Array.from(new Set(unexpectedGroupBy)).join(', ')}`);
+    }
+    return errors;
+}

package/dist/utils/filtered-aggregation-sql.d.ts

@@ -0,0 +1,5 @@
+import type { AggregationSpec, AnyDatasetInstance } from '../types.js';
+type DatasetShape = AnyDatasetInstance;
+export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string): string;
+export {};
+//# sourceMappingURL=filtered-aggregation-sql.d.ts.map

package/dist/utils/filtered-aggregation-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAGrF,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAiEvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAsBR"}

package/dist/utils/filtered-aggregation-sql.js

@@ -0,0 +1,73 @@
+import { resolveFilterField } from '../query-planner.js';
+function renderMeasureFilterLiteral(value) {
+    if (value === null) {
+        return 'NULL';
+    }
+    if (typeof value === 'string') {
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Invalid non-finite numeric literal in measure filter: ${value}`);
+        }
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    throw new Error(`Unsupported literal type in measure filter: ${typeof value}`);
+}
+function renderMeasureFilterCondition(ds, filter) {
+    const field = resolveFilterField(ds, filter.field);
+    switch (filter.operator) {
+        case 'eq':
+            return `${field} = ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'neq':
+            return `${field} != ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'gt':
+            return `${field} > ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'gte':
+            return `${field} >= ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'lt':
+            return `${field} < ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'lte':
+            return `${field} <= ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'like':
+            return `${field} LIKE ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'in':
+        case 'notIn': {
+            if (!Array.isArray(filter.value) || filter.value.length === 0) {
+                throw new Error(`"${filter.operator}" measure filters require a non-empty array.`);
+            }
+            const values = filter.value.map(renderMeasureFilterLiteral).join(', ');
+            return `${field} ${filter.operator === 'in' ? 'IN' : 'NOT IN'} (${values})`;
+        }
+        case 'between': {
+            if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+                throw new Error('"between" measure filters require a two-item array.');
+            }
+            return `${field} BETWEEN ${renderMeasureFilterLiteral(filter.value[0])} AND ${renderMeasureFilterLiteral(filter.value[1])}`;
+        }
+    }
+}
+export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr) {
+    if (!spec.filters?.length) {
+        return fieldOrExpr;
+    }
+    const combinedCondition = spec.filters
+        .map(filter => renderMeasureFilterCondition(ds, filter))
+        .map(condition => `(${condition})`)
+        .join(' AND ');
+    switch (spec.aggregation) {
+        case 'sum':
+            return `if(${combinedCondition}, ${fieldOrExpr}, 0)`;
+        case 'count':
+        case 'countDistinct':
+        case 'avg':
+        case 'min':
+        case 'max':
+            return `if(${combinedCondition}, ${fieldOrExpr}, NULL)`;
+        default:
+            return fieldOrExpr;
+    }
+}

package/dist/utils/metric-handle.d.ts

@@ -0,0 +1,11 @@
+import type { AnyDatasetInstance, ExecutionContext, GrainedMetricRef, MetricFilter, MetricQuery, MetricRef, TimeGrain } from '../types.js';
+type DatasetShape = AnyDatasetInstance;
+export type MetricHandle = MetricRef | GrainedMetricRef;
+export declare function isMetricHandle(value: unknown): value is MetricHandle;
+export declare function assertMetricHandle(value: unknown): asserts value is MetricHandle;
+export declare function getMetricRef(metric: MetricHandle): MetricRef;
+export declare function getMetricGrain(metric: MetricHandle, query: MetricQuery): TimeGrain | undefined;
+export declare function getTenantRuntimeColumn(ds: DatasetShape, context?: ExecutionContext): string | undefined;
+export declare function isTenantScopedFilter(ds: DatasetShape, filter: MetricFilter, context?: ExecutionContext): boolean;
+export {};
+//# sourceMappingURL=metric-handle.d.ts.map

package/dist/utils/metric-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-handle.d.ts","sourceRoot":"","sources":["../../src/utils/metric-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACV,MAAM,aAAa,CAAC;AAGrB,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAMvC,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAExD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAKpE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAOhF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAE5D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAOT"}

package/dist/utils/metric-handle.js

@@ -0,0 +1,36 @@
+import { resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn } from '../query-planner.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+function isMetricHandleType(value) {
+    return value === 'metric_ref' || value === 'grained_metric_ref';
+}
+export function isMetricHandle(value) {
+    return typeof value === 'object'
+        && value !== null
+        && '__type' in value
+        && isMetricHandleType(value.__type);
+}
+export function assertMetricHandle(value) {
+    if (!isMetricHandle(value)) {
+        throw new Error('Metric queries only support MetricRef and GrainedMetricRef. ' +
+            'dataset.query(...) is not part of the public execution API.');
+    }
+}
+export function getMetricRef(metric) {
+    return metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+}
+export function getMetricGrain(metric, query) {
+    return metric.__type === 'grained_metric_ref' ? metric.grain : query.by ?? undefined;
+}
+export function getTenantRuntimeColumn(ds, context) {
+    if (!getRuntimeTenantPredicate(context)) {
+        return undefined;
+    }
+    return resolveTenantFilterColumn(ds, context);
+}
+export function isTenantScopedFilter(ds, filter, context) {
+    const tenantColumn = getTenantRuntimeColumn(ds, context);
+    if (!tenantColumn) {
+        return false;
+    }
+    return resolveFilterField(ds, filter.field) === resolveDimensionExpression(ds, tenantColumn);
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,17 @@
+import type { MetricResultMeta } from '../types.js';
+export type PaginationMeta = NonNullable<MetricResultMeta['pagination']>;
+/**
+ * When a limit is set, request one extra row so the executor can report
+ * `hasMore` without issuing a separate COUNT query. Returns `undefined` when
+ * no limit is set (unbounded query — there is no "next page").
+ */
+export declare function overfetchLimit(limit?: number): number | undefined;
+/**
+ * Trim an over-fetched result set back to `limit` rows and derive pagination
+ * metadata. The extra row (if present) signals that another page exists.
+ */
+export declare function applyPagination<T>(rows: T[], limit?: number, offset?: number): {
+    data: T[];
+    pagination?: PaginationMeta;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,cAAc,CAAA;CAAE,CAU5C"}

package/dist/utils/pagination.js

@@ -0,0 +1,23 @@
+/**
+ * When a limit is set, request one extra row so the executor can report
+ * `hasMore` without issuing a separate COUNT query. Returns `undefined` when
+ * no limit is set (unbounded query — there is no "next page").
+ */
+export function overfetchLimit(limit) {
+    return limit != null ? limit + 1 : undefined;
+}
+/**
+ * Trim an over-fetched result set back to `limit` rows and derive pagination
+ * metadata. The extra row (if present) signals that another page exists.
+ */
+export function applyPagination(rows, limit, offset) {
+    if (limit == null) {
+        return { data: rows };
+    }
+    const hasMore = rows.length > limit;
+    const data = hasMore ? rows.slice(0, limit) : rows;
+    return {
+        data,
+        pagination: { limit, offset: offset ?? 0, hasMore },
+    };
+}

package/dist/utils/tenant-runtime.d.ts

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance, ExecutionContext } from '../types.js';
+export type TenantPredicate = {
+    operator: 'eq';
+    value: string;
+} | {
+    operator: 'in';
+    value: string[];
+};
+export declare function getRuntimeTenantPredicate(context?: ExecutionContext): TenantPredicate | undefined;
+export declare function getRuntimeTenantId(context?: ExecutionContext): string | undefined;
+export declare function isCrossTenantRuntime(context?: ExecutionContext): boolean;
+export declare function hasTenantRuntime(context?: ExecutionContext): boolean;
+export declare function validateTenantRuntime(ds: AnyDatasetInstance, context?: ExecutionContext): string | undefined;
+//# sourceMappingURL=tenant-runtime.d.ts.map

package/dist/utils/tenant-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAGxE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAEpE;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAQpB"}

package/dist/utils/tenant-runtime.js

@@ -0,0 +1,36 @@
+export function getRuntimeTenantPredicate(context) {
+    const tenant = context?.runtime?.tenant;
+    if (!tenant) {
+        return undefined;
+    }
+    if (typeof tenant === 'string') {
+        return { operator: 'eq', value: tenant };
+    }
+    if ('id' in tenant) {
+        return { operator: 'eq', value: tenant.id };
+    }
+    if ('in' in tenant && tenant.in.length > 0) {
+        return { operator: 'in', value: tenant.in };
+    }
+    return undefined;
+}
+export function getRuntimeTenantId(context) {
+    const predicate = getRuntimeTenantPredicate(context);
+    return predicate?.operator === 'eq' ? predicate.value : undefined;
+}
+export function isCrossTenantRuntime(context) {
+    const tenant = context?.runtime?.tenant;
+    return !!tenant && typeof tenant === 'object' && 'scope' in tenant && tenant.scope === 'all';
+}
+export function hasTenantRuntime(context) {
+    return !!getRuntimeTenantPredicate(context) || isCrossTenantRuntime(context);
+}
+export function validateTenantRuntime(ds, context) {
+    if (!ds.tenantKey) {
+        return undefined;
+    }
+    if (!hasTenantRuntime(context)) {
+        return `Dataset "${ds.name}" requires runtime tenant scoping.`;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "require": "./dist/internal.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "internal": [
+        "./dist/internal.d.ts"
+      ]
     }
   },
   "license": "Apache-2.0",
@@ -41,7 +53,7 @@
     "dev": "tsc --watch",
     "test": "npm run test:types && npm run test:unit",
     "test:unit": "vitest run",
-    "test:integration": "vitest run",
+    "test:integration": "node scripts/run-integration-tests.js",
     "test:types": "tsc --project tsconfig.type-tests.json",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage"