@atscript/db-sql-tools 0.1.83 → 0.1.85

package/dist/index.cjs

@@ -318,8 +318,19 @@ function buildSelect(dialect, table, where, controls) {
 }
 /**
 * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+*
+* Optimistic concurrency control (OCC) hooks:
+* - `versionColumn` — when supplied, the builder appends
+*   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
+*   `versionColumn` is set, regardless of whether `expectedVersion` is
+*   supplied. If the version column doesn't auto-increment on every write,
+*   OCC silently degrades to no protection.
+* - `expectedVersion` — when supplied, the builder appends
+*   `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.
 */
-function buildUpdate(dialect, table, data, where, limit, ops) {
+function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, expectedVersion) {
 	const setClauses = [];
 	const params = [];
 	for (const [key, value] of Object.entries(data)) {
@@ -336,11 +347,26 @@ function buildUpdate(dialect, table, data, where, limit, ops) {
 		setClauses.push(`${col} = ${col} * ?`);
 		params.push(ops.mul[key]);
 	}
-	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${where.sql}`;
+	if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("buildUpdate: expectedVersion requires versionColumn");
+	let whereSql = where.sql;
+	const whereParams = [];
+	if (versionColumn !== void 0) {
+		const vcol = dialect.quoteIdentifier(versionColumn);
+		setClauses.push(`${vcol} = ${vcol} + 1`);
+		if (expectedVersion !== void 0) {
+			whereSql += ` AND ${vcol} = ?`;
+			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,
-		params: [...params, ...where.params]
+		params: [
+			...params,
+			...where.params,
+			...whereParams
+		]
 	});
 }
 /**

package/dist/index.d.cts

@@ -53,8 +53,19 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+ *
+ * Optimistic concurrency control (OCC) hooks:
+ * - `versionColumn` — when supplied, the builder appends
+ *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
+ *   `versionColumn` is set, regardless of whether `expectedVersion` is
+ *   supplied. If the version column doesn't auto-increment on every write,
+ *   OCC silently degrades to no protection.
+ * - `expectedVersion` — when supplied, the builder appends
+ *   `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.
  */
-declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps): TSqlFragment;
+declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
 /**
  * Builds a DELETE ... WHERE statement with optional LIMIT.
  */

package/dist/index.d.mts

@@ -53,8 +53,19 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
 /**
  * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+ *
+ * Optimistic concurrency control (OCC) hooks:
+ * - `versionColumn` — when supplied, the builder appends
+ *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
+ *   `versionColumn` is set, regardless of whether `expectedVersion` is
+ *   supplied. If the version column doesn't auto-increment on every write,
+ *   OCC silently degrades to no protection.
+ * - `expectedVersion` — when supplied, the builder appends
+ *   `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.
  */
-declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps): TSqlFragment;
+declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number, ops?: TFieldOps, versionColumn?: string, expectedVersion?: number): TSqlFragment;
 /**
  * Builds a DELETE ... WHERE statement with optional LIMIT.
  */

package/dist/index.mjs

@@ -317,8 +317,19 @@ function buildSelect(dialect, table, where, controls) {
 }
 /**
 * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+*
+* Optimistic concurrency control (OCC) hooks:
+* - `versionColumn` — when supplied, the builder appends
+*   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
+*   `versionColumn` is set, regardless of whether `expectedVersion` is
+*   supplied. If the version column doesn't auto-increment on every write,
+*   OCC silently degrades to no protection.
+* - `expectedVersion` — when supplied, the builder appends
+*   `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.
 */
-function buildUpdate(dialect, table, data, where, limit, ops) {
+function buildUpdate(dialect, table, data, where, limit, ops, versionColumn, expectedVersion) {
 	const setClauses = [];
 	const params = [];
 	for (const [key, value] of Object.entries(data)) {
@@ -335,11 +346,26 @@ function buildUpdate(dialect, table, data, where, limit, ops) {
 		setClauses.push(`${col} = ${col} * ?`);
 		params.push(ops.mul[key]);
 	}
-	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${where.sql}`;
+	if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("buildUpdate: expectedVersion requires versionColumn");
+	let whereSql = where.sql;
+	const whereParams = [];
+	if (versionColumn !== void 0) {
+		const vcol = dialect.quoteIdentifier(versionColumn);
+		setClauses.push(`${vcol} = ${vcol} + 1`);
+		if (expectedVersion !== void 0) {
+			whereSql += ` AND ${vcol} = ?`;
+			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,
-		params: [...params, ...where.params]
+		params: [
+			...params,
+			...where.params,
+			...whereParams
+		]
 	});
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -42,7 +42,7 @@
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.6",
-    "@atscript/db": "^0.1.83"
+    "@atscript/db": "^0.1.85"
   },
   "scripts": {
     "build": "vp pack",