@constructive-io/query-builder 3.10.6 → 3.11.0

package/README.md

@@ -31,7 +31,7 @@ npm install @constructive-io/query-builder
 - Fluent, chainable API
 - SDK-style JSON filters for `WHERE`/`HAVING` (`{ status: { equalTo: 'active' } }`), matching the generated ORM/SDK filter grammar
 - Composable expressions (`col()`, `fn()`, `add()`, `eq()`, ...) usable in SELECT, WHERE, SET, ON CONFLICT, and RETURNING
-- Full support for: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `JOIN`, `CTE`, `ON CONFLICT`, `RETURNING`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`/`OFFSET`, `DISTINCT`, function/procedure calls
+- Full support for: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `JOIN`, `CTE`, `ON CONFLICT`, `RETURNING`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`/`OFFSET`, `FOR UPDATE`/`FOR SHARE`, `DISTINCT`, function/procedure calls
 
 ## Usage
 
@@ -509,6 +509,25 @@ new QueryBuilder()
   .limit(10)
   .offset(20)
   .build();
+
+// FOR UPDATE — lock the row a read-then-write is about to change
+new QueryBuilder()
+  .schema('app_public')
+  .table('runs')
+  .select(['id', 'status'])
+  .where({ id: { equalTo: runId } })
+  .lock()
+  .build();
+
+// FOR UPDATE SKIP LOCKED — a queue claim moves on rather than waiting
+new QueryBuilder()
+  .table('jobs')
+  .select(['id'])
+  .where({ status: { equalTo: 'pending' } })
+  .orderBy('created_at', 'ASC')
+  .limit(1)
+  .lock('update', { skipLocked: true })
+  .build();
 ```
 
 ## API
@@ -535,6 +554,7 @@ new QueryBuilder()
 | `.having(...predicates)` | HAVING clause (JSON filters and/or expressions) |
 | `.limit(n)` | LIMIT clause |
 | `.offset(n)` | OFFSET clause |
+| `.lock(strength?, opts?)` | Row lock: `'update'` (default), `'noKeyUpdate'`, `'share'`, `'keyShare'`; `opts: { skipLocked?, noWait? }` |
 | `.distinct()` | SELECT DISTINCT |
 | `.returning(columns)` | RETURNING clause (column names or `{ expr, as }` items) |
 | `.onConflict(opts)` | ON CONFLICT (DO NOTHING or DO UPDATE) |

package/esm/query-builder.js

@@ -1,6 +1,12 @@
 import { ast, nodes } from 'pg-ast';
 import { deparseSync } from 'pgsql-deparser';
 import { keywordExprNode } from './keyword-exprs';
+const LOCK_STRENGTHS = {
+    update: 'LCS_FORUPDATE',
+    noKeyUpdate: 'LCS_FORNOKEYUPDATE',
+    share: 'LCS_FORSHARE',
+    keyShare: 'LCS_FORKEYSHARE',
+};
 // ---------------------------------------------------------------------------
 // AST helpers (thin wrappers for readability)
 // ---------------------------------------------------------------------------
@@ -268,6 +274,7 @@ export class QueryBuilder {
     _ctes = [];
     _onConflict;
     _funcCall;
+    _lock;
     // -------------------------------------------------------------------------
     // Schema / Table
     // -------------------------------------------------------------------------
@@ -392,6 +399,18 @@ export class QueryBuilder {
         this._offsetValue = n;
         return this;
     }
+    // Row-level lock on the rows this SELECT reads:
+    //   .lock()                              -> FOR UPDATE
+    //   .lock('share')                       -> FOR SHARE
+    //   .lock('update', { skipLocked: true }) -> FOR UPDATE SKIP LOCKED
+    //   .lock('update', { noWait: true })     -> FOR UPDATE NOWAIT
+    lock(strength = 'update', opts) {
+        if (opts?.skipLocked && opts?.noWait) {
+            throw new Error('A lock either skips locked rows or refuses to wait for them, not both.');
+        }
+        this._lock = { strength, opts };
+        return this;
+    }
     // -------------------------------------------------------------------------
     // RETURNING
     // -------------------------------------------------------------------------
@@ -456,6 +475,7 @@ export class QueryBuilder {
             }
             : undefined;
         c._funcCall = this._funcCall ? { ...this._funcCall } : undefined;
+        c._lock = this._lock ? { ...this._lock, opts: this._lock.opts ? { ...this._lock.opts } : undefined } : undefined;
         c._fromFunction = this._fromFunction ? { ...this._fromFunction } : undefined;
         return c;
     }
@@ -769,6 +789,7 @@ export class QueryBuilder {
             : undefined;
         return nodes.selectStmt({
             distinctClause: this._distinct ? [] : undefined,
+            lockingClause: this._buildLockingClause(),
             targetList: targetList,
             fromClause: this._buildFromClause(),
             whereClause: whereClause,
@@ -781,6 +802,21 @@ export class QueryBuilder {
             op: 'SETOP_NONE',
         });
     }
+    _buildLockingClause() {
+        if (!this._lock)
+            return undefined;
+        const { strength, opts } = this._lock;
+        return [
+            nodes.lockingClause({
+                strength: LOCK_STRENGTHS[strength],
+                waitPolicy: (opts?.skipLocked
+                    ? 'LockWaitSkip'
+                    : opts?.noWait
+                        ? 'LockWaitError'
+                        : undefined),
+            }),
+        ];
+    }
     _buildSelect() {
         this._resetParams();
         const withClause = this._buildWithClause();

package/index.d.ts

@@ -1,2 +1,2 @@
-export type { Expr, FieldFilter, Filter, FnArg, FnArgs, Operand, ParamAllocator, QueryOutput, SelectExpr, SelectItem, SqlValue, } from './query-builder';
+export type { Expr, FieldFilter, Filter, FnArg, FnArgs, LockOptions, LockStrength, Operand, ParamAllocator, QueryOutput, SelectExpr, SelectItem, SqlValue, } from './query-builder';
 export { add, and, cast, col, div, eq, fn, gt, gte, isNotNull, isNull, lit, lt, lte, mul, neq, not, or, param, QueryBuilder, sub } from './query-builder';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/query-builder",
-  "version": "3.10.6",
+  "version": "3.11.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Query Builder",
   "main": "index.js",
@@ -45,5 +45,5 @@
     "pgsql-deparser": "^18.3.6",
     "query-spec": "^0.11.0"
   },
-  "gitHead": "ce544846eafd96280fac2607f873960392ae2c89"
+  "gitHead": "6880388c8cd5fb21745decff8bd23c3a430338b3"
 }

package/query-builder.d.ts

@@ -28,6 +28,11 @@ export type Filter = {
 type SortDir = 'ASC' | 'DESC';
 type NullsOrder = 'FIRST' | 'LAST';
 type ConflictAction = 'nothing' | 'update';
+export type LockStrength = 'update' | 'noKeyUpdate' | 'share' | 'keyShare';
+export interface LockOptions {
+    skipLocked?: boolean;
+    noWait?: boolean;
+}
 export interface SelectExpr {
     expr: Expr;
     as?: string;
@@ -91,6 +96,7 @@ export declare class QueryBuilder {
     private _ctes;
     private _onConflict;
     private _funcCall;
+    private _lock;
     schema(name: string): this;
     table(name: string, alias?: string): this;
     select(columns?: SelectItem[]): this;
@@ -119,6 +125,7 @@ export declare class QueryBuilder {
     orderBy(column: string | Expr, direction?: SortDir, nulls?: NullsOrder): this;
     limit(n: number): this;
     offset(n: number): this;
+    lock(strength?: LockStrength, opts?: LockOptions): this;
     returning(columns?: SelectItem[]): this;
     with(name: string, query: QueryBuilder, opts?: {
         columns?: string[];
@@ -158,6 +165,7 @@ export declare class QueryBuilder {
     private _buildFromClause;
     private _rangeFunctionNode;
     private _buildSelectInternal;
+    private _buildLockingClause;
     private _buildSelect;
     private _buildInsert;
     private _buildOnConflictClause;

package/query-builder.js

@@ -14,6 +14,12 @@ exports.not = not;
 const pg_ast_1 = require("pg-ast");
 const pgsql_deparser_1 = require("pgsql-deparser");
 const keyword_exprs_1 = require("./keyword-exprs");
+const LOCK_STRENGTHS = {
+    update: 'LCS_FORUPDATE',
+    noKeyUpdate: 'LCS_FORNOKEYUPDATE',
+    share: 'LCS_FORSHARE',
+    keyShare: 'LCS_FORKEYSHARE',
+};
 // ---------------------------------------------------------------------------
 // AST helpers (thin wrappers for readability)
 // ---------------------------------------------------------------------------
@@ -281,6 +287,7 @@ class QueryBuilder {
     _ctes = [];
     _onConflict;
     _funcCall;
+    _lock;
     // -------------------------------------------------------------------------
     // Schema / Table
     // -------------------------------------------------------------------------
@@ -405,6 +412,18 @@ class QueryBuilder {
         this._offsetValue = n;
         return this;
     }
+    // Row-level lock on the rows this SELECT reads:
+    //   .lock()                              -> FOR UPDATE
+    //   .lock('share')                       -> FOR SHARE
+    //   .lock('update', { skipLocked: true }) -> FOR UPDATE SKIP LOCKED
+    //   .lock('update', { noWait: true })     -> FOR UPDATE NOWAIT
+    lock(strength = 'update', opts) {
+        if (opts?.skipLocked && opts?.noWait) {
+            throw new Error('A lock either skips locked rows or refuses to wait for them, not both.');
+        }
+        this._lock = { strength, opts };
+        return this;
+    }
     // -------------------------------------------------------------------------
     // RETURNING
     // -------------------------------------------------------------------------
@@ -469,6 +488,7 @@ class QueryBuilder {
             }
             : undefined;
         c._funcCall = this._funcCall ? { ...this._funcCall } : undefined;
+        c._lock = this._lock ? { ...this._lock, opts: this._lock.opts ? { ...this._lock.opts } : undefined } : undefined;
         c._fromFunction = this._fromFunction ? { ...this._fromFunction } : undefined;
         return c;
     }
@@ -782,6 +802,7 @@ class QueryBuilder {
             : undefined;
         return pg_ast_1.nodes.selectStmt({
             distinctClause: this._distinct ? [] : undefined,
+            lockingClause: this._buildLockingClause(),
             targetList: targetList,
             fromClause: this._buildFromClause(),
             whereClause: whereClause,
@@ -794,6 +815,21 @@ class QueryBuilder {
             op: 'SETOP_NONE',
         });
     }
+    _buildLockingClause() {
+        if (!this._lock)
+            return undefined;
+        const { strength, opts } = this._lock;
+        return [
+            pg_ast_1.nodes.lockingClause({
+                strength: LOCK_STRENGTHS[strength],
+                waitPolicy: (opts?.skipLocked
+                    ? 'LockWaitSkip'
+                    : opts?.noWait
+                        ? 'LockWaitError'
+                        : undefined),
+            }),
+        ];
+    }
     _buildSelect() {
         this._resetParams();
         const withClause = this._buildWithClause();