@vibeorm/sql 5.0.0 → 5.1.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;
@@ -53,6 +53,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 +72,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. */
@@ -969,6 +987,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/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, 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";