@atscript/db-sql-tools 0.1.131 → 0.1.133

package/dist/index.cjs

@@ -254,6 +254,23 @@ function renameGeoDistance(row) {
 function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
+/**
+* A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
+*
+* The zone is already canonical (the core normalizer ran uniqu's
+* `checkTimeZone`); this re-asserts uniqu's `TIME_ZONE_NAME_RE` charset —
+* no quote, backslash or whitespace can reach the literal — as defense in
+* depth for dialects that inline it (bucket expressions are parameter-free).
+*
+* @throws DbError `INVALID_QUERY` for a name outside the charset.
+*/
+function sqlTimeZoneLiteral(tz) {
+	if (!_uniqu_core.TIME_ZONE_NAME_RE.test(tz)) throw new _atscript_db.DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: `Unknown time zone "${tz}"`
+	}]);
+	return `'${tz}'`;
+}
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 function toSqlValue(value) {
 	if (value === void 0) return null;
@@ -338,6 +355,52 @@ function aggFnSql(dialect, expr) {
 function buildAggExpr(dialect, expr) {
 	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`;
 }
+const BUCKET_UNIT_SET = new Set(_uniqu_core.BUCKET_UNITS);
+const WEEK_START_SET = new Set(_uniqu_core.WEEK_STARTS);
+/**
+* The dialect's label expression for one calendar bucket.
+*
+* Internal assertions, once for every dialect, before it renders:
+* - the dialect has `calendarBucket` — the user-facing `BUCKET_NOT_SUPPORTED`
+*   is the core's (`calendarBucketUnits()`), so only an adapter advertising
+*   units its dialect cannot render reaches this throw;
+* - the literals a dialect inlines (the expression is parameter-free) are in
+*   their closed sets — unit, week start, ISO week start 1..7 — and the zone
+*   passes `sqlTimeZoneLiteral`'s charset. Defense in depth: the core's
+*   normalizer already validated all of them.
+*/
+function bucketSql(dialect, bucket) {
+	if (!dialect.calendarBucket) throw new _atscript_db.DbError("BUCKET_NOT_SUPPORTED", [{
+		path: "$select",
+		message: "Calendar buckets are not supported by this adapter"
+	}]);
+	const { unit, weekStart, weekStartIso } = bucket;
+	for (const [ok, value] of [
+		[BUCKET_UNIT_SET.has(unit), unit],
+		[WEEK_START_SET.has(weekStart), weekStart],
+		[Number.isInteger(weekStartIso) && weekStartIso >= 1 && weekStartIso <= 7, weekStartIso]
+	]) if (!ok) throw new _atscript_db.DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: `Invalid calendar bucket argument "${String(value)}"`
+	}]);
+	sqlTimeZoneLiteral(bucket.tz);
+	return dialect.calendarBucket(dialect.quoteIdentifier(bucket.field), bucket);
+}
+/**
+* The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
+* bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
+* column. GROUP BY, HAVING and the count query's GROUP BY use it — PostgreSQL
+* rejects SELECT aliases in HAVING and lets an input column of the same name
+* win in GROUP BY, so the expression form is the legal, unambiguous rendering
+* there (HAVING on MySQL is the exception — see `SqlDialect.bucketAliasInHaving`).
+* SELECT and GROUP BY render identical, parameter-free text (PostgreSQL /
+* MySQL `ONLY_FULL_GROUP_BY` match them structurally); ORDER BY keeps the
+* bare output alias.
+*/
+function groupKeySql(dialect, controls, key) {
+	const bucket = controls.$select?.bucketByAlias(key);
+	return bucket ? bucketSql(dialect, bucket) : dialect.quoteIdentifier(key);
+}
 /**
 * ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
 * `undefined` when there is nothing to render. Shared by the row and the
@@ -346,35 +409,52 @@ function buildAggExpr(dialect, expr) {
 * A key that names an aggregate alias (`$as`, else `fn_field`) renders the
 * aggregate expression itself — `SUM("amount") > ?` — because PostgreSQL does
 * not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
-* expression form keeps all three identical). Other keys (grouped columns)
-* render as plain columns.
+* expression form keeps all three identical). A calendar-bucket alias renders
+* its bucket expression ({@link groupKeySql}), or its quoted alias when the
+* dialect sets `SqlDialect.bucketAliasInHaving` (why: see there). Other keys
+* (grouped columns) render as plain columns.
 */
 function havingClause(dialect, controls) {
 	const having = controls.$having;
 	if (!having) return void 0;
 	const exprByAlias = /* @__PURE__ */ new Map();
 	for (const expr of controls.$select?.aggregates ?? []) exprByAlias.set((0, _atscript_db_agg.resolveAlias)(expr), aggFnSql(dialect, expr));
-	const fragment = (0, _uniqu_core.walkFilter)(having, createFilterVisitor(dialect, { columnRef: (field) => exprByAlias.get(field) ?? dialect.quoteIdentifier(field) }));
+	const fragment = (0, _uniqu_core.walkFilter)(having, createFilterVisitor(dialect, { columnRef: (field) => {
+		const aggExpr = exprByAlias.get(field);
+		if (aggExpr) return aggExpr;
+		if (dialect.bucketAliasInHaving && controls.$select?.bucketByAlias(field)) return dialect.quoteIdentifier(field);
+		return groupKeySql(dialect, controls, field);
+	} }));
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
 		sql: ` HAVING ${fragment.sql}`,
 		params: fragment.params
 	};
 }
+/** `<bucket expr> AS "alias"` for every calendar bucket in `$select`. */
+function bucketSelectParts(dialect, controls) {
+	return (controls.$select?.buckets ?? []).map((bucket) => `${bucketSql(dialect, bucket)} AS ${dialect.quoteIdentifier(bucket.alias)}`);
+}
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
+*
+* SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
+* per calendar bucket, then the aggregates. Bucket expressions are
+* parameter-free, so the bind parameters are exactly those of the same query
+* without buckets (WHERE, HAVING, LIMIT, OFFSET).
 */
 function buildAggregateSelect(dialect, table, where, controls) {
 	const selectParts = [];
 	const plainFields = controls.$select?.asArray;
 	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	selectParts.push(...bucketSelectParts(dialect, controls));
 	const aggregates = controls.$select?.aggregates;
 	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
 	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
 	const params = [...where.params];
 	const groupBy = controls.$groupBy;
 	if (groupBy?.length) {
-		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
+		const groupCols = groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ");
 		sql += ` GROUP BY ${groupCols}`;
 	}
 	const having = havingClause(dialect, controls);
@@ -415,9 +495,11 @@ function buildAggregateCount(dialect, table, where, controls) {
 		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
 		params: where.params
 	});
-	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ")}` : "";
+	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+	let inner = "COUNT(*)";
+	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${groupBy ? "1" : "COUNT(*)"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${inner} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -436,6 +518,39 @@ function buildInsert(dialect, table, data) {
 	});
 }
 /**
+* The columns of a multi-row INSERT: the union of the rows' keys, in
+* first-seen order (rows may differ in shape — an optional field omitted on
+* some).
+*/
+function insertManyColumns(rows) {
+	const columns = /* @__PURE__ */ new Set();
+	for (const row of rows) for (const key of Object.keys(row)) columns.add(key);
+	return [...columns];
+}
+/**
+* Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
+* (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
+* `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
+* split large inputs into batches themselves (passing the same `columns` to
+* each) and append any `RETURNING` clause.
+*/
+function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)) {
+	const cols = columns.map((k) => dialect.quoteIdentifier(k)).join(", ");
+	const fullRow = `(${columns.map(() => "?").join(", ")})`;
+	const params = [];
+	const clauses = [];
+	for (const row of rows) {
+		let missing = false;
+		for (const k of columns) if (k in row) params.push(dialect.toValue(row[k]));
+		else missing = true;
+		clauses.push(missing ? `(${columns.map((k) => k in row ? "?" : "DEFAULT").join(", ")})` : fullRow);
+	}
+	return finalizeParams(dialect, {
+		sql: `INSERT INTO ${dialect.quoteTable(table)} (${cols}) VALUES ${clauses.join(", ")}`,
+		params
+	});
+}
+/**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
 function buildSelect(dialect, table, where, controls) {
@@ -668,6 +783,7 @@ exports.buildDelete = buildDelete;
 exports.buildGeoSearchCount = buildGeoSearchCount;
 exports.buildGeoSearchSelect = buildGeoSearchSelect;
 exports.buildInsert = buildInsert;
+exports.buildInsertMany = buildInsertMany;
 exports.buildProjection = buildProjection;
 exports.buildSelect = buildSelect;
 exports.buildUpdate = buildUpdate;
@@ -678,6 +794,8 @@ exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
 exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
 exports.geoWindowFromControls = geoWindowFromControls;
+exports.groupKeySql = groupKeySql;
+exports.insertManyColumns = insertManyColumns;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
 exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;
@@ -686,4 +804,5 @@ exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
 exports.replaceColumnsFor = replaceColumnsFor;
 exports.sqlStringLiteral = sqlStringLiteral;
+exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;
 exports.toSqlValue = toSqlValue;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
 
 //#region src/dialect.d.ts
 interface TSqlFragment {
@@ -31,6 +31,35 @@ interface SqlDialect {
    * support omit this; the filter visitor then throws `GEO_NOT_SUPPORTED`.
    */
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
+  /**
+   * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
+   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
+   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
+   *
+   * The expression must be PARAMETER-FREE — inline the zone with
+   * `sqlTimeZoneLiteral(b.tz)` and the unit / week start as literals (the
+   * shared builders assert them against their closed sets first) — because
+   * the builders render it in SELECT, GROUP BY and HAVING and PostgreSQL
+   * matches GROUP BY expressions structurally (and the bind-parameter order
+   * must not change). Dialects without calendar buckets omit this; the
+   * builders then throw `BUCKET_NOT_SUPPORTED`. Since 0.1.132.
+   */
+  calendarBucket?(quotedCol: string, b: TResolvedBucket): string;
+  /**
+   * HAVING references a calendar bucket by its quoted SELECT alias instead of
+   * re-rendering the bucket expression (the aggregate count query's inner
+   * SELECT lists `<bucket expr> AS alias`, so the alias exists there too).
+   *
+   * MySQL needs this: the bucket expression reads the raw source column, which
+   * is not itself in GROUP BY (only the expression is), so HAVING rejects it
+   * (`ER_BAD_FIELD_ERROR … in 'having clause'`), while MySQL does resolve
+   * SELECT aliases in HAVING. PostgreSQL is the opposite (no SELECT aliases in
+   * HAVING), so dialects that omit this keep the expression form. Aggregate
+   * aliases are unaffected — they always render as the inlined aggregate call.
+   * Since 0.1.132.
+   */
+  bucketAliasInHaving?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -118,6 +147,20 @@ declare function renameGeoDistance(row: Record<string, unknown>): Record<string,
  * Builds an INSERT statement.
  */
 declare function buildInsert(dialect: SqlDialect, table: string, data: Record<string, unknown>): TSqlFragment;
+/**
+ * The columns of a multi-row INSERT: the union of the rows' keys, in
+ * first-seen order (rows may differ in shape — an optional field omitted on
+ * some).
+ */
+declare function insertManyColumns(rows: readonly Record<string, unknown>[]): string[];
+/**
+ * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
+ * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
+ * `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
+ * split large inputs into batches themselves (passing the same `columns` to
+ * each) and append any `RETURNING` clause.
+ */
+declare function buildInsertMany(dialect: SqlDialect, table: string, rows: readonly Record<string, unknown>[], columns?: readonly string[]): TSqlFragment;
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
@@ -191,6 +234,17 @@ declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TV
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
+ *
+ * The zone is already canonical (the core normalizer ran uniqu's
+ * `checkTimeZone`); this re-asserts uniqu's `TIME_ZONE_NAME_RE` charset —
+ * no quote, backslash or whitespace can reach the literal — as defense in
+ * depth for dialects that inline it (bucket expressions are parameter-free).
+ *
+ * @throws DbError `INVALID_QUERY` for a name outside the charset.
+ */
+declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
 declare function refActionToSql(action: TDbReferentialAction): string;
@@ -210,8 +264,25 @@ declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref:
 //#endregion
 //#region src/agg.d.ts
 declare const AGG_FN_SQL: Record<string, string>;
+/**
+ * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
+ * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
+ * column. GROUP BY, HAVING and the count query's GROUP BY use it — PostgreSQL
+ * rejects SELECT aliases in HAVING and lets an input column of the same name
+ * win in GROUP BY, so the expression form is the legal, unambiguous rendering
+ * there (HAVING on MySQL is the exception — see `SqlDialect.bucketAliasInHaving`).
+ * SELECT and GROUP BY render identical, parameter-free text (PostgreSQL /
+ * MySQL `ONLY_FULL_GROUP_BY` match them structurally); ORDER BY keeps the
+ * bare output alias.
+ */
+declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: string): string;
 /**
  * Builds a SELECT ... GROUP BY statement with aggregate functions.
+ *
+ * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
+ * per calendar bucket, then the aggregates. Bucket expressions are
+ * parameter-free, so the bind parameters are exactly those of the same query
+ * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
 declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
@@ -235,4 +306,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
 
 //#region src/dialect.d.ts
 interface TSqlFragment {
@@ -31,6 +31,35 @@ interface SqlDialect {
    * support omit this; the filter visitor then throws `GEO_NOT_SUPPORTED`.
    */
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
+  /**
+   * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
+   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
+   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
+   *
+   * The expression must be PARAMETER-FREE — inline the zone with
+   * `sqlTimeZoneLiteral(b.tz)` and the unit / week start as literals (the
+   * shared builders assert them against their closed sets first) — because
+   * the builders render it in SELECT, GROUP BY and HAVING and PostgreSQL
+   * matches GROUP BY expressions structurally (and the bind-parameter order
+   * must not change). Dialects without calendar buckets omit this; the
+   * builders then throw `BUCKET_NOT_SUPPORTED`. Since 0.1.132.
+   */
+  calendarBucket?(quotedCol: string, b: TResolvedBucket): string;
+  /**
+   * HAVING references a calendar bucket by its quoted SELECT alias instead of
+   * re-rendering the bucket expression (the aggregate count query's inner
+   * SELECT lists `<bucket expr> AS alias`, so the alias exists there too).
+   *
+   * MySQL needs this: the bucket expression reads the raw source column, which
+   * is not itself in GROUP BY (only the expression is), so HAVING rejects it
+   * (`ER_BAD_FIELD_ERROR … in 'having clause'`), while MySQL does resolve
+   * SELECT aliases in HAVING. PostgreSQL is the opposite (no SELECT aliases in
+   * HAVING), so dialects that omit this keep the expression form. Aggregate
+   * aliases are unaffected — they always render as the inlined aggregate call.
+   * Since 0.1.132.
+   */
+  bucketAliasInHaving?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -118,6 +147,20 @@ declare function renameGeoDistance(row: Record<string, unknown>): Record<string,
  * Builds an INSERT statement.
  */
 declare function buildInsert(dialect: SqlDialect, table: string, data: Record<string, unknown>): TSqlFragment;
+/**
+ * The columns of a multi-row INSERT: the union of the rows' keys, in
+ * first-seen order (rows may differ in shape — an optional field omitted on
+ * some).
+ */
+declare function insertManyColumns(rows: readonly Record<string, unknown>[]): string[];
+/**
+ * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
+ * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
+ * `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
+ * split large inputs into batches themselves (passing the same `columns` to
+ * each) and append any `RETURNING` clause.
+ */
+declare function buildInsertMany(dialect: SqlDialect, table: string, rows: readonly Record<string, unknown>[], columns?: readonly string[]): TSqlFragment;
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
@@ -191,6 +234,17 @@ declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TV
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
+ *
+ * The zone is already canonical (the core normalizer ran uniqu's
+ * `checkTimeZone`); this re-asserts uniqu's `TIME_ZONE_NAME_RE` charset —
+ * no quote, backslash or whitespace can reach the literal — as defense in
+ * depth for dialects that inline it (bucket expressions are parameter-free).
+ *
+ * @throws DbError `INVALID_QUERY` for a name outside the charset.
+ */
+declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
 declare function refActionToSql(action: TDbReferentialAction): string;
@@ -210,8 +264,25 @@ declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref:
 //#endregion
 //#region src/agg.d.ts
 declare const AGG_FN_SQL: Record<string, string>;
+/**
+ * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
+ * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
+ * column. GROUP BY, HAVING and the count query's GROUP BY use it — PostgreSQL
+ * rejects SELECT aliases in HAVING and lets an input column of the same name
+ * win in GROUP BY, so the expression form is the legal, unambiguous rendering
+ * there (HAVING on MySQL is the exception — see `SqlDialect.bucketAliasInHaving`).
+ * SELECT and GROUP BY render identical, parameter-free text (PostgreSQL /
+ * MySQL `ONLY_FULL_GROUP_BY` match them structurally); ORDER BY keeps the
+ * bare output alias.
+ */
+declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: string): string;
 /**
  * Builds a SELECT ... GROUP BY statement with aggregate functions.
+ *
+ * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
+ * per calendar bucket, then the aggregates. Bucket expressions are
+ * parameter-free, so the bind parameters are exactly those of the same query
+ * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
 declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
@@ -235,4 +306,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { walkFilter } from "@uniqu/core";
+import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
 import { DbError } from "@atscript/db";
 import { resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
@@ -253,6 +253,23 @@ function renameGeoDistance(row) {
 function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
+/**
+* A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
+*
+* The zone is already canonical (the core normalizer ran uniqu's
+* `checkTimeZone`); this re-asserts uniqu's `TIME_ZONE_NAME_RE` charset —
+* no quote, backslash or whitespace can reach the literal — as defense in
+* depth for dialects that inline it (bucket expressions are parameter-free).
+*
+* @throws DbError `INVALID_QUERY` for a name outside the charset.
+*/
+function sqlTimeZoneLiteral(tz) {
+	if (!TIME_ZONE_NAME_RE.test(tz)) throw new DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: `Unknown time zone "${tz}"`
+	}]);
+	return `'${tz}'`;
+}
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 function toSqlValue(value) {
 	if (value === void 0) return null;
@@ -337,6 +354,52 @@ function aggFnSql(dialect, expr) {
 function buildAggExpr(dialect, expr) {
 	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`;
 }
+const BUCKET_UNIT_SET = new Set(BUCKET_UNITS);
+const WEEK_START_SET = new Set(WEEK_STARTS);
+/**
+* The dialect's label expression for one calendar bucket.
+*
+* Internal assertions, once for every dialect, before it renders:
+* - the dialect has `calendarBucket` — the user-facing `BUCKET_NOT_SUPPORTED`
+*   is the core's (`calendarBucketUnits()`), so only an adapter advertising
+*   units its dialect cannot render reaches this throw;
+* - the literals a dialect inlines (the expression is parameter-free) are in
+*   their closed sets — unit, week start, ISO week start 1..7 — and the zone
+*   passes `sqlTimeZoneLiteral`'s charset. Defense in depth: the core's
+*   normalizer already validated all of them.
+*/
+function bucketSql(dialect, bucket) {
+	if (!dialect.calendarBucket) throw new DbError("BUCKET_NOT_SUPPORTED", [{
+		path: "$select",
+		message: "Calendar buckets are not supported by this adapter"
+	}]);
+	const { unit, weekStart, weekStartIso } = bucket;
+	for (const [ok, value] of [
+		[BUCKET_UNIT_SET.has(unit), unit],
+		[WEEK_START_SET.has(weekStart), weekStart],
+		[Number.isInteger(weekStartIso) && weekStartIso >= 1 && weekStartIso <= 7, weekStartIso]
+	]) if (!ok) throw new DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: `Invalid calendar bucket argument "${String(value)}"`
+	}]);
+	sqlTimeZoneLiteral(bucket.tz);
+	return dialect.calendarBucket(dialect.quoteIdentifier(bucket.field), bucket);
+}
+/**
+* The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
+* bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
+* column. GROUP BY, HAVING and the count query's GROUP BY use it — PostgreSQL
+* rejects SELECT aliases in HAVING and lets an input column of the same name
+* win in GROUP BY, so the expression form is the legal, unambiguous rendering
+* there (HAVING on MySQL is the exception — see `SqlDialect.bucketAliasInHaving`).
+* SELECT and GROUP BY render identical, parameter-free text (PostgreSQL /
+* MySQL `ONLY_FULL_GROUP_BY` match them structurally); ORDER BY keeps the
+* bare output alias.
+*/
+function groupKeySql(dialect, controls, key) {
+	const bucket = controls.$select?.bucketByAlias(key);
+	return bucket ? bucketSql(dialect, bucket) : dialect.quoteIdentifier(key);
+}
 /**
 * ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
 * `undefined` when there is nothing to render. Shared by the row and the
@@ -345,35 +408,52 @@ function buildAggExpr(dialect, expr) {
 * A key that names an aggregate alias (`$as`, else `fn_field`) renders the
 * aggregate expression itself — `SUM("amount") > ?` — because PostgreSQL does
 * not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
-* expression form keeps all three identical). Other keys (grouped columns)
-* render as plain columns.
+* expression form keeps all three identical). A calendar-bucket alias renders
+* its bucket expression ({@link groupKeySql}), or its quoted alias when the
+* dialect sets `SqlDialect.bucketAliasInHaving` (why: see there). Other keys
+* (grouped columns) render as plain columns.
 */
 function havingClause(dialect, controls) {
 	const having = controls.$having;
 	if (!having) return void 0;
 	const exprByAlias = /* @__PURE__ */ new Map();
 	for (const expr of controls.$select?.aggregates ?? []) exprByAlias.set(resolveAlias(expr), aggFnSql(dialect, expr));
-	const fragment = walkFilter(having, createFilterVisitor(dialect, { columnRef: (field) => exprByAlias.get(field) ?? dialect.quoteIdentifier(field) }));
+	const fragment = walkFilter(having, createFilterVisitor(dialect, { columnRef: (field) => {
+		const aggExpr = exprByAlias.get(field);
+		if (aggExpr) return aggExpr;
+		if (dialect.bucketAliasInHaving && controls.$select?.bucketByAlias(field)) return dialect.quoteIdentifier(field);
+		return groupKeySql(dialect, controls, field);
+	} }));
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
 		sql: ` HAVING ${fragment.sql}`,
 		params: fragment.params
 	};
 }
+/** `<bucket expr> AS "alias"` for every calendar bucket in `$select`. */
+function bucketSelectParts(dialect, controls) {
+	return (controls.$select?.buckets ?? []).map((bucket) => `${bucketSql(dialect, bucket)} AS ${dialect.quoteIdentifier(bucket.alias)}`);
+}
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
+*
+* SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
+* per calendar bucket, then the aggregates. Bucket expressions are
+* parameter-free, so the bind parameters are exactly those of the same query
+* without buckets (WHERE, HAVING, LIMIT, OFFSET).
 */
 function buildAggregateSelect(dialect, table, where, controls) {
 	const selectParts = [];
 	const plainFields = controls.$select?.asArray;
 	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	selectParts.push(...bucketSelectParts(dialect, controls));
 	const aggregates = controls.$select?.aggregates;
 	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
 	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
 	const params = [...where.params];
 	const groupBy = controls.$groupBy;
 	if (groupBy?.length) {
-		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
+		const groupCols = groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ");
 		sql += ` GROUP BY ${groupCols}`;
 	}
 	const having = havingClause(dialect, controls);
@@ -414,9 +494,11 @@ function buildAggregateCount(dialect, table, where, controls) {
 		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
 		params: where.params
 	});
-	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ")}` : "";
+	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+	let inner = "COUNT(*)";
+	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${groupBy ? "1" : "COUNT(*)"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${inner} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -435,6 +517,39 @@ function buildInsert(dialect, table, data) {
 	});
 }
 /**
+* The columns of a multi-row INSERT: the union of the rows' keys, in
+* first-seen order (rows may differ in shape — an optional field omitted on
+* some).
+*/
+function insertManyColumns(rows) {
+	const columns = /* @__PURE__ */ new Set();
+	for (const row of rows) for (const key of Object.keys(row)) columns.add(key);
+	return [...columns];
+}
+/**
+* Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
+* (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
+* `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
+* split large inputs into batches themselves (passing the same `columns` to
+* each) and append any `RETURNING` clause.
+*/
+function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)) {
+	const cols = columns.map((k) => dialect.quoteIdentifier(k)).join(", ");
+	const fullRow = `(${columns.map(() => "?").join(", ")})`;
+	const params = [];
+	const clauses = [];
+	for (const row of rows) {
+		let missing = false;
+		for (const k of columns) if (k in row) params.push(dialect.toValue(row[k]));
+		else missing = true;
+		clauses.push(missing ? `(${columns.map((k) => k in row ? "?" : "DEFAULT").join(", ")})` : fullRow);
+	}
+	return finalizeParams(dialect, {
+		sql: `INSERT INTO ${dialect.quoteTable(table)} (${cols}) VALUES ${clauses.join(", ")}`,
+		params
+	});
+}
+/**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
 function buildSelect(dialect, table, where, controls) {
@@ -655,4 +770,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.10",
     "unplugin-atscript": "^0.1.92"
   },
   "peerDependencies": {
-    "@uniqu/core": "^0.1.8",
-    "@atscript/db": "^0.1.131"
+    "@uniqu/core": "^0.1.10",
+    "@atscript/db": "^0.1.133"
   },
   "scripts": {
     "build": "vp pack",