@hypequery/datasets 0.19.0 → 0.20.0

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

@@ -0,0 +1,46 @@
+import { GRAIN_FUNCTIONS } from '../constants.js';
+import { addTimeSql, subtractTimeSql } from './time-arithmetic-sql.js';
+import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
+/** Preserve the selected portion of a bucket and both authored endpoint operators. */
+export function shiftRangeSql(shift, axis, period) {
+    const end = period ? addTimeSql(period, 1, axis.grain) : undefined;
+    return {
+        lower: subtractTimeSql(period ? `greatest(${period}, _hq_lower)` : '_hq_lower', shift.interval.amount, shift.interval.unit),
+        upper: subtractTimeSql(end ? `least(${end}, _hq_upper)` : '_hq_upper', shift.interval.amount, shift.interval.unit),
+        lowerInclusive: period ? `(${period} > _hq_lower OR ${Number(axis.lowerInclusive)})` : String(Number(axis.lowerInclusive)),
+        upperInclusive: end ? `(_hq_upper < ${end} AND ${Number(axis.upperInclusive)})` : String(Number(axis.upperInclusive)),
+    };
+}
+export function shiftRangePredicateSql(time, range) {
+    return `(${time} > ${range.lower} OR (${range.lowerInclusive} AND ${time} = ${range.lower}))`
+        + ` AND (${time} < ${range.upper} OR (${range.upperInclusive} AND ${time} = ${range.upper}))`;
+}
+/** Check the shifted scan independently of whether it contains source rows. */
+export function shiftCalendarGuardSql(shift, grain, axisGuard) {
+    const lower = subtractTimeSql('_hq_first', shift.interval.amount, shift.interval.unit);
+    const upper = subtractTimeSql(addTimeSql('_hq_last', 1, grain), shift.interval.amount, shift.interval.unit);
+    const first = `${GRAIN_FUNCTIONS[grain]}(${lower})`;
+    const last = `${GRAIN_FUNCTIONS[grain]}(${upper})`;
+    const count = `dateDiff('${grain}', ${first}, ${last}) + ${axisGuard}`;
+    return calendarBucketGuardSql(first, count, grain);
+}
+/** Map output buckets to their earlier half-open ranges, retaining calendar arithmetic. */
+export function shiftBucketCtes(shift, axis, index) {
+    const { grain } = axis;
+    const ranges = `_hq_shift_ranges${index}`;
+    const keys = `_hq_shift_keys${index}`;
+    const range = shiftRangeSql(shift, axis, '_hq_period');
+    const bucket = `${GRAIN_FUNCTIONS[grain]}(_hq_shift_lower)`;
+    const upperBucket = `${GRAIN_FUNCTIONS[grain]}(_hq_shift_upper)`;
+    const count = `greatest(0, dateDiff('${grain}', ${bucket}, ${upperBucket}) + if(_hq_shift_upper > ${upperBucket} OR _hq_shift_upper_inclusive, 1, 0))`;
+    return {
+        ctes: [
+            `${ranges} AS (SELECT _hq_period, ${range.lower} AS _hq_shift_lower, ${range.upper} AS _hq_shift_upper, ${range.lowerInclusive} AS _hq_shift_lower_inclusive, ${range.upperInclusive} AS _hq_shift_upper_inclusive FROM _hq_series CROSS JOIN _hq_bounds)`,
+            // A DST transition can map a one-hour output bucket to zero or two
+            // source hours. Enumerate source bucket keys and keep exact endpoints.
+            // The equality join avoids a source-rows × output-series Cartesian product.
+            `${keys} AS (SELECT *, ${addTimeSql(bucket, `arrayJoin(range(toUInt64(${count})))`, grain)} AS _hq_source_period FROM ${ranges})`,
+        ],
+        rowsSql: `SELECT r.*, b._hq_period FROM _hq_scanned AS r INNER JOIN ${keys} AS b ON ${GRAIN_FUNCTIONS[grain]}(r._hq_time) = b._hq_source_period WHERE ${shiftRangePredicateSql('r._hq_time', { lower: 'b._hq_shift_lower', upper: 'b._hq_shift_upper', lowerInclusive: 'b._hq_shift_lower_inclusive', upperInclusive: 'b._hq_shift_upper_inclusive' })}`,
+    };
+}

package/dist/utils/shift-measure-validation.d.ts

@@ -0,0 +1,3 @@
+import type { DatasetMeasureDefinition } from '../types.js';
+export declare function validateShiftMeasures(datasetName: string, timeKey: string | undefined, measures: Record<string, DatasetMeasureDefinition>): void;
+//# sourceMappingURL=shift-measure-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shift-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAK5D,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,IAAI,CAYhJ"}

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

@@ -0,0 +1,20 @@
+import { isSafeSQLIdentifier } from '../sql-utils.js';
+import { isSupportedTimeGrain } from '../constants.js';
+import { getBaseMeasure, isShiftMeasure } from './dataset-measures.js';
+export function validateShiftMeasures(datasetName, timeKey, measures) {
+    for (const [name, definition] of Object.entries(measures)) {
+        if (!isShiftMeasure(definition))
+            continue;
+        const prefix = `Invalid dataset "${datasetName}": shift measure "${name}"`;
+        if (!isSafeSQLIdentifier(name))
+            throw new Error(`${prefix} name is not a safe identifier.`);
+        if (!timeKey)
+            throw new Error(`${prefix} requires a timeKey.`);
+        if (!getBaseMeasure(measures, definition.measure))
+            throw new Error(`${prefix} must wrap a base measure; "${String(definition.measure)}" is not one.`);
+        const interval = definition.interval;
+        if (!interval || !Number.isSafeInteger(interval.amount) || interval.amount <= 0 || !isSupportedTimeGrain(interval.unit)) {
+            throw new Error(`${prefix} interval needs a positive safe integer and supported unit.`);
+        }
+    }
+}

package/dist/utils/sql-under-joins.d.ts

@@ -0,0 +1,10 @@
+import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
+/**
+ * Raw SQL expressions on the base dataset are emitted verbatim, so their column
+ * references are not table-qualified. When relationship joins are active a bare
+ * `price` in such an expression is ambiguous if the joined table also has a
+ * `price` column. Until the builder rewrites identifiers inside expressions,
+ * reject the combination rather than emit ambiguous SQL.
+ */
+export declare function assertNoRawSqlUnderJoins(kind: 'dimension' | 'measure', name: string, sql: string, joinCtx?: RelationshipBuilderContext): void;
+//# sourceMappingURL=sql-under-joins.d.ts.map

package/dist/utils/sql-under-joins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-under-joins.d.ts","sourceRoot":"","sources":["../../src/utils/sql-under-joins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,0BAA0B,GACnC,IAAI,CASN"}

package/dist/utils/sql-under-joins.js

@@ -0,0 +1,15 @@
+/**
+ * Raw SQL expressions on the base dataset are emitted verbatim, so their column
+ * references are not table-qualified. When relationship joins are active a bare
+ * `price` in such an expression is ambiguous if the joined table also has a
+ * `price` column. Until the builder rewrites identifiers inside expressions,
+ * reject the combination rather than emit ambiguous SQL.
+ */
+export function assertNoRawSqlUnderJoins(kind, name, sql, joinCtx) {
+    if (!joinCtx) {
+        return;
+    }
+    throw new Error(`SQL-backed ${kind} "${name}" cannot be combined with relationship joins: its expression ` +
+        `("${sql}") is not table-qualified and may collide with joined columns. Query it without ` +
+        `relationship-qualified fields, or redeclare it as a plain column.`);
+}

package/dist/utils/time-arithmetic-sql.d.ts

@@ -0,0 +1,4 @@
+import type { TimeGrain } from '../types.js';
+export declare function addTimeSql(time: string, amount: string | number, grain: TimeGrain): string;
+export declare function subtractTimeSql(time: string, amount: number, grain: TimeGrain): string;
+//# sourceMappingURL=time-arithmetic-sql.d.ts.map

package/dist/utils/time-arithmetic-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-arithmetic-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-arithmetic-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAE1F;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAEtF"}

package/dist/utils/time-arithmetic-sql.js

@@ -0,0 +1,9 @@
+const INTERVAL_FUNCTIONS = {
+    minute: 'Minutes', hour: 'Hours', day: 'Days', week: 'Weeks', month: 'Months', quarter: 'Quarters', year: 'Years',
+};
+export function addTimeSql(time, amount, grain) {
+    return `add${INTERVAL_FUNCTIONS[grain]}(${time}, ${amount})`;
+}
+export function subtractTimeSql(time, amount, grain) {
+    return `subtract${INTERVAL_FUNCTIONS[grain]}(${time}, ${amount})`;
+}

package/dist/utils/time-axis-bounds.d.ts

@@ -0,0 +1,24 @@
+import type { AnyDatasetInstance, MetricFilter } from '../types.js';
+export interface ParsedTimeBound {
+    /** Preserve the authored text: SQL interprets local bounds in the query timezone. */
+    text: string;
+    /** UTC instant for offset bounds; a wall-clock estimate for local bounds. */
+    milliseconds: number;
+    subMillisecond: boolean;
+    nanoseconds: bigint;
+    hasOffset: boolean;
+}
+export interface TimeAxisRange {
+    start: ParsedTimeBound;
+    end: ParsedTimeBound;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+    filters: MetricFilter[];
+}
+/** Parse without applying the process timezone, preserving nanosecond precision. */
+export declare function parseTimeBound(value: unknown): ParsedTimeBound | undefined;
+/** Extract exactly one bounded time range, retaining all non-time predicates. */
+export declare function resolveTimeAxisRange(dataset: AnyDatasetInstance, filters: MetricFilter[]): TimeAxisRange | undefined;
+/** Mixed offset/local bounds cannot be ordered until the query timezone is known. */
+export declare function isDefinitelyEmptyTimeRange(range: TimeAxisRange): boolean;
+//# sourceMappingURL=time-axis-bounds.d.ts.map

package/dist/utils/time-axis-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-axis-bounds.d.ts","sourceRoot":"","sources":["../../src/utils/time-axis-bounds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,GAAG,EAAE,eAAe,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAID,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAuB1E;AAMD,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,aAAa,GAAG,SAAS,CA2BpH;AAED,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAKxE"}

package/dist/utils/time-axis-bounds.js

@@ -0,0 +1,71 @@
+const ISO_TIME_BOUND = /^(\d{4}-\d{2}-\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/** Parse without applying the process timezone, preserving nanosecond precision. */
+export function parseTimeBound(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = ISO_TIME_BOUND.exec(value);
+    if (!match)
+        return undefined;
+    const [, day, hour, minute, second, fraction = '', offset] = match;
+    // Date.parse normalizes invalid calendar dates, so verify the authored day first.
+    const date = new Date(`${day}T00:00:00Z`);
+    if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== day)
+        return undefined;
+    if (Number(hour ?? 0) > 23 || Number(minute ?? 0) > 59 || Number(second ?? 0) > 59)
+        return undefined;
+    const clock = hour === undefined ? `${day}T00:00:00` : value.replace(' ', 'T');
+    const hasOffset = offset !== undefined;
+    const milliseconds = Date.parse(hasOffset ? clock : `${clock}Z`);
+    if (!Number.isFinite(milliseconds))
+        return undefined;
+    const nanosecondRemainder = BigInt(fraction.padEnd(9, '0').slice(3));
+    return {
+        text: value,
+        milliseconds,
+        subMillisecond: nanosecondRemainder !== 0n,
+        nanoseconds: BigInt(milliseconds) * 1000000n + nanosecondRemainder,
+        hasOffset,
+    };
+}
+function timeColumn(dataset, name) {
+    return dataset.dimensions[name]?.column ?? name;
+}
+/** Extract exactly one bounded time range, retaining all non-time predicates. */
+export function resolveTimeAxisRange(dataset, filters) {
+    const timeFilters = filters.filter(filter => {
+        const field = dataset.filters[filter.field]?.field ?? filter.field;
+        return !field.includes('.') && timeColumn(dataset, field) === timeColumn(dataset, dataset.timeKey ?? '');
+    });
+    let lower;
+    let upper;
+    let lowerInclusive = true;
+    let upperInclusive = true;
+    const between = timeFilters.length === 1 ? timeFilters[0] : undefined;
+    if (between?.operator === 'between' && Array.isArray(between.value) && between.value.length === 2) {
+        [lower, upper] = between.value;
+    }
+    else if (timeFilters.length === 2) {
+        const start = timeFilters.find(filter => filter.operator === 'gt' || filter.operator === 'gte');
+        const end = timeFilters.find(filter => filter.operator === 'lt' || filter.operator === 'lte');
+        lower = start?.value;
+        upper = end?.value;
+        lowerInclusive = start?.operator === 'gte';
+        upperInclusive = end?.operator === 'lte';
+    }
+    const start = parseTimeBound(lower);
+    const end = parseTimeBound(upper);
+    if (!start || !end)
+        return undefined;
+    return {
+        start, end, lowerInclusive, upperInclusive,
+        filters: filters.filter(filter => !timeFilters.includes(filter)),
+    };
+}
+/** Mixed offset/local bounds cannot be ordered until the query timezone is known. */
+export function isDefinitelyEmptyTimeRange(range) {
+    const { start, end, lowerInclusive, upperInclusive } = range;
+    if (start.hasOffset !== end.hasOffset)
+        return false;
+    return start.nanoseconds > end.nanoseconds
+        || (start.nanoseconds === end.nanoseconds && !(lowerInclusive && upperInclusive));
+}

package/dist/utils/time-axis-calendar-guard.d.ts

@@ -0,0 +1,9 @@
+import type { TimeGrain } from '../types.js';
+/**
+ * Calendar arithmetic can clamp a nonexistent date onto the previous bucket
+ * (for example Pacific/Apia, 2011-12-30). Reject non-increasing bucket starts:
+ * repeating them would duplicate aggregates and cumulative contributions.
+ * `count` must already include the series/fanout guards, bounding enumeration.
+ */
+export declare function calendarBucketGuardSql(start: string, count: string, grain: TimeGrain): string;
+//# sourceMappingURL=time-axis-calendar-guard.d.ts.map

package/dist/utils/time-axis-calendar-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-axis-calendar-guard.d.ts","sourceRoot":"","sources":["../../src/utils/time-axis-calendar-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAQ7F"}

package/dist/utils/time-axis-calendar-guard.js

@@ -0,0 +1,17 @@
+import { addTimeSql } from './time-arithmetic-sql.js';
+/**
+ * Calendar arithmetic can clamp a nonexistent date onto the previous bucket
+ * (for example Pacific/Apia, 2011-12-30). Reject non-increasing bucket starts:
+ * repeating them would duplicate aggregates and cumulative contributions.
+ * `count` must already include the series/fanout guards, bounding enumeration.
+ */
+export function calendarBucketGuardSql(start, count, grain) {
+    if (grain === 'minute' || grain === 'hour')
+        return '0';
+    const current = addTimeSql(start, '_hq_calendar_index', grain);
+    const next = addTimeSql(start, '_hq_calendar_index + 1', grain);
+    // Include the end boundary, which also bounds the source-row scan.
+    const indices = `range(toUInt64(greatest(1, ${count})))`;
+    return `throwIf(arrayExists(_hq_calendar_index -> ${next} <= ${current}, ${indices}), `
+        + "'Time range crosses a skipped local calendar bucket; use a UTC time key for this range.')";
+}

package/dist/utils/time-axis-intervals.d.ts

@@ -0,0 +1,13 @@
+import type { TimeGrain, WindowMeasureDefinition } from '../types.js';
+import type { ParsedTimeBound } from './time-axis-bounds.js';
+/** Exact conversions from RFC 0015; calendar months never become days. */
+export declare function intervalBuckets(amount: number, unit: TimeGrain, grain: TimeGrain): number | undefined;
+/** UTC estimate; SQL uses the time expression's timezone for exact buckets. */
+export declare function utcBucketStart(timestamp: number, grain: TimeGrain): number;
+/** Check the authored window's compatibility and maximum per-row contribution. */
+export declare function windowGrainErrors(name: string, window: WindowMeasureDefinition, grain: TimeGrain): string[];
+/** Estimate only: SQL determines exact bucket counts in the query timezone. */
+export declare function estimateTimeAxisBuckets(start: ParsedTimeBound, end: ParsedTimeBound, upperInclusive: boolean, grain: TimeGrain): number;
+/** Leave mixed bounds and local sub-day ranges to SQL's timezone-aware check. */
+export declare function exceedsEstimatedTimeAxisLimit(start: ParsedTimeBound, end: ParsedTimeBound, grain: TimeGrain, bucketCount: number, resultLimit: number | undefined): boolean;
+//# sourceMappingURL=time-axis-intervals.d.ts.map

package/dist/utils/time-axis-intervals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-axis-intervals.d.ts","sourceRoot":"","sources":["../../src/utils/time-axis-intervals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAa7D,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAQrG;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAgB1E;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAU3G;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,eAAe,EACpB,cAAc,EAAE,OAAO,EACvB,KAAK,EAAE,SAAS,GACf,MAAM,CAcR;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAMT"}

package/dist/utils/time-axis-intervals.js

@@ -0,0 +1,81 @@
+const FIXED_MINUTES = { minute: 1, hour: 60, day: 1440, week: 10080 };
+const CALENDAR_MONTHS = { month: 1, quarter: 3, year: 12 };
+const MAX_TO_DATE_BUCKETS = {
+    hour: { minute: 60 },
+    day: { minute: 1440, hour: 24 },
+    week: { minute: 10080, hour: 168, day: 7 },
+    month: { minute: 44640, hour: 744, day: 31 },
+    quarter: { minute: 132480, hour: 2208, day: 92, month: 3 },
+    year: { minute: 527040, hour: 8784, day: 366, month: 12, quarter: 4 },
+};
+/** Exact conversions from RFC 0015; calendar months never become days. */
+export function intervalBuckets(amount, unit, grain) {
+    const units = FIXED_MINUTES[unit] ?? CALENDAR_MONTHS[unit];
+    const buckets = FIXED_MINUTES[grain] ?? CALENDAR_MONTHS[grain];
+    const bothFixed = FIXED_MINUTES[unit] !== undefined && FIXED_MINUTES[grain] !== undefined;
+    const bothCalendar = CALENDAR_MONTHS[unit] !== undefined && CALENDAR_MONTHS[grain] !== undefined;
+    if (units === undefined || buckets === undefined || (!bothFixed && !bothCalendar))
+        return undefined;
+    const count = amount * units / buckets;
+    return Number.isSafeInteger(count) && count > 0 ? count : undefined;
+}
+/** UTC estimate; SQL uses the time expression's timezone for exact buckets. */
+export function utcBucketStart(timestamp, grain) {
+    const date = new Date(timestamp);
+    if (grain === 'minute') {
+        date.setUTCSeconds(0, 0);
+        return date.getTime();
+    }
+    if (grain === 'hour') {
+        date.setUTCMinutes(0, 0, 0);
+        return date.getTime();
+    }
+    date.setUTCHours(0, 0, 0, 0);
+    if (grain === 'week')
+        date.setUTCDate(date.getUTCDate() - date.getUTCDay());
+    if (grain === 'month' || grain === 'quarter' || grain === 'year')
+        date.setUTCDate(1);
+    if (grain === 'quarter')
+        date.setUTCMonth(Math.floor(date.getUTCMonth() / 3) * 3);
+    if (grain === 'year')
+        date.setUTCMonth(0);
+    return date.getTime();
+}
+/** Check the authored window's compatibility and maximum per-row contribution. */
+export function windowGrainErrors(name, window, grain) {
+    const count = window.trailing
+        ? intervalBuckets(window.trailing.amount, window.trailing.unit, grain)
+        : window.toDate ? MAX_TO_DATE_BUCKETS[window.toDate]?.[grain] : 1;
+    if (count === undefined) {
+        const toDateRequirement = window.toDate ? ' at a strictly coarser grain' : '';
+        return [`Window measure "${name}" must span whole "${grain}" buckets${toDateRequirement}.`];
+    }
+    if (count > 1000)
+        return [`Window measure "${name}" would make a row contribute to more than 1,000 buckets.`];
+    return [];
+}
+/** Estimate only: SQL determines exact bucket counts in the query timezone. */
+export function estimateTimeAxisBuckets(start, end, upperInclusive, grain) {
+    const first = utcBucketStart(start.milliseconds, grain);
+    const upperBucket = utcBucketStart(end.milliseconds, grain);
+    const excludesUpperBucket = !upperInclusive && !end.subMillisecond && end.milliseconds === upperBucket;
+    const last = utcBucketStart(end.milliseconds - (excludesUpperBucket ? 1 : 0), grain);
+    const calendar = CALENDAR_MONTHS[grain];
+    if (calendar !== undefined) {
+        const firstDate = new Date(first);
+        const lastDate = new Date(last);
+        const months = (lastDate.getUTCFullYear() - firstDate.getUTCFullYear()) * 12
+            + lastDate.getUTCMonth() - firstDate.getUTCMonth();
+        return months / calendar + 1;
+    }
+    return (last - first) / ((FIXED_MINUTES[grain] ?? 1) * 60000) + 1;
+}
+/** Leave mixed bounds and local sub-day ranges to SQL's timezone-aware check. */
+export function exceedsEstimatedTimeAxisLimit(start, end, grain, bucketCount, resultLimit) {
+    if (resultLimit === undefined)
+        return false;
+    const canEstimate = start.hasOffset === end.hasOffset
+        && (start.hasOffset || (grain !== 'minute' && grain !== 'hour'));
+    // Allow two boundary buckets because the query timezone is unknown.
+    return resultLimit === 0 || (canEstimate && bucketCount - 2 > resultLimit);
+}

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

@@ -0,0 +1,12 @@
+import type { TimeMeasureAxis } from './time-measure-axis.js';
+import type { TimeMeasureSqlSource } from './time-measure-source-sql.js';
+import type { ShiftMeasureDefinition } from '../types.js';
+export interface TimeMeasureSqlAxis {
+    ctes: string[];
+    timeAxisSql: string;
+    guard: string;
+    rangeGuard: string;
+}
+/** Build bounded output buckets using the query timezone. */
+export declare function buildTimeMeasureAxisSql(source: TimeMeasureSqlSource, axis: TimeMeasureAxis, shifts?: readonly ShiftMeasureDefinition[]): TimeMeasureSqlAxis;
+//# sourceMappingURL=time-measure-axis-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-axis-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-axis-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,6DAA6D;AAC7D,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE,eAAe,EACrB,MAAM,GAAE,SAAS,sBAAsB,EAAO,GAC7C,kBAAkB,CAwCpB"}

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

@@ -0,0 +1,47 @@
+import { GRAIN_FUNCTIONS } from '../constants.js';
+import { addTimeSql as add, subtractTimeSql as subtract } from './time-arithmetic-sql.js';
+import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
+import { shiftCalendarGuardSql } from './shift-measure-sql.js';
+function literal(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}
+/** Build bounded output buckets using the query timezone. */
+export function buildTimeMeasureAxisSql(source, axis, shifts = []) {
+    const first = `${GRAIN_FUNCTIONS[axis.grain]}(_hq_lower)`;
+    const upperBucket = `${GRAIN_FUNCTIONS[axis.grain]}(_hq_upper)`;
+    const last = axis.upperInclusive
+        ? upperBucket
+        : `if(_hq_upper = ${upperBucket}, ${subtract(upperBucket, 1, axis.grain)}, ${upperBucket})`;
+    const count = `dateDiff('${axis.grain}', _hq_first, _hq_last) + 1`;
+    const emptyRange = axis.lowerInclusive && axis.upperInclusive ? '' : ' OR _hq_lower = _hq_upper';
+    const rangeGuard = `throwIf(_hq_lower > _hq_upper${emptyRange}, 'Window measure time range must be non-empty and ordered.')`;
+    const limitGuard = axis.resultLimit === undefined
+        ? '0'
+        : `throwIf(${count} > ${axis.resultLimit}, 'Window series exceeds the effective result limit of ${axis.resultLimit} buckets.')`;
+    const calendarGuard = calendarBucketGuardSql('_hq_first', `${count} + ${limitGuard} + ${rangeGuard}`, axis.grain);
+    const physicalTimeType = `toTypeName(tupleElement((SELECT ${source.rowAlias} FROM _hq_raw LIMIT 0), 1))`;
+    const physicalGuard = axis.grain === 'minute' || axis.grain === 'hour'
+        ? `throwIf(position(${physicalTimeType}, 'Date') > 0 AND position(${physicalTimeType}, 'DateTime') = 0, 'Sub-day time measures require a time-of-day column; Date and Date32 are not supported.')`
+        : '0';
+    const shiftGuards = shifts.map(shift => shiftCalendarGuardSql(shift, axis.grain, `${limitGuard} + ${rangeGuard}`));
+    const guard = [limitGuard, physicalGuard, calendarGuard, ...shiftGuards].join(' + ');
+    // A zero-row scalar retains the converted timestamp type and query timezone.
+    // Reading any(time) here would scan the entire population just for its type.
+    const timezone = 'timezoneOf(assumeNotNull((SELECT _hq_time FROM _hq_source LIMIT 0)))';
+    const bounds = [
+        `parseDateTime64BestEffort(${literal(axis.lower)}, 9, ${timezone}) AS _hq_lower`,
+        `parseDateTime64BestEffort(${literal(axis.upper)}, 9, ${timezone}) AS _hq_upper`,
+        `${first} AS _hq_first`,
+        `${last} AS _hq_last`,
+    ];
+    const bucketIndices = `arrayJoin(range(toUInt64(${count} + ${guard} + ${rangeGuard})))`;
+    const period = add('_hq_first', bucketIndices, axis.grain);
+    const ctes = [
+        `_hq_bounds AS (SELECT ${bounds.join(', ')})`,
+        `_hq_series AS (SELECT ${period} AS _hq_period FROM _hq_bounds)`,
+    ];
+    // Always check the singleton axis before aggregating. ClickHouse can skip
+    // a series guard when a dimensional CROSS JOIN has an empty population.
+    const timeAxisSql = `WITH ${[...source.ctes, ctes[0]].join(',\n')} SELECT ${guard} + ${rangeGuard} AS _hq_validated FROM _hq_bounds`;
+    return { ctes, timeAxisSql, guard, rangeGuard };
+}

package/dist/utils/time-measure-axis.d.ts

@@ -0,0 +1,19 @@
+import type { AnyDatasetInstance, DatasetQuery, MetricFilter, TimeGrain } from '../types.js';
+export { intervalBuckets, utcBucketStart } from './time-axis-intervals.js';
+export interface TimeMeasureAxis {
+    grain: TimeGrain;
+    lower: string;
+    upper: string;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+    filters: MetricFilter[];
+    /** UTC estimate; execution enforces the exact timezone-aware count. */
+    bucketCount: number;
+    resultLimit?: number;
+}
+/** Validate time-measure grains, resolve bounds, then estimate the output series. */
+export declare function analyzeTimeMeasureAxis(dataset: AnyDatasetInstance, query: DatasetQuery): {
+    axis?: TimeMeasureAxis;
+    errors: string[];
+};
+//# sourceMappingURL=time-measure-axis.d.ts.map

package/dist/utils/time-measure-axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-axis.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-axis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQ7F,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,GAClB;IAAE,IAAI,CAAC,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmC9C"}

package/dist/utils/time-measure-axis.js

@@ -0,0 +1,45 @@
+import { isSupportedTimeGrain } from '../constants.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+import { isShiftMeasure } from './dataset-measures.js';
+import { resolveTimeAxisRange, isDefinitelyEmptyTimeRange } from './time-axis-bounds.js';
+import { intervalBuckets, windowGrainErrors, estimateTimeAxisBuckets, exceedsEstimatedTimeAxisLimit } from './time-axis-intervals.js';
+export { intervalBuckets, utcBucketStart } from './time-axis-intervals.js';
+/** Validate time-measure grains, resolve bounds, then estimate the output series. */
+export function analyzeTimeMeasureAxis(dataset, query) {
+    const timeMeasures = selectedTimeMeasures(dataset, query);
+    if (timeMeasures.size === 0)
+        return { errors: [] };
+    const errors = [];
+    const subjects = [...timeMeasures.values()].some(isShiftMeasure) ? 'Window and shift measures' : 'Window measures';
+    if (!isSupportedTimeGrain(query.by))
+        return { errors: [`${subjects} require a supported "by" grain.`] };
+    const grain = query.by;
+    for (const [name, window] of timeMeasures) {
+        if (isShiftMeasure(window)) {
+            if (intervalBuckets(window.interval.amount, window.interval.unit, grain) === undefined)
+                errors.push(`Shift measure "${name}" must span whole "${grain}" buckets.`);
+            continue;
+        }
+        errors.push(...windowGrainErrors(name, window, grain));
+    }
+    const range = resolveTimeAxisRange(dataset, query.filters ?? []);
+    if (!range) {
+        return { errors: [...errors, `${subjects} require exactly one bounded time range: between, or gt/gte with lt/lte, using ISO timestamps.`] };
+    }
+    if (isDefinitelyEmptyTimeRange(range)) {
+        return { errors: [...errors, 'Window measure time range must be non-empty and ordered.'] };
+    }
+    const { start, end, lowerInclusive, upperInclusive, filters } = range;
+    const bucketCount = estimateTimeAxisBuckets(start, end, upperInclusive, grain);
+    const resultLimit = query.limit ?? dataset.limits?.maxResultSize;
+    if (exceedsEstimatedTimeAxisLimit(start, end, grain, bucketCount, resultLimit)) {
+        errors.push(`Window series exceeds the effective result limit of ${resultLimit} buckets.`);
+    }
+    return {
+        errors,
+        axis: {
+            grain, lower: start.text, upper: end.text,
+            lowerInclusive, upperInclusive, filters, bucketCount, resultLimit,
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+/** Plan source rows → output axis → window/shift values → final projection. */
+export declare function buildTimeMeasureDatasetSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions): {
+    sql: string;
+    parameters: unknown[];
+    timeAxisSql: string;
+};
+//# sourceMappingURL=time-measure-dataset-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-dataset-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-dataset-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYxE,+EAA+E;AAC/E,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAuD7D"}

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

@@ -0,0 +1,63 @@
+import { getBaseMeasure, getDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+import { analyzeTimeMeasureAxis } from './time-measure-axis.js';
+import { validateDatasetQueryInput } from './dataset-query-validation.js';
+import { addTimeSql as add } from './time-arithmetic-sql.js';
+import { shiftBucketCtes, shiftRangeSql, shiftRangePredicateSql } from './shift-measure-sql.js';
+import { buildTimeMeasureSourceSql } from './time-measure-source-sql.js';
+import { buildTimeMeasureAxisSql } from './time-measure-axis-sql.js';
+import { buildTimeMeasureValuesSql, windowMeasureRowsSql, windowScanStartSql } from './time-measure-values-sql.js';
+import { buildTimeMeasureResultSql } from './time-measure-result-sql.js';
+/** Plan source rows → output axis → window/shift values → final projection. */
+export function buildTimeMeasureDatasetSql(ds, query, options) {
+    const validation = validateDatasetQueryInput(ds, query, options.context);
+    if (!validation.valid)
+        throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
+    const { axis } = analyzeTimeMeasureAxis(ds, query);
+    if (!axis || !ds.timeKey)
+        throw new Error('Window measures require a bounded time axis.');
+    const timeMeasures = selectedTimeMeasures(ds, query);
+    const windows = [...timeMeasures.values()].filter(isWindowMeasure);
+    const shifts = [...timeMeasures.values()].filter(isShiftMeasure);
+    const needed = new Set((query.measures ?? []).filter(name => !getDerivedMeasure(ds.measures, name)));
+    for (const name of query.measures ?? []) {
+        const derived = getDerivedMeasure(ds.measures, name);
+        if (derived)
+            Object.values(derived.uses).forEach(input => needed.add(input));
+    }
+    const baseNames = new Set([...needed].map(name => timeMeasures.get(name)?.measure ?? name));
+    const source = buildTimeMeasureSourceSql(ds, query, baseNames, axis.filters, options);
+    const timeAxis = buildTimeMeasureAxisSql(source, axis, shifts);
+    // Scan only requested populations: intervening rows must not introduce dimensions.
+    const end = add('_hq_last', 1, axis.grain);
+    const populations = [];
+    if ([...needed].some(name => getBaseMeasure(ds.measures, name))) {
+        populations.push(`(_hq_time >= _hq_first AND _hq_time < ${end})`);
+    }
+    if (windows.length) {
+        const starts = windows.filter(window => !window.cumulative)
+            .map(window => windowScanStartSql(window, axis.grain));
+        const lower = windows.some(window => window.cumulative)
+            ? '' : ` AND _hq_time >= least(${starts.join(', ')})`;
+        populations.push(`(_hq_time < ${end}${lower})`);
+    }
+    for (const shift of shifts) {
+        populations.push(`(${shiftRangePredicateSql('_hq_time', shiftRangeSql(shift, axis))})`);
+    }
+    const scanCte = `_hq_scanned AS (SELECT * FROM _hq_source CROSS JOIN _hq_bounds WHERE ${populations.join(' OR ')})`;
+    const inputs = [...needed].map((name, index) => {
+        const timeMeasure = timeMeasures.get(name);
+        const window = isWindowMeasure(timeMeasure) ? timeMeasure : undefined;
+        const base = source.bases.find(base => base.name === (timeMeasure?.measure ?? name));
+        if (!base)
+            throw new Error(`Missing base input for measure "${name}".`);
+        if (isShiftMeasure(timeMeasure)) {
+            const shifted = shiftBucketCtes(timeMeasure, axis, index);
+            return { name, base, rowsSql: shifted.rowsSql, rowCtes: shifted.ctes, restrictToAxis: false };
+        }
+        return { name, base, window, rowsSql: windowMeasureRowsSql(window, axis) };
+    });
+    const values = buildTimeMeasureValuesSql(source.dimensions, inputs, axis);
+    const sql = buildTimeMeasureResultSql(ds, query, options, source.dimensions, [...source.ctes, ...timeAxis.ctes, scanCte, ...values], `${timeAxis.guard} + ${timeAxis.rangeGuard}`);
+    return { sql, parameters: source.parameters, timeAxisSql: timeAxis.timeAxisSql };
+}

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

@@ -0,0 +1,6 @@
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+import type { TimeMeasureSqlDimension } from './time-measure-source-sql.js';
+/** Evaluate formulas after aggregation, then apply output ordering and pagination. */
+export declare function buildTimeMeasureResultSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, dims: readonly TimeMeasureSqlDimension[], ctes: readonly string[], validationGuard: string): string;
+//# sourceMappingURL=time-measure-result-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-result-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-result-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAIxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,sFAAsF;AACtF,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,EAAE,SAAS,uBAAuB,EAAE,EACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,eAAe,EAAE,MAAM,GACtB,MAAM,CAuBR"}

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

@@ -0,0 +1,30 @@
+import { quoteSQLIdentifier } from '../sql-utils.js';
+import { getDerivedMeasure } from './dataset-measures.js';
+import { derivedProjection } from './derived-measure-sql.js';
+/** Evaluate formulas after aggregation, then apply output ordering and pagination. */
+export function buildTimeMeasureResultSql(ds, query, options, dims, ctes, validationGuard) {
+    const selected = query.measures ?? [];
+    const projections = [
+        quoteSQLIdentifier('period'),
+        ...dims.map(dimension => quoteSQLIdentifier(dimension.name)),
+        ...selected.map(name => {
+            const derived = getDerivedMeasure(ds.measures, name);
+            return derived ? derivedProjection(name, derived) : quoteSQLIdentifier(name);
+        }),
+    ];
+    // Keep toSQL independently guarded too. This branch produces no valid
+    // result rows, and forces axis validation even when _hq_values is empty.
+    const outputNames = ['period', ...dims.map(dimension => dimension.name), ...selected];
+    const nullProjections = outputNames.map(name => `NULL AS ${quoteSQLIdentifier(name)}`).join(', ');
+    const resultCte = `_hq_result AS (SELECT ${projections.join(', ')} FROM _hq_values`
+        + ` UNION ALL SELECT ${nullProjections} FROM _hq_bounds WHERE ${validationGuard} = 1)`;
+    let sql = `WITH ${[...ctes, resultCte].join(',\n')} SELECT ${outputNames.map(quoteSQLIdentifier).join(', ')} FROM _hq_result`;
+    const order = query.orderBy?.length ? query.orderBy : [{ field: 'period', direction: 'asc' }];
+    sql += ` ORDER BY ${order.map(item => `${quoteSQLIdentifier(item.field)} ${item.direction === 'asc' ? 'ASC' : 'DESC'}`).join(', ')}`;
+    const limit = options.executionLimit ?? query.limit;
+    if (limit !== undefined)
+        sql += ` LIMIT ${limit}`;
+    if (query.offset !== undefined)
+        sql += ` OFFSET ${query.offset}`;
+    return sql;
+}