@vibeorm/sql 5.0.1 → 5.2.0

package/dist/ast.d.ts

@@ -10,7 +10,7 @@ import type { RlsReadinessQuery } from "./dialects/postgres-rls-readiness.ts";
  * grows with the runtime in P2/P3. Every shape added here needs a catalog case
  * (tests/catalog/cases.ts) in the same change.
  */
-import type { AdvisoryLockMode, RlsContextIR, RowLockStrength, RowLockWaitPolicy, ScalarType, SchemaIR, SqlFragmentSpec } from "@vibeorm/schema";
+import type { AdvisoryLockMode, DateTruncationStorage, DateTruncationUnit, RlsContextIR, RowLockStrength, RowLockWaitPolicy, ScalarType, SchemaIR, SqlFragmentSpec } from "@vibeorm/schema";
 /** A column reference, optionally table-qualified. */
 export type ColRef = {
     readonly table?: string;
@@ -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,
@@ -53,6 +55,17 @@ export type ColRef = {
      * column. Never set on projections, so read-back keeps the stored text.
      */
     readonly castJsonb?: "jsonb" | "jsonb[]";
+    /**
+     * Calendar truncation of a timestamp column, for a `groupBy` date key. The
+     * reference renders as the start of its period in a named time zone
+     * (`date_trunc('day', "col", 'Europe/Oslo')`; see `renderDateTruncation`),
+     * in the column's own SQL type. Set on the projection, GROUP BY and ORDER BY
+     * refs of one key, which then repeat the identical expression text
+     * (PostgreSQL matches GROUP BY expressions by structure); a projection keeps
+     * `alias ?? name` as its output name. Never set on filter refs. Dialects
+     * without the `dateTruncation` capability refuse it when rendering.
+     */
+    readonly truncate?: DateTruncation;
     /**
      * Projection alias: renders `ref AS "alias"`. PROJECTION-ONLY — filter,
      * order and correlation refs never set it (the renderer ignores it outside
@@ -61,6 +74,13 @@ export type ColRef = {
      */
     readonly alias?: string;
 };
+/** A {@link ColRef.truncate} request: the calendar unit, the zone that defines the calendar, and the column's storage form. */
+export type DateTruncation = {
+    readonly unit: DateTruncationUnit;
+    /** A time-zone name (`"Europe/Oslo"`, `"UTC"`), rendered as a string literal after a strict character check. */
+    readonly timeZone: string;
+    readonly storage: DateTruncationStorage;
+};
 export type TableRef = {
     readonly name: string;
     /** Explicit fixed PostgreSQL placement; absence preserves existing SQL. */
@@ -75,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
@@ -445,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;
 /**
@@ -501,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
@@ -747,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
@@ -969,6 +1013,16 @@ export type OnConflictUpdate = {
      */
     readonly conflictWhere?: string;
     readonly update: Readonly<Record<string, unknown>>;
+    /**
+     * Guard on the update arm, BOUND parameters: `ON CONFLICT (…) DO UPDATE SET
+     * … WHERE <guard>` — the conflicting row is updated (and returned) only when
+     * the guard admits it; otherwise the statement writes and returns nothing.
+     * Postgres has both the target row and `excluded` in scope there, so every
+     * column ref must carry `table` (the target table's name), exactly as the
+     * SET self-references do. Needs the `conflictUpdateWhere` capability:
+     * mysql's ODKU has no WHERE and refuses it (`VIBE_UNSUPPORTED_CAPABILITY`).
+     */
+    readonly updateWhere?: SqlExpr;
     /**
      * MySQL only (`upsertForm: "onDuplicateKey"`): append
      * `` `col` = LAST_INSERT_ID(`col`) `` to the update list so the UPDATE arm

package/dist/date-truncation.d.ts

@@ -0,0 +1,27 @@
+import type { DateTruncation } from "./ast.ts";
+import type { SqlDialect } from "./dialect.ts";
+/** Is this value a time-zone name the renderer will spell as a literal? (See {@link TIME_ZONE_NAME}.) */
+export declare function isTimeZoneName(params: {
+    readonly value: unknown;
+}): params is {
+    readonly value: string;
+};
+/**
+ * The start of the period that holds `reference`'s value, in the column's own
+ * SQL type, so the field's codec decodes it unchanged:
+ *
+ * - `timestamptz` → `date_trunc('day', "col", 'Europe/Oslo')` — the 3-argument
+ *   form (PostgreSQL 12 or later) truncates in the named zone, never in the
+ *   session's `TimeZone`;
+ * - `timestamp` (zone-less, UTC wall-clock by contract) →
+ *   `(date_trunc('day', "col" AT TIME ZONE 'UTC', 'Europe/Oslo') AT TIME ZONE 'UTC')`.
+ *
+ * The unit and the zone are literals, so every site of one key (projection,
+ * GROUP BY, ORDER BY) repeats the identical text and binds no parameter.
+ */
+export declare function renderDateTruncation(params: {
+    readonly dialect: SqlDialect;
+    readonly reference: string;
+    readonly truncation: DateTruncation;
+}): string;
+//# sourceMappingURL=date-truncation.d.ts.map

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,7 +40,7 @@ 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, 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, 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";
@@ -53,6 +53,7 @@ export { tableDefinitionParts } from "./dialects/sqlite-table-definition.ts";
 export { keyListBindsUntypedRows, postgresBulkInsertArrayCastOf, postgresKeyListElementTypeOf } from "./key-list.ts";
 export { renderPredicate, renderSchemaExpression } from "./predicate.ts";
 export { renderLocalDateCheck } from "./local-date.ts";
+export { isTimeZoneName, renderDateTruncation } from "./date-truncation.ts";
 export { renderGeneratedColumnClause } from "./generated-columns.ts";
 export type { GeneratedColumnDeclaration, ExtractedGeneratedColumn } from "./generated-columns.ts";
 export { renderPostgresGeneratedColumnProbe, renderPostgresDropGeneratedExpression } from "./dialects/postgres-generated-columns.ts";