@vibeorm/sql 5.1.0 → 5.3.0

package/dist/ast.d.ts

@@ -45,6 +45,8 @@ export type ColRef = {
      * storage and read-back stay the exact text.
      */
     readonly castReal?: boolean;
+    /** Native enum order key through a scalar subquery: MySQL reads its member index, other dialects keep the column. */
+    readonly enumOrdinal?: true;
     /**
      * Order/distinct/compare cast, postgres `json` columns only (`Json @db.Json`,
      * release-3.0 D3): `json` has no ordering or equality operator, so ORDER BY,
@@ -93,6 +95,8 @@ export type AggRef = {
 } | {
     readonly fn: AggFn;
     readonly column: ColRef;
+    /** Native enum MIN/MAX: projections and HAVING return the database label; order keys keep its ordinal. */
+    readonly enumOrder?: "value" | "ordinal";
 };
 /**
  * One aggregate projection: `FN("col") AS "alias"`. The alias is part of the
@@ -463,18 +467,27 @@ export type OrderByAggregate = {
 };
 /**
  * ORDER BY a correlated scalar subquery — relation orderBy
- * (`orderBy: { posts: { _count: "desc" } }` → `(SELECT COUNT(*) …)` /
+ * (`orderBy: { posts: { _count: "desc" } }` → `(SELECT COUNT(*) …)`,
+ * `orderBy: { posts: { _max: { createdAt: "desc" } } }` → `(SELECT MAX(…) …)`,
  * `orderBy: { author: { email: "asc" } }` → `(SELECT "email" …)`).
  * Portable: all three dialects order by scalar subqueries. The subquery
  * correlates to the outer scope through table-qualified `cmpCol` predicates,
  * exactly like `exists`; its parameters merge into the statement's single
- * sequence in render order. NULLS placement is deliberately unsupported here
- * (emulating it would render the subquery twice and duplicate its params) —
- * missing relations sort at each engine's native NULL position.
+ * sequence in render order.
+ *
+ * `nulls` places the NULL a missing to-one row or a parent without related
+ * rows (under MIN/MAX/AVG/SUM) sorts as. Without it, NULL sorts at the
+ * engine's native position. Postgres and sqlite render `NULLS FIRST|LAST`;
+ * mysql renders the bare term when its native placement already matches, and
+ * otherwise a leading `(<subquery>) IS NULL` term — the subquery then renders
+ * twice and its parameters bind twice, in text order.
  */
 export type OrderBySubquery = {
     readonly select: SelectStatement;
+    /** A count behind a missing to-one row is zero, not NULL. */
+    readonly coalesce?: 0;
     readonly direction: "asc" | "desc";
+    readonly nulls?: "first" | "last";
 };
 export type OrderTerm = OrderByColumn | OrderByAggregate | OrderBySubquery;
 /**
@@ -519,6 +532,17 @@ export type LateralJoin = {
     /** The correlated child select — may reference outer columns via table-qualified refs. */
     readonly select: SelectStatement;
 };
+/**
+ * One scalar subquery in a projection. The builder guarantees a single column
+ * and at most one row. Hidden sort values stay inside derived tables rather
+ * than becoming result fields. `coalesce` preserves a count across a missing
+ * to-one hop.
+ */
+export type ScalarSubquery = {
+    readonly alias: string;
+    readonly select: SelectStatement;
+    readonly coalesce?: 0;
+};
 /**
  * One correlated scalar `COUNT(*)` projected into a select list:
  * `(SELECT COUNT(*) FROM … WHERE <correlation>) AS "alias"` — the relation
@@ -765,6 +789,8 @@ export type SelectStatement = {
     readonly aggregates?: readonly AggSelect[];
     /** Correlated `COUNT(*)` subqueries, rendered after `aggregates` — see {@link CountSubquery}. */
     readonly countSubqueries?: readonly CountSubquery[];
+    /** Scalar values projected after count subqueries and before a row number. */
+    readonly scalarSubqueries?: readonly ScalarSubquery[];
     /**
      * `SELECT DISTINCT ON (cols)` — postgres only (`capabilities.distinctOn`;
      * other dialects refuse at render time and the runtime emulates client-side
@@ -1146,6 +1172,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;
 /**
@@ -1264,6 +1296,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?: {
@@ -1296,12 +1329,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 = {
@@ -1341,7 +1377,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/dialect.d.ts

@@ -446,6 +446,16 @@ export type SqlDialect = {
     quoteStringLiteral(params: {
         value: string;
     }): string;
+    /** Keep a native enum's ordering through a scalar subquery that may lose its physical enum type. */
+    renderEnumOrdinal(params: {
+        column: string;
+    }): string;
+    /** Render native enum MIN/MAX in database declaration order, returning its label or an order key. */
+    renderEnumMinMax(params: {
+        fn: "min" | "max";
+        column: string;
+        result: "value" | "ordinal";
+    }): string;
     /** Positional placeholder for the 1-based parameter index ($n or ?). */
     placeholder(params: {
         index: number;

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, 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

@@ -2402,6 +2402,12 @@ var sqliteDialect = {
   quoteStringLiteral({ value }) {
     return `'${value.replaceAll("'", "''")}'`;
   },
+  renderEnumOrdinal({ column }) {
+    return column;
+  },
+  renderEnumMinMax({ fn, column }) {
+    return `${fn === "min" ? "MIN" : "MAX"}(${column})`;
+  },
   placeholder() {
     return "?";
   },
@@ -2984,6 +2990,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) {
@@ -3075,6 +3103,12 @@ var postgresDialect = {
   quoteStringLiteral({ value }) {
     return `'${value.replaceAll("'", "''")}'`;
   },
+  renderEnumOrdinal({ column }) {
+    return column;
+  },
+  renderEnumMinMax({ fn, column }) {
+    return `${fn === "min" ? "MIN" : "MAX"}(${column})`;
+  },
   placeholder({ index }) {
     return `$${index}`;
   },
@@ -3148,6 +3182,15 @@ var mysqlDialect = {
   quoteStringLiteral({ value }) {
     return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`;
   },
+  renderEnumOrdinal({ column }) {
+    return `${column} + 0`;
+  },
+  renderEnumMinMax({ fn, column, result }) {
+    const aggregate = fn === "min" ? "MIN" : "MAX";
+    if (result === "ordinal")
+      return `${aggregate}(${column} + 0)`;
+    return `SUBSTRING(${aggregate}(CONCAT(LPAD(${column} + 0, 5, '0'), ${column})), 6)`;
+  },
   placeholder() {
     return "?";
   },
@@ -4090,6 +4133,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":
@@ -4129,6 +4174,8 @@ function quoteCol(dialect, column) {
   const ref = column.table === undefined ? name : `${dialect.quoteIdent({ name: column.table })}.${name}`;
   if (column.truncate !== undefined)
     return renderDateTruncation({ dialect, reference: ref, truncation: column.truncate });
+  if (column.enumOrdinal === true)
+    return dialect.renderEnumOrdinal({ column: ref });
   if (column.castReal === true) {
     if (dialect.name !== "sqlite") {
       throw internalError4({ message: "ColRef.castReal is a sqlite Decimal construct" });
@@ -4229,7 +4276,11 @@ var AGG_FN_SQL = {
 function renderAggRef(dialect, agg) {
   if (agg.fn === "countAll")
     return "COUNT(*)";
-  return `${AGG_FN_SQL[agg.fn]}(${quoteCol(dialect, agg.column)})`;
+  const column = quoteCol(dialect, agg.column);
+  if ((agg.fn === "min" || agg.fn === "max") && agg.enumOrder !== undefined) {
+    return dialect.renderEnumMinMax({ fn: agg.fn, column, result: agg.enumOrder });
+  }
+  return `${AGG_FN_SQL[agg.fn]}(${column})`;
 }
 function assertScalarArrays(dialect, feature) {
   if (dialect.capabilities.scalarArrays)
@@ -4770,23 +4821,20 @@ function renderOrderTerm(params) {
   if ("agg" in term) {
     return `${renderAggRef(dialect, term.agg)} ${term.direction === "asc" ? "ASC" : "DESC"}`;
   }
-  if ("select" in term) {
-    const sub = renderSelect({ dialect, statement: term.select, collector });
-    return `(${sub.text}) ${term.direction === "asc" ? "ASC" : "DESC"}`;
-  }
-  const column = quoteCol(dialect, term.column);
+  const expression = "select" in term ? () => renderScalarSubquery({ dialect, subquery: term, collector }) : () => quoteCol(dialect, term.column);
   const direction = term.direction === "asc" ? "ASC" : "DESC";
   if (term.nulls === undefined) {
-    return `${column} ${direction}`;
+    return `${expression()} ${direction}`;
   }
   if (dialect.orderByNullsMode === "native") {
-    return `${column} ${direction} NULLS ${term.nulls === "first" ? "FIRST" : "LAST"}`;
+    return `${expression()} ${direction} NULLS ${term.nulls === "first" ? "FIRST" : "LAST"}`;
   }
   if (term.nulls === "first" === (term.direction === "asc")) {
-    return `${column} ${direction}`;
+    return `${expression()} ${direction}`;
   }
-  const nullsTerm = term.nulls === "first" ? `${column} IS NULL DESC` : `${column} IS NULL`;
-  return `${nullsTerm}, ${column} ${direction}`;
+  const tested = expression();
+  const nullsTerm = term.nulls === "first" ? `${tested} IS NULL DESC` : `${tested} IS NULL`;
+  return `${nullsTerm}, ${expression()} ${direction}`;
 }
 function renderSelectExpr(params) {
   const { dialect, expr } = params;
@@ -4837,7 +4885,7 @@ function renderLateralJoin(params) {
   const json = lateralJsonOf({ dialect });
   let aggOrder = "";
   if (json.order === "inAggregate" && join.agg === "jsonArray" && join.select.orderBy !== undefined && join.select.orderBy.length > 0) {
-    const projected = new Set(join.select.columns.filter((column) => column.transform === undefined && column.castReal !== true).map((column) => column.name));
+    const projected = new Set(join.select.columns.filter((column) => column.transform === undefined && column.castReal !== true).map((column) => column.name).concat((join.select.scalarSubqueries ?? []).map((subquery) => subquery.alias)));
     const terms = join.select.orderBy;
     const columnTerms = terms.filter((term) => ("column" in term));
     if (columnTerms.length === terms.length && columnTerms.every((term) => projected.has(term.column.name))) {
@@ -4863,12 +4911,17 @@ function renderLateralJoin(params) {
 function renderCountSubquery(params) {
   const { dialect, subquery, collector } = params;
   const select = subquery.select;
-  if (select.columns.length !== 0 || select.selectExpr?.kind !== "countAll" || (select.aggregates?.length ?? 0) > 0 || select.rowNumber !== undefined || select.groupBy !== undefined || select.having !== undefined || select.limit !== undefined || select.offset !== undefined || select.distinctOn !== undefined || select.distinct !== undefined || select.rowLock !== undefined || select.countSubqueries !== undefined) {
+  if (select.columns.length !== 0 || select.selectExpr?.kind !== "countAll" || (select.aggregates?.length ?? 0) > 0 || select.rowNumber !== undefined || select.groupBy !== undefined || select.having !== undefined || select.limit !== undefined || select.offset !== undefined || select.distinctOn !== undefined || select.distinct !== undefined || select.rowLock !== undefined || select.countSubqueries !== undefined || select.scalarSubqueries !== undefined) {
     throw internalError4({ message: "count subquery must be one ungrouped COUNT(*)" });
   }
   const inner = renderSelect({ dialect, statement: select, collector });
   return `(${inner.text}) AS ${dialect.quoteIdent({ name: subquery.alias })}`;
 }
+function renderScalarSubquery(params) {
+  const { dialect, subquery, collector } = params;
+  const value = `(${renderSelect({ dialect, statement: subquery.select, collector }).text})`;
+  return subquery.coalesce === 0 ? `COALESCE(${value}, 0)` : value;
+}
 function applyReturning(params) {
   const { dialect, requested } = params;
   if (requested === undefined || requested.length === 0) {
@@ -4977,6 +5030,11 @@ function renderSelect(params) {
       columnList.push(renderCountSubquery({ dialect, subquery, collector }));
     }
   }
+  if (statement.scalarSubqueries !== undefined) {
+    for (const subquery of statement.scalarSubqueries) {
+      columnList.push(`${renderScalarSubquery({ dialect, subquery, collector })} AS ${dialect.quoteIdent({ name: subquery.alias })}`);
+    }
+  }
   if (statement.rowNumber !== undefined) {
     const rowNumber = statement.rowNumber;
     if (rowNumber.partitionBy.length === 0 && rowNumber.orderBy.length === 0) {
@@ -5393,6 +5451,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" });
   }
@@ -5491,7 +5552,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 })}`;
@@ -6275,6 +6339,7 @@ export {
   recordSqlBindingCheck,
   registerSqlHandleCheck,
   renderAdvisoryLock,
+  renderAdvisoryLocks,
   renderCheckProbe,
   renderColumnStateQuery,
   renderConstraintOwnedIndexDrop,
@@ -6380,4 +6445,4 @@ export {
   toPgArrayLiteral
 };
 
-//# debugId=DB7441716F57EC8864756E2164756E21
+//# debugId=A6FF0AC9CFF5903864756E2164756E21