@atscript/db-sql-tools 0.1.161 → 0.1.162

package/dist/index.cjs

@@ -213,11 +213,12 @@ function orderKeySql(dialect, expr, desc, nulls, nullTest) {
 * reads the same on every dialect (SQLite's quoted path labels have no escape
 * syntax), so it is rejected rather than escaped.
 *
+* An empty path (the JSON root — a primitive JSON column's value) has no segments.
+*
 * @since 0.1.136
-* @throws for an empty path or a segment that is empty or holds such a character.
+* @throws for a segment that is empty or holds such a character.
 */
 function quotedJsonPathSegments(path) {
-	if (path.length === 0) throw new Error("JSON extraction needs a path below the JSON column");
 	return path.map((seg) => {
 		let ok = seg.length > 0;
 		for (let i = 0; ok && i < seg.length; i++) {
@@ -522,15 +523,24 @@ function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
 /**
+* The value of a single-quoted SQL string literal (`'it''s'` → `it's`) — as
+* engines report a column default — or `undefined` when `literal` is not one.
+* @since 0.1.162
+*/
+function unquoteSqlStringLiteral(literal) {
+	if (literal.length < 2 || !literal.startsWith("'") || !literal.endsWith("'")) return void 0;
+	return literal.slice(1, -1).replace(/''/g, "'");
+}
+/**
 * The SQL string literal of a `$`-rooted JSON path with every segment quoted
 * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
-* `json_type`.
+* `json_type`; an empty path is the JSON root (`'$'`).
 *
 * @since 0.1.136
 * @throws as {@link quotedJsonPathSegments}.
 */
-function jsonDollarPath(path) {
-	return sqlStringLiteral(`$.${quotedJsonPathSegments(path).join(".")}`);
+function jsonDollarPath(path, stringLiteral = sqlStringLiteral) {
+	return stringLiteral(["$", ...quotedJsonPathSegments(path)].join("."));
 }
 /**
 * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
@@ -596,7 +606,7 @@ function defaultValueForType(designType) {
 * respecting the field's designType. Booleans become 0/1, numbers stay unquoted,
 * strings are single-quote-escaped.
 */
-function defaultValueToSqlLiteral(designType, value) {
+function defaultValueToSqlLiteral(designType, value, stringLiteral = sqlStringLiteral) {
 	switch (designType) {
 		case "boolean": return value === "true" || value === "1" ? "1" : "0";
 		case "number":
@@ -605,7 +615,7 @@ function defaultValueToSqlLiteral(designType, value) {
 			const n = Number(value);
 			return Number.isFinite(n) ? String(n) : "0";
 		}
-		default: return sqlStringLiteral(value);
+		default: return stringLiteral(value);
 	}
 }
 const queryOpToSql = {
@@ -617,9 +627,9 @@ const queryOpToSql = {
 	$lte: "<="
 };
 /** An inlined SQL literal for a view-predicate value (DDL — no parameters). */
-function predicateLiteral(value) {
+function predicateLiteral(value, stringLiteral) {
 	if (value === null || value === void 0) return "NULL";
-	if (typeof value === "string") return sqlStringLiteral(value);
+	if (typeof value === "string") return stringLiteral(value);
 	if (typeof value === "number") {
 		if (!Number.isFinite(value)) throw new Error(`Non-finite number ${value} in a view predicate`);
 		return String(value);
@@ -637,18 +647,18 @@ function predicateLiteral(value) {
 * @throws for `matches` (`$regex`) and any other operator — a view predicate
 *   that cannot be rendered fails at sync instead of rendering wrong SQL.
 */
-function queryNodeToSql(node, resolveFieldRef) {
+function queryNodeToSql(node, resolveFieldRef, stringLiteral = sqlStringLiteral) {
 	if ("$and" in node) {
 		const children = node.$and;
 		if (children.length === 0) return EMPTY_AND.sql;
-		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef, stringLiteral)).join(" AND ");
 	}
 	if ("$or" in node) {
 		const children = node.$or;
 		if (children.length === 0) return EMPTY_OR.sql;
-		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef, stringLiteral)).join(" OR ")})`;
 	}
-	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
+	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef, stringLiteral)})`;
 	const comp = node;
 	const leftSql = resolveFieldRef(comp.left);
 	switch (comp.op) {
@@ -657,7 +667,7 @@ function queryNodeToSql(node, resolveFieldRef) {
 		case "$nin": {
 			const values = Array.isArray(comp.right) ? comp.right : [comp.right];
 			if (values.length === 0) return comp.op === "$in" ? EMPTY_OR.sql : EMPTY_AND.sql;
-			const list = values.map((v) => predicateLiteral(v)).join(", ");
+			const list = values.map((v) => predicateLiteral(v, stringLiteral)).join(", ");
 			return `${leftSql} ${comp.op === "$in" ? "IN" : "NOT IN"} (${list})`;
 		}
 		case "$regex": throw new Error("matches is not supported in view predicates");
@@ -667,7 +677,7 @@ function queryNodeToSql(node, resolveFieldRef) {
 	if (!sqlOp) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
 	if ((0, _atscript_db.isFieldRef)(comp.right)) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
 	if (comp.right === null || comp.right === void 0) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
-	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right)}`;
+	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right, stringLiteral)}`;
 }
 //#endregion
 //#region src/agg.ts
@@ -1001,7 +1011,7 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 	const star = c.aggField === "*";
 	const src = star ? "*" : viewSourceExpr(dialect, c);
 	if (!c.aggFilter) return renderAggCall(c.aggFn, src, c.viewColumn);
-	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef);
+	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef, dialect.stringLiteral);
 	const call = renderAggCall(c.aggFn, `CASE WHEN ${predicate} THEN ${star ? "1" : src} END`, c.viewColumn);
 	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
 }
@@ -1092,14 +1102,14 @@ function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
 	let sql = `SELECT ${columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ")} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
-		const condition = queryNodeToSql(join.condition, resolveFieldRef);
+		const condition = queryNodeToSql(join.condition, resolveFieldRef, dialect.stringLiteral);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
 		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
 		const onClause = join.first ? firstRowOn(dialect, join, target, condition, resolveFieldRef) : condition;
 		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
-		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef, dialect.stringLiteral);
 		sql += ` WHERE ${whereClause}`;
 	}
 	if (hasAggregates) {
@@ -1120,7 +1130,7 @@ function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 				if (!col.json) return expr;
 				return dialect.bucketAliasInHaving && groupedColumns().has(col.viewColumn.toLowerCase()) ? `MIN(${expr})` : havingGroupRef(dialect, expr, col.viewColumn);
 			};
-			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			const havingClause = queryNodeToSql(plan.having, havingResolver, dialect.stringLiteral);
 			sql += ` HAVING ${havingClause}`;
 		}
 	}
@@ -1244,8 +1254,9 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 * `table` may be a derived source (a pruned view read, since 0.1.153).
+* `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
 */
-function buildSelect(dialect, table, where, controls) {
+function buildSelect(dialect, table, where, controls, lock) {
 	const cols = buildProjection(dialect, controls?.$select);
 	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
@@ -1260,12 +1271,26 @@ function buildSelect(dialect, table, where, controls) {
 		sql += ` OFFSET ?`;
 		params.push(controls.$skip);
 	}
+	if (lock) sql += readLockSql(lock);
 	return finalizeParams(dialect, {
 		sql,
 		params
 	});
 }
 /**
+* The row-locking clause of a locking read — `" FOR UPDATE"`,
+* `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
+* MySQL 8 share the syntax); `""` without a lock. Goes after `LIMIT` /
+* `OFFSET`. @since 0.1.162
+*/
+function readLockSql(lock) {
+	if (!lock) return "";
+	const mode = lock.mode === "share" ? " FOR SHARE" : " FOR UPDATE";
+	if (lock.wait === "nowait") return `${mode} NOWAIT`;
+	if (lock.wait === "skipLocked") return `${mode} SKIP LOCKED`;
+	return mode;
+}
+/**
 * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
 * nothing. A key with a `$nulls` entry places NULL as asked
 * ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
@@ -1352,13 +1377,14 @@ function replaceColumnsFor(fields, nativeFns) {
 * 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.
+* version column is excluded (`buildUpdate` appends the OCC bump itself), and
+* so are `skip` columns (`@db.onUpdate.inc` counters, since 0.1.162 — the
+* statement increments them). Returns a new object; `data` is not mutated.
 */
-function fillReplacePayload(data, columns, versionColumn) {
+function fillReplacePayload(data, columns, versionColumn, skip) {
 	const full = { ...data };
 	for (const col of columns) {
-		if (col.name === versionColumn || col.name in full) continue;
+		if (col.name === versionColumn || col.name in full || skip?.includes(col.name)) continue;
 		full[col.name] = col.useDefault ? SQL_DEFAULT : null;
 	}
 	return full;
@@ -1381,6 +1407,9 @@ function fillReplacePayload(data, columns, versionColumn) {
 *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
 *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
 *   without `versionColumn` is a programmer error and throws.
+*
+* `limit` renders `LIMIT n`; as `{ count, orderBy }` (since 0.1.162) also
+* `ORDER BY <orderBy>` before it (MySQL's bounded `UPDATE`).
 */
 function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, expectedVersion) {
 	const setClauses = [];
@@ -1414,10 +1443,8 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 			whereParams.push(expectedVersion);
 		}
 	}
-	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${whereSql}`;
-	if (limit !== void 0) sql += ` LIMIT ${limit}`;
 	return finalizeParams(dialect, {
-		sql,
+		sql: `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${whereSql}` + limitSql(limit),
 		params: [
 			...params,
 			...where.params,
@@ -1426,16 +1453,21 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 	});
 }
 /**
-* Builds a DELETE ... WHERE statement with optional LIMIT.
+* Builds a DELETE ... WHERE statement with an optional LIMIT — as
+* `{ count, orderBy }` (since 0.1.162) with an ORDER BY before it.
 */
 function buildDelete(dialect, table, where, limit) {
-	let sql = `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
-	if (limit !== void 0) sql += ` LIMIT ${limit}`;
 	return finalizeParams(dialect, {
-		sql,
+		sql: `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}` + limitSql(limit),
 		params: where.params
 	});
 }
+/** ` [ORDER BY …] LIMIT n` of an UPDATE / DELETE, or `""` when unbounded. */
+function limitSql(limit) {
+	if (limit === void 0) return "";
+	if (typeof limit === "number") return ` LIMIT ${limit}`;
+	return (limit.orderBy ? ` ORDER BY ${limit.orderBy}` : "") + ` LIMIT ${limit.count}`;
+}
 /**
 * The expression a `@db.column.derived` column is generated from: the
 * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
@@ -1483,6 +1515,29 @@ function buildKeyViolationCount(dialect, quotedTable, columns) {
 	const noNull = cols.map((c) => `${c} IS NOT NULL`).join(" AND ");
 	return `SELECT (SELECT COUNT(*) FROM ${quotedTable} WHERE ${anyNull}) + (SELECT COALESCE(SUM(${dialect.quoteIdentifier("n")}), 0) FROM (SELECT COUNT(*) AS ${dialect.quoteIdentifier("n")} FROM ${quotedTable} WHERE ${noNull} GROUP BY ${cols.join(", ")} HAVING COUNT(*) > 1) ${dialect.quoteIdentifier("d")}) AS ` + dialect.quoteIdentifier("violations");
 }
+/**
+* Narrows an UPDATE / DELETE to the first rows of a bounded write
+* ({@link TDbWriteLimit}, since 0.1.162) on engines without
+* `UPDATE/DELETE … ORDER BY … LIMIT`: `where AND <key> IN (SELECT <key> FROM
+* <table> WHERE where ORDER BY … LIMIT n)`. `keyCols` are already-quoted key
+* expressions (the primary key columns, or SQLite's `rowid`). The filter is
+* repeated on the outer statement so a row changed out of it meanwhile is
+* left alone. Unfinalized (`?` placeholders).
+*/
+function writeLimitWhere(dialect, quotedTable, keyCols, where, bound) {
+	const cols = keyCols.join(", ");
+	const key = keyCols.length === 1 ? cols : `(${cols})`;
+	const order = orderByList(dialect, bound.sort, bound.nulls);
+	return {
+		sql: `${where.sql} AND ${key} IN (SELECT ${cols} FROM ${quotedTable} WHERE ${where.sql} ORDER BY ${order} LIMIT ${writeLimitCount(bound)})`,
+		params: [...where.params, ...where.params]
+	};
+}
+/** The validated row count of a bounded write — a positive safe integer, rendered inline. */
+function writeLimitCount(bound) {
+	if (!Number.isSafeInteger(bound.limit) || bound.limit < 1) throw new Error(`Invalid write limit: ${String(bound.limit)}`);
+	return bound.limit;
+}
 //#endregion
 //#region src/geo.ts
 /**
@@ -1851,6 +1906,7 @@ exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;
 exports.queryOpToSql = queryOpToSql;
 exports.quotedJsonPathSegments = quotedJsonPathSegments;
+exports.readLockSql = readLockSql;
 exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
 exports.renderArith = renderArith;
@@ -1859,5 +1915,8 @@ exports.sqlStringLiteral = sqlStringLiteral;
 exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;
 exports.stripPartitionRowNumber = stripPartitionRowNumber;
 exports.toSqlValue = toSqlValue;
+exports.unquoteSqlStringLiteral = unquoteSqlStringLiteral;
 exports.vectorDistanceSource = vectorDistanceSource;
 exports.viewReadSource = viewReadSource;
+exports.writeLimitCount = writeLimitCount;
+exports.writeLimitWhere = writeLimitWhere;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TJsonCopyTarget, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReadLock, TDbReferentialAction, TDbWriteLimit, TFieldOps, TJsonCopyTarget, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor, NullsPlacement } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
@@ -19,6 +19,14 @@ interface SqlDialect {
   quoteTable(name: string): string;
   /** SQL literal for unlimited LIMIT (SQLite: '-1', MySQL: '18446744073709551615') */
   unlimitedLimit: string;
+  /**
+   * Renders a string as an SQL string literal inlined into SQL text (view
+   * predicates, JSON paths, defaults): `sqlStringLiteral` (quotes doubled),
+   * or — for a dialect whose literals treat `\` as an escape (MySQL) — one
+   * that escapes it too.
+   * @since 0.1.162
+   */
+  stringLiteral: (value: string) => string;
   /**
    * The optimizer hint asking the engine to MERGE the derived table `alias`
    * into the SELECT reading it (MySQL: `/*+ MERGE(\`alias\`) *\/`) — carried
@@ -251,8 +259,10 @@ declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean, n
  * reads the same on every dialect (SQLite's quoted path labels have no escape
  * syntax), so it is rejected rather than escaped.
  *
+ * An empty path (the JSON root — a primitive JSON column's value) has no segments.
+ *
  * @since 0.1.136
- * @throws for an empty path or a segment that is empty or holds such a character.
+ * @throws for a segment that is empty or holds such a character.
  */
 declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
@@ -555,8 +565,16 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  * `table` may be a derived source (a pruned view read, since 0.1.153).
+ * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+ */
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock): TSqlFragment;
+/**
+ * The row-locking clause of a locking read — `" FOR UPDATE"`,
+ * `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
+ * MySQL 8 share the syntax); `""` without a lock. Goes after `LIMIT` /
+ * `OFFSET`. @since 0.1.162
  */
-declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+declare function readLockSql(lock: TDbReadLock | undefined): string;
 /**
  * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
  * nothing. A key with a `$nulls` entry places NULL as asked
@@ -618,10 +636,11 @@ declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: R
  * 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.
+ * version column is excluded (`buildUpdate` appends the OCC bump itself), and
+ * so are `skip` columns (`@db.onUpdate.inc` counters, since 0.1.162 — the
+ * statement increments them). Returns a new object; `data` is not mutated.
  */
-declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string): Record<string, unknown>;
+declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string, skip?: readonly string[]): Record<string, unknown>;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
  *
@@ -640,12 +659,26 @@ declare function fillReplacePayload(data: Record<string, unknown>, columns: read
  *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
  *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
  *   without `versionColumn` is a programmer error and throws.
+ *
+ * `limit` renders `LIMIT n`; as `{ count, orderBy }` (since 0.1.162) also
+ * `ORDER BY <orderBy>` before it (MySQL's bounded `UPDATE`).
  */
-declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
+declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number | TSqlWriteLimit, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
 /**
- * Builds a DELETE ... WHERE statement with optional LIMIT.
+ * Builds a DELETE ... WHERE statement with an optional LIMIT — as
+ * `{ count, orderBy }` (since 0.1.162) with an ORDER BY before it.
  */
-declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number): TSqlFragment;
+declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number | TSqlWriteLimit): TSqlFragment;
+/**
+ * The row bound of an `UPDATE` / `DELETE` on engines that render
+ * `ORDER BY … LIMIT n` on writes (MySQL; since 0.1.162).
+ */
+interface TSqlWriteLimit {
+  /** Rows the statement may touch (rendered inline). */
+  count: number;
+  /** Rendered `ORDER BY` list (see {@link orderByList}). */
+  orderBy?: string;
+}
 /**
  * The expression a `@db.column.derived` column is generated from: the
  * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
@@ -673,19 +706,39 @@ declare function buildProjection(dialect: SqlDialect, select?: UniquSelect, qual
  * @since 0.1.155
  */
 declare function buildKeyViolationCount(dialect: SqlDialect, quotedTable: string, columns: readonly string[]): string;
+/**
+ * Narrows an UPDATE / DELETE to the first rows of a bounded write
+ * ({@link TDbWriteLimit}, since 0.1.162) on engines without
+ * `UPDATE/DELETE … ORDER BY … LIMIT`: `where AND <key> IN (SELECT <key> FROM
+ * <table> WHERE where ORDER BY … LIMIT n)`. `keyCols` are already-quoted key
+ * expressions (the primary key columns, or SQLite's `rowid`). The filter is
+ * repeated on the outer statement so a row changed out of it meanwhile is
+ * left alone. Unfinalized (`?` placeholders).
+ */
+declare function writeLimitWhere(dialect: SqlDialect, quotedTable: string, keyCols: readonly string[], where: TSqlFragment, bound: TDbWriteLimit): TSqlFragment;
+/** The validated row count of a bounded write — a positive safe integer, rendered inline. */
+declare function writeLimitCount(bound: TDbWriteLimit): number;
 //#endregion
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * The value of a single-quoted SQL string literal (`'it''s'` → `it's`) — as
+ * engines report a column default — or `undefined` when `literal` is not one.
+ * @since 0.1.162
+ */
+declare function unquoteSqlStringLiteral(literal: string): string | undefined;
 /**
  * The SQL string literal of a `$`-rooted JSON path with every segment quoted
  * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
- * `json_type`.
+ * `json_type`; an empty path is the JSON root (`'$'`).
  *
  * @since 0.1.136
  * @throws as {@link quotedJsonPathSegments}.
  */
-declare function jsonDollarPath(path: readonly string[]): string;
+declare function jsonDollarPath(path: readonly string[], /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 /**
  * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
  *
@@ -714,7 +767,9 @@ declare function defaultValueForType(designType: string): string;
  * respecting the field's designType. Booleans become 0/1, numbers stay unquoted,
  * strings are single-quote-escaped.
  */
-declare function defaultValueToSqlLiteral(designType: string, value: string): string;
+declare function defaultValueToSqlLiteral(designType: string, value: string, /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 declare const queryOpToSql: Record<string, string>;
 /**
  * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
@@ -726,7 +781,9 @@ declare const queryOpToSql: Record<string, string>;
  * @throws for `matches` (`$regex`) and any other operator — a view predicate
  *   that cannot be rendered fails at sync instead of rendering wrong SQL.
  */
-declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string, /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 //#endregion
 //#region src/agg.d.ts
 /**
@@ -825,4 +882,4 @@ declare function buildJsonColumnCopy(dialect: SqlDialect, table: string, source:
  */
 declare function buildJsonifyText(dialect: SqlDialect, table: string, column: string): string;
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TJsonCopyTarget, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReadLock, TDbReferentialAction, TDbWriteLimit, TFieldOps, TJsonCopyTarget, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor, NullsPlacement } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
@@ -19,6 +19,14 @@ interface SqlDialect {
   quoteTable(name: string): string;
   /** SQL literal for unlimited LIMIT (SQLite: '-1', MySQL: '18446744073709551615') */
   unlimitedLimit: string;
+  /**
+   * Renders a string as an SQL string literal inlined into SQL text (view
+   * predicates, JSON paths, defaults): `sqlStringLiteral` (quotes doubled),
+   * or — for a dialect whose literals treat `\` as an escape (MySQL) — one
+   * that escapes it too.
+   * @since 0.1.162
+   */
+  stringLiteral: (value: string) => string;
   /**
    * The optimizer hint asking the engine to MERGE the derived table `alias`
    * into the SELECT reading it (MySQL: `/*+ MERGE(\`alias\`) *\/`) — carried
@@ -251,8 +259,10 @@ declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean, n
  * reads the same on every dialect (SQLite's quoted path labels have no escape
  * syntax), so it is rejected rather than escaped.
  *
+ * An empty path (the JSON root — a primitive JSON column's value) has no segments.
+ *
  * @since 0.1.136
- * @throws for an empty path or a segment that is empty or holds such a character.
+ * @throws for a segment that is empty or holds such a character.
  */
 declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
@@ -555,8 +565,16 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  * `table` may be a derived source (a pruned view read, since 0.1.153).
+ * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+ */
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock): TSqlFragment;
+/**
+ * The row-locking clause of a locking read — `" FOR UPDATE"`,
+ * `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
+ * MySQL 8 share the syntax); `""` without a lock. Goes after `LIMIT` /
+ * `OFFSET`. @since 0.1.162
  */
-declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+declare function readLockSql(lock: TDbReadLock | undefined): string;
 /**
  * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
  * nothing. A key with a `$nulls` entry places NULL as asked
@@ -618,10 +636,11 @@ declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: R
  * 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.
+ * version column is excluded (`buildUpdate` appends the OCC bump itself), and
+ * so are `skip` columns (`@db.onUpdate.inc` counters, since 0.1.162 — the
+ * statement increments them). Returns a new object; `data` is not mutated.
  */
-declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string): Record<string, unknown>;
+declare function fillReplacePayload(data: Record<string, unknown>, columns: readonly TReplaceColumn[], versionColumn?: string, skip?: readonly string[]): Record<string, unknown>;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
  *
@@ -640,12 +659,26 @@ declare function fillReplacePayload(data: Record<string, unknown>, columns: read
  *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
  *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
  *   without `versionColumn` is a programmer error and throws.
+ *
+ * `limit` renders `LIMIT n`; as `{ count, orderBy }` (since 0.1.162) also
+ * `ORDER BY <orderBy>` before it (MySQL's bounded `UPDATE`).
  */
-declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
+declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number | TSqlWriteLimit, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
 /**
- * Builds a DELETE ... WHERE statement with optional LIMIT.
+ * Builds a DELETE ... WHERE statement with an optional LIMIT — as
+ * `{ count, orderBy }` (since 0.1.162) with an ORDER BY before it.
  */
-declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number): TSqlFragment;
+declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number | TSqlWriteLimit): TSqlFragment;
+/**
+ * The row bound of an `UPDATE` / `DELETE` on engines that render
+ * `ORDER BY … LIMIT n` on writes (MySQL; since 0.1.162).
+ */
+interface TSqlWriteLimit {
+  /** Rows the statement may touch (rendered inline). */
+  count: number;
+  /** Rendered `ORDER BY` list (see {@link orderByList}). */
+  orderBy?: string;
+}
 /**
  * The expression a `@db.column.derived` column is generated from: the
  * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
@@ -673,19 +706,39 @@ declare function buildProjection(dialect: SqlDialect, select?: UniquSelect, qual
  * @since 0.1.155
  */
 declare function buildKeyViolationCount(dialect: SqlDialect, quotedTable: string, columns: readonly string[]): string;
+/**
+ * Narrows an UPDATE / DELETE to the first rows of a bounded write
+ * ({@link TDbWriteLimit}, since 0.1.162) on engines without
+ * `UPDATE/DELETE … ORDER BY … LIMIT`: `where AND <key> IN (SELECT <key> FROM
+ * <table> WHERE where ORDER BY … LIMIT n)`. `keyCols` are already-quoted key
+ * expressions (the primary key columns, or SQLite's `rowid`). The filter is
+ * repeated on the outer statement so a row changed out of it meanwhile is
+ * left alone. Unfinalized (`?` placeholders).
+ */
+declare function writeLimitWhere(dialect: SqlDialect, quotedTable: string, keyCols: readonly string[], where: TSqlFragment, bound: TDbWriteLimit): TSqlFragment;
+/** The validated row count of a bounded write — a positive safe integer, rendered inline. */
+declare function writeLimitCount(bound: TDbWriteLimit): number;
 //#endregion
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * The value of a single-quoted SQL string literal (`'it''s'` → `it's`) — as
+ * engines report a column default — or `undefined` when `literal` is not one.
+ * @since 0.1.162
+ */
+declare function unquoteSqlStringLiteral(literal: string): string | undefined;
 /**
  * The SQL string literal of a `$`-rooted JSON path with every segment quoted
  * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
- * `json_type`.
+ * `json_type`; an empty path is the JSON root (`'$'`).
  *
  * @since 0.1.136
  * @throws as {@link quotedJsonPathSegments}.
  */
-declare function jsonDollarPath(path: readonly string[]): string;
+declare function jsonDollarPath(path: readonly string[], /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 /**
  * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
  *
@@ -714,7 +767,9 @@ declare function defaultValueForType(designType: string): string;
  * respecting the field's designType. Booleans become 0/1, numbers stay unquoted,
  * strings are single-quote-escaped.
  */
-declare function defaultValueToSqlLiteral(designType: string, value: string): string;
+declare function defaultValueToSqlLiteral(designType: string, value: string, /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 declare const queryOpToSql: Record<string, string>;
 /**
  * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
@@ -726,7 +781,9 @@ declare const queryOpToSql: Record<string, string>;
  * @throws for `matches` (`$regex`) and any other operator — a view predicate
  *   that cannot be rendered fails at sync instead of rendering wrong SQL.
  */
-declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string, /** The dialect's string literal (`SqlDialect.stringLiteral`). @since 0.1.162 */
+
+stringLiteral?: (value: string) => string): string;
 //#endregion
 //#region src/agg.d.ts
 /**
@@ -825,4 +882,4 @@ declare function buildJsonColumnCopy(dialect: SqlDialect, table: string, source:
  */
 declare function buildJsonifyText(dialect: SqlDialect, table: string, column: string): string;
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/dist/index.mjs

@@ -212,11 +212,12 @@ function orderKeySql(dialect, expr, desc, nulls, nullTest) {
 * reads the same on every dialect (SQLite's quoted path labels have no escape
 * syntax), so it is rejected rather than escaped.
 *
+* An empty path (the JSON root — a primitive JSON column's value) has no segments.
+*
 * @since 0.1.136
-* @throws for an empty path or a segment that is empty or holds such a character.
+* @throws for a segment that is empty or holds such a character.
 */
 function quotedJsonPathSegments(path) {
-	if (path.length === 0) throw new Error("JSON extraction needs a path below the JSON column");
 	return path.map((seg) => {
 		let ok = seg.length > 0;
 		for (let i = 0; ok && i < seg.length; i++) {
@@ -521,15 +522,24 @@ function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
 /**
+* The value of a single-quoted SQL string literal (`'it''s'` → `it's`) — as
+* engines report a column default — or `undefined` when `literal` is not one.
+* @since 0.1.162
+*/
+function unquoteSqlStringLiteral(literal) {
+	if (literal.length < 2 || !literal.startsWith("'") || !literal.endsWith("'")) return void 0;
+	return literal.slice(1, -1).replace(/''/g, "'");
+}
+/**
 * The SQL string literal of a `$`-rooted JSON path with every segment quoted
 * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
-* `json_type`.
+* `json_type`; an empty path is the JSON root (`'$'`).
 *
 * @since 0.1.136
 * @throws as {@link quotedJsonPathSegments}.
 */
-function jsonDollarPath(path) {
-	return sqlStringLiteral(`$.${quotedJsonPathSegments(path).join(".")}`);
+function jsonDollarPath(path, stringLiteral = sqlStringLiteral) {
+	return stringLiteral(["$", ...quotedJsonPathSegments(path)].join("."));
 }
 /**
 * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
@@ -595,7 +605,7 @@ function defaultValueForType(designType) {
 * respecting the field's designType. Booleans become 0/1, numbers stay unquoted,
 * strings are single-quote-escaped.
 */
-function defaultValueToSqlLiteral(designType, value) {
+function defaultValueToSqlLiteral(designType, value, stringLiteral = sqlStringLiteral) {
 	switch (designType) {
 		case "boolean": return value === "true" || value === "1" ? "1" : "0";
 		case "number":
@@ -604,7 +614,7 @@ function defaultValueToSqlLiteral(designType, value) {
 			const n = Number(value);
 			return Number.isFinite(n) ? String(n) : "0";
 		}
-		default: return sqlStringLiteral(value);
+		default: return stringLiteral(value);
 	}
 }
 const queryOpToSql = {
@@ -616,9 +626,9 @@ const queryOpToSql = {
 	$lte: "<="
 };
 /** An inlined SQL literal for a view-predicate value (DDL — no parameters). */
-function predicateLiteral(value) {
+function predicateLiteral(value, stringLiteral) {
 	if (value === null || value === void 0) return "NULL";
-	if (typeof value === "string") return sqlStringLiteral(value);
+	if (typeof value === "string") return stringLiteral(value);
 	if (typeof value === "number") {
 		if (!Number.isFinite(value)) throw new Error(`Non-finite number ${value} in a view predicate`);
 		return String(value);
@@ -636,18 +646,18 @@ function predicateLiteral(value) {
 * @throws for `matches` (`$regex`) and any other operator — a view predicate
 *   that cannot be rendered fails at sync instead of rendering wrong SQL.
 */
-function queryNodeToSql(node, resolveFieldRef) {
+function queryNodeToSql(node, resolveFieldRef, stringLiteral = sqlStringLiteral) {
 	if ("$and" in node) {
 		const children = node.$and;
 		if (children.length === 0) return EMPTY_AND.sql;
-		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef, stringLiteral)).join(" AND ");
 	}
 	if ("$or" in node) {
 		const children = node.$or;
 		if (children.length === 0) return EMPTY_OR.sql;
-		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef, stringLiteral)).join(" OR ")})`;
 	}
-	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
+	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef, stringLiteral)})`;
 	const comp = node;
 	const leftSql = resolveFieldRef(comp.left);
 	switch (comp.op) {
@@ -656,7 +666,7 @@ function queryNodeToSql(node, resolveFieldRef) {
 		case "$nin": {
 			const values = Array.isArray(comp.right) ? comp.right : [comp.right];
 			if (values.length === 0) return comp.op === "$in" ? EMPTY_OR.sql : EMPTY_AND.sql;
-			const list = values.map((v) => predicateLiteral(v)).join(", ");
+			const list = values.map((v) => predicateLiteral(v, stringLiteral)).join(", ");
 			return `${leftSql} ${comp.op === "$in" ? "IN" : "NOT IN"} (${list})`;
 		}
 		case "$regex": throw new Error("matches is not supported in view predicates");
@@ -666,7 +676,7 @@ function queryNodeToSql(node, resolveFieldRef) {
 	if (!sqlOp) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
 	if (isFieldRef(comp.right)) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
 	if (comp.right === null || comp.right === void 0) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
-	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right)}`;
+	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right, stringLiteral)}`;
 }
 //#endregion
 //#region src/agg.ts
@@ -1000,7 +1010,7 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 	const star = c.aggField === "*";
 	const src = star ? "*" : viewSourceExpr(dialect, c);
 	if (!c.aggFilter) return renderAggCall(c.aggFn, src, c.viewColumn);
-	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef);
+	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef, dialect.stringLiteral);
 	const call = renderAggCall(c.aggFn, `CASE WHEN ${predicate} THEN ${star ? "1" : src} END`, c.viewColumn);
 	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
 }
@@ -1091,14 +1101,14 @@ function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
 	let sql = `SELECT ${columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ")} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
-		const condition = queryNodeToSql(join.condition, resolveFieldRef);
+		const condition = queryNodeToSql(join.condition, resolveFieldRef, dialect.stringLiteral);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
 		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
 		const onClause = join.first ? firstRowOn(dialect, join, target, condition, resolveFieldRef) : condition;
 		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
-		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef, dialect.stringLiteral);
 		sql += ` WHERE ${whereClause}`;
 	}
 	if (hasAggregates) {
@@ -1119,7 +1129,7 @@ function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 				if (!col.json) return expr;
 				return dialect.bucketAliasInHaving && groupedColumns().has(col.viewColumn.toLowerCase()) ? `MIN(${expr})` : havingGroupRef(dialect, expr, col.viewColumn);
 			};
-			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			const havingClause = queryNodeToSql(plan.having, havingResolver, dialect.stringLiteral);
 			sql += ` HAVING ${havingClause}`;
 		}
 	}
@@ -1243,8 +1253,9 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 * `table` may be a derived source (a pruned view read, since 0.1.153).
+* `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
 */
-function buildSelect(dialect, table, where, controls) {
+function buildSelect(dialect, table, where, controls, lock) {
 	const cols = buildProjection(dialect, controls?.$select);
 	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
@@ -1259,12 +1270,26 @@ function buildSelect(dialect, table, where, controls) {
 		sql += ` OFFSET ?`;
 		params.push(controls.$skip);
 	}
+	if (lock) sql += readLockSql(lock);
 	return finalizeParams(dialect, {
 		sql,
 		params
 	});
 }
 /**
+* The row-locking clause of a locking read — `" FOR UPDATE"`,
+* `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
+* MySQL 8 share the syntax); `""` without a lock. Goes after `LIMIT` /
+* `OFFSET`. @since 0.1.162
+*/
+function readLockSql(lock) {
+	if (!lock) return "";
+	const mode = lock.mode === "share" ? " FOR SHARE" : " FOR UPDATE";
+	if (lock.wait === "nowait") return `${mode} NOWAIT`;
+	if (lock.wait === "skipLocked") return `${mode} SKIP LOCKED`;
+	return mode;
+}
+/**
 * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
 * nothing. A key with a `$nulls` entry places NULL as asked
 * ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
@@ -1351,13 +1376,14 @@ function replaceColumnsFor(fields, nativeFns) {
 * 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.
+* version column is excluded (`buildUpdate` appends the OCC bump itself), and
+* so are `skip` columns (`@db.onUpdate.inc` counters, since 0.1.162 — the
+* statement increments them). Returns a new object; `data` is not mutated.
 */
-function fillReplacePayload(data, columns, versionColumn) {
+function fillReplacePayload(data, columns, versionColumn, skip) {
 	const full = { ...data };
 	for (const col of columns) {
-		if (col.name === versionColumn || col.name in full) continue;
+		if (col.name === versionColumn || col.name in full || skip?.includes(col.name)) continue;
 		full[col.name] = col.useDefault ? SQL_DEFAULT : null;
 	}
 	return full;
@@ -1380,6 +1406,9 @@ function fillReplacePayload(data, columns, versionColumn) {
 *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
 *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
 *   without `versionColumn` is a programmer error and throws.
+*
+* `limit` renders `LIMIT n`; as `{ count, orderBy }` (since 0.1.162) also
+* `ORDER BY <orderBy>` before it (MySQL's bounded `UPDATE`).
 */
 function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, expectedVersion) {
 	const setClauses = [];
@@ -1413,10 +1442,8 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 			whereParams.push(expectedVersion);
 		}
 	}
-	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${whereSql}`;
-	if (limit !== void 0) sql += ` LIMIT ${limit}`;
 	return finalizeParams(dialect, {
-		sql,
+		sql: `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${whereSql}` + limitSql(limit),
 		params: [
 			...params,
 			...where.params,
@@ -1425,16 +1452,21 @@ function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, exp
 	});
 }
 /**
-* Builds a DELETE ... WHERE statement with optional LIMIT.
+* Builds a DELETE ... WHERE statement with an optional LIMIT — as
+* `{ count, orderBy }` (since 0.1.162) with an ORDER BY before it.
 */
 function buildDelete(dialect, table, where, limit) {
-	let sql = `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
-	if (limit !== void 0) sql += ` LIMIT ${limit}`;
 	return finalizeParams(dialect, {
-		sql,
+		sql: `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}` + limitSql(limit),
 		params: where.params
 	});
 }
+/** ` [ORDER BY …] LIMIT n` of an UPDATE / DELETE, or `""` when unbounded. */
+function limitSql(limit) {
+	if (limit === void 0) return "";
+	if (typeof limit === "number") return ` LIMIT ${limit}`;
+	return (limit.orderBy ? ` ORDER BY ${limit.orderBy}` : "") + ` LIMIT ${limit.count}`;
+}
 /**
 * The expression a `@db.column.derived` column is generated from: the
 * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
@@ -1482,6 +1514,29 @@ function buildKeyViolationCount(dialect, quotedTable, columns) {
 	const noNull = cols.map((c) => `${c} IS NOT NULL`).join(" AND ");
 	return `SELECT (SELECT COUNT(*) FROM ${quotedTable} WHERE ${anyNull}) + (SELECT COALESCE(SUM(${dialect.quoteIdentifier("n")}), 0) FROM (SELECT COUNT(*) AS ${dialect.quoteIdentifier("n")} FROM ${quotedTable} WHERE ${noNull} GROUP BY ${cols.join(", ")} HAVING COUNT(*) > 1) ${dialect.quoteIdentifier("d")}) AS ` + dialect.quoteIdentifier("violations");
 }
+/**
+* Narrows an UPDATE / DELETE to the first rows of a bounded write
+* ({@link TDbWriteLimit}, since 0.1.162) on engines without
+* `UPDATE/DELETE … ORDER BY … LIMIT`: `where AND <key> IN (SELECT <key> FROM
+* <table> WHERE where ORDER BY … LIMIT n)`. `keyCols` are already-quoted key
+* expressions (the primary key columns, or SQLite's `rowid`). The filter is
+* repeated on the outer statement so a row changed out of it meanwhile is
+* left alone. Unfinalized (`?` placeholders).
+*/
+function writeLimitWhere(dialect, quotedTable, keyCols, where, bound) {
+	const cols = keyCols.join(", ");
+	const key = keyCols.length === 1 ? cols : `(${cols})`;
+	const order = orderByList(dialect, bound.sort, bound.nulls);
+	return {
+		sql: `${where.sql} AND ${key} IN (SELECT ${cols} FROM ${quotedTable} WHERE ${where.sql} ORDER BY ${order} LIMIT ${writeLimitCount(bound)})`,
+		params: [...where.params, ...where.params]
+	};
+}
+/** The validated row count of a bounded write — a positive safe integer, rendered inline. */
+function writeLimitCount(bound) {
+	if (!Number.isSafeInteger(bound.limit) || bound.limit < 1) throw new Error(`Invalid write limit: ${String(bound.limit)}`);
+	return bound.limit;
+}
 //#endregion
 //#region src/geo.ts
 /**
@@ -1795,4 +1850,4 @@ function buildJsonifyText(dialect, table, column) {
 	return `UPDATE ${dialect.quoteTable(table)} SET ${col} = ${dialect.jsonFromText(col)} WHERE ${col} IS NOT NULL`;
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.161",
+  "version": "0.1.162",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -38,11 +38,11 @@
   },
   "devDependencies": {
     "@uniqu/core": "^0.1.15",
-    "unplugin-atscript": "^0.1.108"
+    "unplugin-atscript": "^0.1.109"
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.15",
-    "@atscript/db": "^0.1.161"
+    "@atscript/db": "^0.1.162"
   },
   "scripts": {
     "build": "vp pack",