@atscript/db-sql-tools 0.1.127 → 0.1.128

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,27 @@ 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))}`;
+}
+/**
+* Renders `$having`. 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 buildHaving(dialect, controls) {
+	const having = controls.$having;
+	const aggregates = controls.$select?.aggregates;
+	if (!aggregates?.length) return buildWhere(dialect, having);
+	const exprByAlias = /* @__PURE__ */ new Map();
+	for (const expr of aggregates) exprByAlias.set((0, _atscript_db_agg.resolveAlias)(expr), aggFnSql(dialect, expr));
+	return (0, _uniqu_core.walkFilter)(having, createFilterVisitor(dialect, { columnRef: (field) => exprByAlias.get(field) ?? dialect.quoteIdentifier(field) })) ?? EMPTY_AND;
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -352,7 +370,7 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		sql += ` GROUP BY ${groupCols}`;
 	}
 	if (controls.$having) {
-		const havingFragment = buildWhere(dialect, controls.$having);
+		const havingFragment = buildHaving(dialect, controls);
 		if (havingFragment.sql !== EMPTY_AND.sql) {
 			sql += ` HAVING ${havingFragment.sql}`;
 			params.push(...havingFragment.params);
@@ -433,8 +451,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 +513,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 +650,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 +665,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 +674,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
@@ -186,4 +233,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
@@ -186,4 +233,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,27 @@ 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))}`;
+}
+/**
+* Renders `$having`. 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 buildHaving(dialect, controls) {
+	const having = controls.$having;
+	const aggregates = controls.$select?.aggregates;
+	if (!aggregates?.length) return buildWhere(dialect, having);
+	const exprByAlias = /* @__PURE__ */ new Map();
+	for (const expr of aggregates) exprByAlias.set(resolveAlias(expr), aggFnSql(dialect, expr));
+	return walkFilter(having, createFilterVisitor(dialect, { columnRef: (field) => exprByAlias.get(field) ?? dialect.quoteIdentifier(field) })) ?? EMPTY_AND;
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -351,7 +369,7 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		sql += ` GROUP BY ${groupCols}`;
 	}
 	if (controls.$having) {
-		const havingFragment = buildWhere(dialect, controls.$having);
+		const havingFragment = buildHaving(dialect, controls);
 		if (havingFragment.sql !== EMPTY_AND.sql) {
 			sql += ` HAVING ${havingFragment.sql}`;
 			params.push(...havingFragment.params);
@@ -432,8 +450,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 +512,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 +645,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.128",
   "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.128"
   },
   "scripts": {
     "build": "vp pack",