@vibeorm/sql 5.2.0 → 5.4.0

package/dist/ast.d.ts

@@ -868,10 +868,21 @@ export type SelectStatement = {
  * The lock a locking read takes: one strength, one wait policy. Both members
  * are REQUIRED here — defaulting happens once, in the query builder, so the
  * rendered SQL is a function of the AST alone.
+ *
+ * `of` narrows the lock to named FROM items (`FOR UPDATE OF "Parent"`). The
+ * join relation strategy needs it: its statement also reads child rows through
+ * `LEFT JOIN LATERAL` subqueries, and an unnarrowed clause is refused by
+ * postgres ("FOR UPDATE is not allowed with aggregate functions", from the
+ * children's `json_agg`). With `of` naming the statement's own table only the
+ * parent rows are locked. Each name must be the statement's table alias, or its
+ * unqualified table name when it has no alias — the only FROM item the AST
+ * names; the renderer refuses anything else. Dialects without a locking-read
+ * clause render nothing, as for a lock without `of`.
  */
 export type RowLock = {
     readonly strength: RowLockStrength;
     readonly wait: RowLockWaitPolicy;
+    readonly of?: readonly string[];
 };
 /**
  * Sentinel VALUES cell: render the `DEFAULT` keyword instead of a placeholder
@@ -1172,6 +1183,12 @@ export type AdvisoryLockStatement = {
     readonly wait: "wait" | "nowait";
     readonly key: AdvisoryLockKey;
 };
+/** An ordered set of transaction-scoped bigint advisory locks. */
+export type AdvisoryLocksStatement = {
+    readonly kind: "advisoryLocks";
+    readonly keys: readonly bigint[];
+    readonly mode: AdvisoryLockMode;
+};
 /** The column an advisory try-lock projects its verdict into. */
 export declare const ADVISORY_LOCK_RESULT_COLUMN: string;
 /**
@@ -1290,6 +1307,7 @@ export type ChainStep = {
  * verdict-row outcome (the upsert fold always rolls it back).
  */
 export type ChainResult = {
+    /** Both lists may be empty for a tally-only result: one count row, no model values. */
     readonly rowsFrom: readonly string[];
     readonly columns: readonly string[];
     readonly verdict?: {
@@ -1322,12 +1340,15 @@ export type ChainResult = {
  * `minRows` (EPIC W) makes the veto count-sensitive: the statement fails when
  * `step` returned FEWER rows than that (a multi-row INSERT a trigger shortened).
  * Omitted or 1 = "no row". A positive safe integer, rendered as SQL text.
+ * `exactRows` instead requires equality, including zero. It is a nonnegative
+ * safe integer and cannot combine with `minRows`.
  */
 export type ChainVeto = {
     readonly step: string;
     readonly token: string;
     readonly nonce: string;
     readonly minRows?: number;
+    readonly exactRows?: number;
 };
 /** Count the RETURNING rows of `steps` into the result column `alias`. */
 export type ChainTally = {
@@ -1367,7 +1388,7 @@ export type ChainStatement = {
     readonly steps: readonly ChainStep[];
     readonly result: ChainResult;
 };
-export type SqlStatement = SelectStatement | InsertStatement | UpdateStatement | DeleteStatement | RlsEnableStatement | RlsForceStatement | RlsDisableStatement | RlsNoForceStatement | RlsDropPolicyStatement | RlsPolicyStatement | RlsContextStatement | RlsRoleStatement | AdvisoryLockStatement | ChainStatement;
+export type SqlStatement = SelectStatement | InsertStatement | UpdateStatement | DeleteStatement | RlsEnableStatement | RlsForceStatement | RlsDisableStatement | RlsNoForceStatement | RlsDropPolicyStatement | RlsPolicyStatement | RlsContextStatement | RlsRoleStatement | AdvisoryLockStatement | AdvisoryLocksStatement | ChainStatement;
 /** Readiness statements remain distinct from application queries. */
 export type RlsReadinessStatement = {
     readonly kind: "rlsReadiness";

package/dist/index.d.ts

@@ -40,10 +40,10 @@ export type { ResultDecoder, ResultReadDecoder, ResultParameterEncoder, ResultSc
  * lives in this package; see the root sql-catalog.md for the reviewable surface.
  */
 export { compileExclusion, renderExclusionSetup, renderExclusionDdl, renderExclusionCatalog, renderExclusionProbe } from "./exclusion.ts";
-export type { AdvisoryLockKey, AdvisoryLockStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, TableRef, UpdateStatement, } from "./ast.ts";
+export type { AdvisoryLockKey, AdvisoryLockStatement, AdvisoryLocksStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, TableRef, UpdateStatement, } from "./ast.ts";
 export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, SQL_DEFAULT_CELL, SQL_KEEP_CELL, chainVetoToken, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isSqlKeepCell, isStepColumnRef, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
 export type { AdvisoryLockFunctions, AdvisoryLockModeFunctions, RowLockSyntax, EmptyInsertSyntax, SqlDialect, } from "./dialect.ts";
-export { ADVISORY_KEY_BOUNDS, describeRowLock, renderAdvisoryLock, renderRowLockClause } from "./locks.ts";
+export { ADVISORY_KEY_BOUNDS, describeRowLock, renderAdvisoryLock, renderAdvisoryLocks, renderRowLockClause } from "./locks.ts";
 export { JSON_TRANSPORT, projectionOutputName } from "./json-transport.ts";
 export { postgresDialect } from "./dialects/postgres.ts";
 export { sqliteDialect } from "./dialects/sqlite.ts";

package/dist/index.js

@@ -2960,6 +2960,12 @@ function renderRowLockClause(params) {
       hint: `${dialect.name} can express: ${Object.keys(syntax.wait).join(", ")}`
     });
   }
+  if (lock.of !== undefined) {
+    if (lock.of.length === 0)
+      throw internalError({ message: "a row lock's `of` list cannot be empty" });
+    const tables = lock.of.map((name) => dialect.quoteIdent({ name })).join(", ");
+    return `${strengthText} OF ${tables}${waitText}`;
+  }
   return `${strengthText}${waitText}`;
 }
 var ADVISORY_KEY_BOUNDS = Object.freeze({
@@ -2990,6 +2996,28 @@ function renderAdvisoryLock(params) {
     returning: "none"
   };
 }
+function renderAdvisoryLocks(params) {
+  const { dialect, keys, mode } = params;
+  const functions = dialect.advisoryLockFunctions;
+  if (functions === null)
+    throw unsupportedCapability15({ dialect: dialect.name, feature: "advisory locks" });
+  if (mode !== "exclusive" && mode !== "shared")
+    throw internalError({ message: "advisory lock mode must be exclusive or shared" });
+  if (keys.some((key) => typeof key !== "bigint" || key < ADVISORY_KEY_BOUNDS.single.min || key > ADVISORY_KEY_BOUNDS.single.max)) {
+    throw internalError({ message: "advisory lock keys must be signed 64-bit integers" });
+  }
+  const collector = new ParamCollector(dialect);
+  const binding = collector.add(JSON.stringify(keys.map((key) => key.toString())));
+  const fn = (mode === "exclusive" ? functions.exclusive : functions.shared).wait;
+  const table = dialect.quoteIdent({ name: "__vibe_locks" });
+  const key = dialect.quoteIdent({ name: "key" });
+  const order = dialect.quoteIdent({ name: "ordinal" });
+  return {
+    text: `SELECT ${fn}(${table}.${key}${functions.keyCast.single}) FROM jsonb_array_elements_text(${binding}::text::jsonb) WITH ORDINALITY AS ${table}(${key}, ${order}) ORDER BY ${table}.${order}`,
+    values: collector.values,
+    returning: "none"
+  };
+}
 function assertInt32(params) {
   const { value, part } = params;
   if (!Number.isInteger(value) || value < ADVISORY_KEY_BOUNDS.pair.min || value > ADVISORY_KEY_BOUNDS.pair.max) {
@@ -4111,6 +4139,8 @@ function renderStatement(params) {
     }
     case "select":
       return renderSelect({ dialect, statement, collector });
+    case "advisoryLocks":
+      return renderAdvisoryLocks({ dialect, keys: statement.keys, mode: statement.mode });
     case "advisoryLock":
       return renderAdvisoryLock({ dialect, statement, collector });
     case "insert":
@@ -5112,6 +5142,13 @@ function renderSelect(params) {
     text += ` OFFSET ${statement.offset}`;
   }
   if (statement.rowLock !== undefined) {
+    const target = statement.table.alias ?? statement.table.name;
+    if (statement.rowLock.of !== undefined && statement.rowLock.of.some((name) => name !== target)) {
+      throw internalError4({ message: `a row lock's \`of\` list may name only the statement's own table "${target}"` });
+    }
+    if (statement.rowLock.of !== undefined && (statement.fromSelect !== undefined || statement.keyPage !== undefined)) {
+      throw internalError4({ message: "a row lock's `of` list cannot name a derived table" });
+    }
     const clause = renderRowLockClause({ dialect, lock: statement.rowLock });
     if (clause !== null)
       text += ` ${clause}`;
@@ -5427,6 +5464,9 @@ function renderChain(params) {
     defined.add(step.name);
   }
   const result = statement.result;
+  if (result.rowsFrom.length === 0 && result.columns.length === 0 && result.tally !== undefined && result.verdict === undefined) {
+    return { text: `WITH ${steps.join(", ")} SELECT ${renderTallyColumn({ dialect, result, defined, collector })}`, values: collector.values, returning: "none" };
+  }
   if (result.rowsFrom.length === 0 || result.columns.length === 0) {
     throw internalError4({ message: "a chain result needs at least one source step and one column" });
   }
@@ -5525,7 +5565,10 @@ function renderTallyColumn(params) {
     const minRows = veto.minRows ?? 1;
     if (!Number.isSafeInteger(minRows) || minRows < 1)
       throw internalError4({ message: `chain veto "${veto.token}" needs a positive integer minRows` });
-    const when = minRows === 1 ? `WHEN NOT EXISTS (SELECT 1 FROM ${step(veto.step)})` : `WHEN ${count(veto.step)} < ${minRows}`;
+    if (veto.exactRows !== undefined && (!Number.isSafeInteger(veto.exactRows) || veto.exactRows < 0 || veto.minRows !== undefined)) {
+      throw internalError4({ message: `chain veto "${veto.token}" needs a nonnegative safe integer exactRows without minRows` });
+    }
+    const when = veto.exactRows !== undefined ? `WHEN ${count(veto.step)} <> ${veto.exactRows}` : minRows === 1 ? `WHEN NOT EXISTS (SELECT 1 FROM ${step(veto.step)})` : `WHEN ${count(veto.step)} < ${minRows}`;
     return `${when} THEN CAST('${CHAIN_VETO_PREFIX}${veto.token}:' || ${collector.add(veto.nonce)} || ':' || ${count(veto.step)} AS integer)`;
   });
   return `CASE ${arms.join(" ")} ELSE ${sum} END AS ${dialect.quoteIdent({ name: tally.alias })}`;
@@ -6309,6 +6352,7 @@ export {
   recordSqlBindingCheck,
   registerSqlHandleCheck,
   renderAdvisoryLock,
+  renderAdvisoryLocks,
   renderCheckProbe,
   renderColumnStateQuery,
   renderConstraintOwnedIndexDrop,
@@ -6414,4 +6458,4 @@ export {
   toPgArrayLiteral
 };
 
-//# debugId=7A09C0BE2E07A46664756E2164756E21
+//# debugId=11C29D1889ACA76B64756E2164756E21