@atscript/db-sql-tools 0.1.127 → 0.1.129

package/dist/index.cjs

@@ -28,17 +28,18 @@ const EMPTY_OR = {
 /**
 * Creates a dialect-specific filter visitor for `walkFilter`.
 */
-function createFilterVisitor(dialect) {
+function createFilterVisitor(dialect, options) {
+	const columnRef = options?.columnRef ?? ((field) => dialect.quoteIdentifier(field));
 	return {
 		comparison(field, op, value) {
 			if (op === "$geoWithin") {
-				if (dialect.geoWithin) return dialect.geoWithin(dialect.quoteIdentifier(field), value);
+				if (dialect.geoWithin) return dialect.geoWithin(columnRef(field), value);
 				throw new _atscript_db.DbError("GEO_NOT_SUPPORTED", [{
 					path: field,
 					message: "$geoWithin is not supported by this adapter"
 				}]);
 			}
-			const col = dialect.quoteIdentifier(field);
+			const col = columnRef(field);
 			const v = dialect.toParam(value);
 			switch (op) {
 				case "$eq":
@@ -330,10 +331,35 @@ const AGG_FN_SQL = {
 	min: "MIN",
 	max: "MAX"
 };
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)`. */
+function aggFnSql(dialect, expr) {
+	return `${AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase()}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)})`;
+}
 function buildAggExpr(dialect, expr) {
-	const fn = AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase();
-	const alias = dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr));
-	return `${fn}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)}) AS ${alias}`;
+	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`;
+}
+/**
+* ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
+* `undefined` when there is nothing to render. Shared by the row and the
+* count builders so both filter the same group set.
+*
+* 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.
+*/
+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) }));
+	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
+	return {
+		sql: ` HAVING ${fragment.sql}`,
+		params: fragment.params
+	};
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -351,12 +377,10 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
 		sql += ` GROUP BY ${groupCols}`;
 	}
-	if (controls.$having) {
-		const havingFragment = buildWhere(dialect, controls.$having);
-		if (havingFragment.sql !== EMPTY_AND.sql) {
-			sql += ` HAVING ${havingFragment.sql}`;
-			params.push(...havingFragment.params);
-		}
+	const having = havingClause(dialect, controls);
+	if (having) {
+		sql += having.sql;
+		params.push(...having.params);
 	}
 	if (controls.$sort) {
 		const orderParts = [];
@@ -378,19 +402,23 @@ function buildAggregateSelect(dialect, table, where, controls) {
 	});
 }
 /**
-* Builds a COUNT query for the number of distinct groups.
-* Returns `{ count: N }` when executed.
+* Builds a COUNT query for the number of distinct groups — the groups that
+* survive `$having` when one is given (the same predicate the row query
+* renders, so `$count` agrees with the row set). Returns `{ count: N }` when
+* executed.
 */
 function buildAggregateCount(dialect, table, where, controls) {
 	const groupFields = controls.$groupBy;
-	if (!groupFields?.length) return finalizeParams(dialect, {
-		sql: `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+	const having = havingClause(dialect, controls);
+	const countCol = `COUNT(*) AS ${dialect.quoteIdentifier("count")}`;
+	if (!groupFields?.length && !having) return finalizeParams(dialect, {
+		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
 		params: where.params
 	});
-	const groupCols = groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ");
+	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ")}` : "";
 	return finalizeParams(dialect, {
-		sql: `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM (SELECT 1 FROM ${dialect.quoteTable(table)} WHERE ${where.sql} GROUP BY ${groupCols}) AS ${dialect.quoteIdentifier("_groups")}`,
-		params: where.params
+		sql: `SELECT ${countCol} FROM (SELECT ${groupBy ? "1" : "COUNT(*)"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		params: [...where.params, ...having?.params ?? []]
 	});
 }
 //#endregion
@@ -433,8 +461,53 @@ function buildSelect(dialect, table, where, controls) {
 	});
 }
 /**
+* Marker value for {@link buildUpdate}: the column is assigned its DDL
+* `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
+* {@link fillReplacePayload} for columns whose function default the engine
+* owns; never appears in a patch.
+*/
+const SQL_DEFAULT = Symbol("SQL_DEFAULT");
+/**
+* The columns a full replace assigns on a SQL adapter: every non-ignored
+* descriptor (the same set `CREATE TABLE` emits) except the primary key —
+* the row is matched by the filter, and an omitted PK must never be nulled
+* or re-defaulted. Static value defaults are filled SDK-side before the
+* adapter sees the row, so only native function defaults are flagged.
+*/
+function replaceColumnsFor(fields, nativeFns) {
+	const out = [];
+	for (const fd of fields) {
+		if (fd.ignored || fd.isPrimaryKey) continue;
+		const def = fd.defaultValue;
+		out.push({
+			name: fd.physicalName,
+			useDefault: def?.kind === "fn" && nativeFns.has(def.fn)
+		});
+	}
+	return out;
+}
+/**
+* Turns a (physical-name) replace payload into a FULL row assignment: every
+* column in `columns` the payload omits becomes `null` — or {@link SQL_DEFAULT}
+* when the engine owns its function default — so an UPDATE-based replace never
+* retains a value the caller left out. This is the SQL counterpart of the
+* whole-document replace the memory and MongoDB adapters do natively. The
+* version column is excluded (`buildUpdate` appends the OCC bump itself).
+* Returns a new object; `data` is not mutated.
+*/
+function fillReplacePayload(data, columns, versionColumn) {
+	const full = { ...data };
+	for (const col of columns) {
+		if (col.name === versionColumn || col.name in full) continue;
+		full[col.name] = col.useDefault ? SQL_DEFAULT : null;
+	}
+	return full;
+}
+/**
 * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
 *
+* A value of {@link SQL_DEFAULT} renders as `<col> = DEFAULT` (full replace).
+*
 * Optimistic concurrency control (OCC) hooks:
 * - `versionColumn` — when supplied, the builder appends
 *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
@@ -450,6 +523,10 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 	const setClauses = [];
 	const params = [];
 	for (const [key, value] of Object.entries(data)) {
+		if (value === SQL_DEFAULT) {
+			setClauses.push(`${dialect.quoteIdentifier(key)} = DEFAULT`);
+			continue;
+		}
 		setClauses.push(`${dialect.quoteIdentifier(key)} = ?`);
 		params.push(dialect.toValue(value));
 	}
@@ -583,6 +660,7 @@ exports.AGG_FN_SQL = AGG_FN_SQL;
 exports.EMPTY_AND = EMPTY_AND;
 exports.EMPTY_OR = EMPTY_OR;
 exports.GEO_DISTANCE_ALIAS = GEO_DISTANCE_ALIAS;
+exports.SQL_DEFAULT = SQL_DEFAULT;
 exports.buildAggregateCount = buildAggregateCount;
 exports.buildAggregateSelect = buildAggregateSelect;
 exports.buildCreateView = buildCreateView;
@@ -597,6 +675,7 @@ exports.buildWhere = buildWhere;
 exports.createFilterVisitor = createFilterVisitor;
 exports.defaultValueForType = defaultValueForType;
 exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
+exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
 exports.geoWindowFromControls = geoWindowFromControls;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
@@ -605,5 +684,6 @@ exports.queryNodeToSql = queryNodeToSql;
 exports.queryOpToSql = queryOpToSql;
 exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
+exports.replaceColumnsFor = replaceColumnsFor;
 exports.sqlStringLiteral = sqlStringLiteral;
 exports.toSqlValue = toSqlValue;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
 
 //#region src/dialect.d.ts
 interface TSqlFragment {
@@ -45,10 +45,19 @@ declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
 //#region src/filter-builder.d.ts
+interface TFilterVisitorOptions {
+  /**
+   * Renders a filter key as its SQL operand. Defaults to
+   * `dialect.quoteIdentifier(field)`; the aggregate builder overrides it so a
+   * `$having` key that names an aggregate alias renders the aggregate
+   * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
+   */
+  columnRef?: (field: string) => string;
+}
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
  */
-declare function createFilterVisitor(dialect: SqlDialect): FilterVisitor<TSqlFragment>;
+declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * Translates a filter expression into a parameterized SQL WHERE clause.
  */
@@ -113,9 +122,47 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * Marker value for {@link buildUpdate}: the column is assigned its DDL
+ * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
+ * {@link fillReplacePayload} for columns whose function default the engine
+ * owns; never appears in a patch.
+ */
+declare const SQL_DEFAULT: unique symbol;
+/** One physical column a full replace must assign. */
+interface TReplaceColumn {
+  /** Physical column name. */
+  name: string;
+  /**
+   * `true` when the engine owns this column's function default (`now`,
+   * `uuid`, `increment` listed in the adapter's `nativeDefaultFns()`): an
+   * omitted value re-applies the DDL `DEFAULT` instead of storing NULL.
+   */
+  useDefault: boolean;
+}
+/**
+ * The columns a full replace assigns on a SQL adapter: every non-ignored
+ * descriptor (the same set `CREATE TABLE` emits) except the primary key —
+ * the row is matched by the filter, and an omitted PK must never be nulled
+ * or re-defaulted. Static value defaults are filled SDK-side before the
+ * adapter sees the row, so only native function defaults are flagged.
+ */
+declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
+/**
+ * Turns a (physical-name) replace payload into a FULL row assignment: every
+ * column in `columns` the payload omits becomes `null` — or {@link SQL_DEFAULT}
+ * when the engine owns its function default — so an UPDATE-based replace never
+ * retains a value the caller left out. This is the SQL counterpart of the
+ * whole-document replace the memory and MongoDB adapters do natively. The
+ * version column is excluded (`buildUpdate` appends the OCC bump itself).
+ * Returns a new object; `data` is not mutated.
+ */
+declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string): Record<string, unknown>;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
  *
+ * A value of {@link SQL_DEFAULT} renders as `<col> = DEFAULT` (full replace).
+ *
  * Optimistic concurrency control (OCC) hooks:
  * - `versionColumn` — when supplied, the builder appends
  *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
@@ -168,8 +215,10 @@ declare const AGG_FN_SQL: Record<string, string>;
  */
 declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
- * Builds a COUNT query for the number of distinct groups.
- * Returns `{ count: N }` when executed.
+ * Builds a COUNT query for the number of distinct groups — the groups that
+ * survive `$having` when one is given (the same predicate the row query
+ * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
+ * executed.
  */
 declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
@@ -186,4 +235,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, type SqlDialect, type TGeoCircle, type TGeoWindow, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, 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, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, toSqlValue };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
 
 //#region src/dialect.d.ts
 interface TSqlFragment {
@@ -45,10 +45,19 @@ declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
 //#region src/filter-builder.d.ts
+interface TFilterVisitorOptions {
+  /**
+   * Renders a filter key as its SQL operand. Defaults to
+   * `dialect.quoteIdentifier(field)`; the aggregate builder overrides it so a
+   * `$having` key that names an aggregate alias renders the aggregate
+   * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
+   */
+  columnRef?: (field: string) => string;
+}
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
  */
-declare function createFilterVisitor(dialect: SqlDialect): FilterVisitor<TSqlFragment>;
+declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * Translates a filter expression into a parameterized SQL WHERE clause.
  */
@@ -113,9 +122,47 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * Marker value for {@link buildUpdate}: the column is assigned its DDL
+ * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
+ * {@link fillReplacePayload} for columns whose function default the engine
+ * owns; never appears in a patch.
+ */
+declare const SQL_DEFAULT: unique symbol;
+/** One physical column a full replace must assign. */
+interface TReplaceColumn {
+  /** Physical column name. */
+  name: string;
+  /**
+   * `true` when the engine owns this column's function default (`now`,
+   * `uuid`, `increment` listed in the adapter's `nativeDefaultFns()`): an
+   * omitted value re-applies the DDL `DEFAULT` instead of storing NULL.
+   */
+  useDefault: boolean;
+}
+/**
+ * The columns a full replace assigns on a SQL adapter: every non-ignored
+ * descriptor (the same set `CREATE TABLE` emits) except the primary key —
+ * the row is matched by the filter, and an omitted PK must never be nulled
+ * or re-defaulted. Static value defaults are filled SDK-side before the
+ * adapter sees the row, so only native function defaults are flagged.
+ */
+declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
+/**
+ * Turns a (physical-name) replace payload into a FULL row assignment: every
+ * column in `columns` the payload omits becomes `null` — or {@link SQL_DEFAULT}
+ * when the engine owns its function default — so an UPDATE-based replace never
+ * retains a value the caller left out. This is the SQL counterpart of the
+ * whole-document replace the memory and MongoDB adapters do natively. The
+ * version column is excluded (`buildUpdate` appends the OCC bump itself).
+ * Returns a new object; `data` is not mutated.
+ */
+declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string): Record<string, unknown>;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
  *
+ * A value of {@link SQL_DEFAULT} renders as `<col> = DEFAULT` (full replace).
+ *
  * Optimistic concurrency control (OCC) hooks:
  * - `versionColumn` — when supplied, the builder appends
  *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
@@ -168,8 +215,10 @@ declare const AGG_FN_SQL: Record<string, string>;
  */
 declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
- * Builds a COUNT query for the number of distinct groups.
- * Returns `{ count: N }` when executed.
+ * Builds a COUNT query for the number of distinct groups — the groups that
+ * survive `$having` when one is given (the same predicate the row query
+ * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
+ * executed.
  */
 declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
@@ -186,4 +235,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, type SqlDialect, type TGeoCircle, type TGeoWindow, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, 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, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, toSqlValue };

package/dist/index.mjs

@@ -27,17 +27,18 @@ const EMPTY_OR = {
 /**
 * Creates a dialect-specific filter visitor for `walkFilter`.
 */
-function createFilterVisitor(dialect) {
+function createFilterVisitor(dialect, options) {
+	const columnRef = options?.columnRef ?? ((field) => dialect.quoteIdentifier(field));
 	return {
 		comparison(field, op, value) {
 			if (op === "$geoWithin") {
-				if (dialect.geoWithin) return dialect.geoWithin(dialect.quoteIdentifier(field), value);
+				if (dialect.geoWithin) return dialect.geoWithin(columnRef(field), value);
 				throw new DbError("GEO_NOT_SUPPORTED", [{
 					path: field,
 					message: "$geoWithin is not supported by this adapter"
 				}]);
 			}
-			const col = dialect.quoteIdentifier(field);
+			const col = columnRef(field);
 			const v = dialect.toParam(value);
 			switch (op) {
 				case "$eq":
@@ -329,10 +330,35 @@ const AGG_FN_SQL = {
 	min: "MIN",
 	max: "MAX"
 };
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)`. */
+function aggFnSql(dialect, expr) {
+	return `${AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase()}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)})`;
+}
 function buildAggExpr(dialect, expr) {
-	const fn = AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase();
-	const alias = dialect.quoteIdentifier(resolveAlias(expr));
-	return `${fn}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)}) AS ${alias}`;
+	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`;
+}
+/**
+* ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
+* `undefined` when there is nothing to render. Shared by the row and the
+* count builders so both filter the same group set.
+*
+* 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.
+*/
+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) }));
+	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
+	return {
+		sql: ` HAVING ${fragment.sql}`,
+		params: fragment.params
+	};
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -350,12 +376,10 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
 		sql += ` GROUP BY ${groupCols}`;
 	}
-	if (controls.$having) {
-		const havingFragment = buildWhere(dialect, controls.$having);
-		if (havingFragment.sql !== EMPTY_AND.sql) {
-			sql += ` HAVING ${havingFragment.sql}`;
-			params.push(...havingFragment.params);
-		}
+	const having = havingClause(dialect, controls);
+	if (having) {
+		sql += having.sql;
+		params.push(...having.params);
 	}
 	if (controls.$sort) {
 		const orderParts = [];
@@ -377,19 +401,23 @@ function buildAggregateSelect(dialect, table, where, controls) {
 	});
 }
 /**
-* Builds a COUNT query for the number of distinct groups.
-* Returns `{ count: N }` when executed.
+* Builds a COUNT query for the number of distinct groups — the groups that
+* survive `$having` when one is given (the same predicate the row query
+* renders, so `$count` agrees with the row set). Returns `{ count: N }` when
+* executed.
 */
 function buildAggregateCount(dialect, table, where, controls) {
 	const groupFields = controls.$groupBy;
-	if (!groupFields?.length) return finalizeParams(dialect, {
-		sql: `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+	const having = havingClause(dialect, controls);
+	const countCol = `COUNT(*) AS ${dialect.quoteIdentifier("count")}`;
+	if (!groupFields?.length && !having) return finalizeParams(dialect, {
+		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
 		params: where.params
 	});
-	const groupCols = groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ");
+	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ")}` : "";
 	return finalizeParams(dialect, {
-		sql: `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM (SELECT 1 FROM ${dialect.quoteTable(table)} WHERE ${where.sql} GROUP BY ${groupCols}) AS ${dialect.quoteIdentifier("_groups")}`,
-		params: where.params
+		sql: `SELECT ${countCol} FROM (SELECT ${groupBy ? "1" : "COUNT(*)"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		params: [...where.params, ...having?.params ?? []]
 	});
 }
 //#endregion
@@ -432,8 +460,53 @@ function buildSelect(dialect, table, where, controls) {
 	});
 }
 /**
+* Marker value for {@link buildUpdate}: the column is assigned its DDL
+* `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
+* {@link fillReplacePayload} for columns whose function default the engine
+* owns; never appears in a patch.
+*/
+const SQL_DEFAULT = Symbol("SQL_DEFAULT");
+/**
+* The columns a full replace assigns on a SQL adapter: every non-ignored
+* descriptor (the same set `CREATE TABLE` emits) except the primary key —
+* the row is matched by the filter, and an omitted PK must never be nulled
+* or re-defaulted. Static value defaults are filled SDK-side before the
+* adapter sees the row, so only native function defaults are flagged.
+*/
+function replaceColumnsFor(fields, nativeFns) {
+	const out = [];
+	for (const fd of fields) {
+		if (fd.ignored || fd.isPrimaryKey) continue;
+		const def = fd.defaultValue;
+		out.push({
+			name: fd.physicalName,
+			useDefault: def?.kind === "fn" && nativeFns.has(def.fn)
+		});
+	}
+	return out;
+}
+/**
+* Turns a (physical-name) replace payload into a FULL row assignment: every
+* column in `columns` the payload omits becomes `null` — or {@link SQL_DEFAULT}
+* when the engine owns its function default — so an UPDATE-based replace never
+* retains a value the caller left out. This is the SQL counterpart of the
+* whole-document replace the memory and MongoDB adapters do natively. The
+* version column is excluded (`buildUpdate` appends the OCC bump itself).
+* Returns a new object; `data` is not mutated.
+*/
+function fillReplacePayload(data, columns, versionColumn) {
+	const full = { ...data };
+	for (const col of columns) {
+		if (col.name === versionColumn || col.name in full) continue;
+		full[col.name] = col.useDefault ? SQL_DEFAULT : null;
+	}
+	return full;
+}
+/**
 * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
 *
+* A value of {@link SQL_DEFAULT} renders as `<col> = DEFAULT` (full replace).
+*
 * Optimistic concurrency control (OCC) hooks:
 * - `versionColumn` — when supplied, the builder appends
 *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
@@ -449,6 +522,10 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 	const setClauses = [];
 	const params = [];
 	for (const [key, value] of Object.entries(data)) {
+		if (value === SQL_DEFAULT) {
+			setClauses.push(`${dialect.quoteIdentifier(key)} = DEFAULT`);
+			continue;
+		}
 		setClauses.push(`${dialect.quoteIdentifier(key)} = ?`);
 		params.push(dialect.toValue(value));
 	}
@@ -578,4 +655,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, sqlStringLiteral, toSqlValue };
+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 };

package/package.json

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