@vibeorm/sql 5.9.0 → 5.11.0

package/dist/ast.d.ts

@@ -307,6 +307,8 @@ export type SqlExpr = {
     /** The tested columns, in the subquery's projection order. */
     readonly columns: readonly ColRef[];
     readonly select: SelectStatement;
+    /** The subquery yields at most one row: one column, rendered `"fk" = (SELECT …)`. */
+    readonly single?: true;
 } | {
     readonly kind: "like";
     readonly column: ColRef;
@@ -450,12 +452,20 @@ export type SqlExpr = {
  *
  * `one` renders the constant `1` — the conventional EXISTS projection; it
  * cannot be combined with a column list.
+ *
+ * `exists` asks whether the statement's own FROM and WHERE match a row:
+ * `SELECT EXISTS (SELECT 1 FROM … WHERE …) AS "alias"` — one row, one
+ * boolean-valued column (PostgreSQL `boolean`, SQLite and MySQL `0`/`1`). It
+ * takes no column list, aggregate, grouping, order, paging, lock or join.
  */
 export type SelectExpr = {
     readonly kind: "countAll";
     readonly alias?: string;
 } | {
     readonly kind: "one";
+} | {
+    readonly kind: "exists";
+    readonly alias: string;
 };
 /** Arithmetic applied to a column's current value in an UPDATE ... SET. */
 export type SetOperator = "increment" | "decrement" | "multiply" | "divide";
@@ -574,10 +584,18 @@ export type OrderTerm = OrderByColumn | OrderByAggregate | OrderBySubquery;
 export type LateralJoin = {
     /** Join alias (`__lat_0`) — the outer projection selects `alias.columnAlias`. */
     readonly alias: string;
-    /** Column the aggregated JSON value is exposed under (`__rel_posts`). */
+    /**
+     * Column the aggregated JSON value is exposed under (`__rel_posts`). An
+     * `aggregate` lateral exposes one column per entry of its select's
+     * `aggregates` instead, under each entry's alias.
+     */
     readonly columnAlias: string;
-    /** jsonArray: many rows; jsonObject: one row or NULL; count: a scalar COUNT(*) lateral. */
-    readonly agg: "jsonArray" | "jsonObject" | "count";
+    /**
+     * jsonArray: many rows; jsonObject: one row or NULL; count: a scalar COUNT(*)
+     * lateral; aggregate: one ungrouped row of `aggregates` (no columns), which
+     * an aggregate without GROUP BY returns even over zero rows.
+     */
+    readonly agg: "jsonArray" | "jsonObject" | "count" | "aggregate";
     /**
      * Object output is the SQL-layer default. Positional rows follow the exact
      * select.columns order, using explicit output names (never SELECT *).
@@ -586,6 +604,20 @@ export type LateralJoin = {
      * slot. Consumers must use the SAME projection to decode the payload.
      */
     readonly rowFormat?: "object" | "positional";
+    /**
+     * Positional rows only: output names of `select.columns` the subselect
+     * projects for the statement's own use (an order key the aggregate's ORDER
+     * BY reads, a key a nested lateral correlates on) but the JSON row leaves
+     * out. The row is the remaining columns in `select.columns` order.
+     */
+    readonly hidden?: readonly string[];
+    /**
+     * `jsonObject` laterals only: output names of `select.columns` the lateral
+     * exposes as typed columns of its own beside the JSON value (`"alias"."name"`
+     * in the outer scope). The outer statement reads a key of the row from them
+     * without parsing the JSON; they are SQL NULL when the lateral finds no row.
+     */
+    readonly expose?: readonly string[];
     /** The correlated child select — may reference outer columns via table-qualified refs. */
     readonly select: SelectStatement;
 };
@@ -752,6 +784,175 @@ export type RowNumberProjection = {
     readonly orderBy: readonly OrderTerm[];
     readonly alias: string;
 };
+/**
+ * One window column of a select, rendered after `rowNumber`
+ * (`SelectStatement.windows`). Together the two kinds let a statement say
+ * which of its rows is the first to hold a key:
+ *
+ * - `ordinal`: `ROW_NUMBER() OVER ([ORDER BY …]) AS "alias"`, the row's
+ *   position among the rows of its query level, in `orderBy`, or in the order
+ *   the rows arrive when `orderBy` is empty (`OVER ()`).
+ * - `firstOrdinal`: `MIN(<ordinal>) OVER (PARTITION BY …) AS "alias"`, the
+ *   smallest `ordinal` among the rows that share the partition columns. The
+ *   database's own equality groups them (NULLs together), whatever the
+ *   column's type or collation.
+ *
+ * A window is computed before the `ORDER BY` and `LIMIT` of its own query
+ * level: number a page one level outside the select that cuts it.
+ */
+export type WindowColumn = {
+    readonly kind: "ordinal";
+    readonly alias: string;
+    readonly orderBy: readonly OrderTerm[];
+} | {
+    readonly kind: "firstOrdinal";
+    readonly alias: string;
+    readonly ordinal: ColRef;
+    readonly partitionBy: readonly ColRef[];
+};
+/**
+ * One column of a `SelectStatement.fromRow`: an outer column under the name
+ * the row gives it.
+ */
+export type RowSourceColumn = {
+    readonly column: ColRef;
+    readonly alias: string;
+};
+/**
+ * One common table expression of a select (`SelectStatement.with`):
+ * `"name" AS [MATERIALIZED] (<select>)`. `materialized` pins the table to one
+ * evaluation whatever the number of references: required when two readers
+ * must see the same rows of a select whose rows are numbered in arrival
+ * order.
+ */
+export type CommonTable = {
+    readonly name: string;
+    readonly select: SelectStatement;
+    readonly materialized?: true;
+};
+/**
+ * The place of one value in a positional JSON row ({@link LateralJoin}
+ * `rowFormat: "positional"`): its index among the row's `width` values. A row
+ * wider than `JSON_TRANSPORT.chunkSize` is an array of chunks, so the renderer
+ * needs both numbers to address the value.
+ */
+export type JsonSlot = {
+    readonly index: number;
+    readonly width: number;
+};
+/**
+ * One step of a walk through JSON a statement built: into one value of a
+ * positional row, or over every element of a list.
+ */
+export type JsonStep = {
+    readonly kind: "slot";
+    readonly slot: JsonSlot;
+} | {
+    readonly kind: "elements";
+};
+/**
+ * One key column of a {@link JsonKeys} source: `token` is the output name of
+ * the key's text as the JSON rows hold it (at `slot` of the row the walk
+ * ends at), `alias` the output name of the same key cast back to the
+ * column's own type (`member`, typed like a key-list member).
+ */
+export type JsonKeyColumn = {
+    readonly slot: JsonSlot;
+    readonly token: string;
+    readonly alias: string;
+    readonly member: KeyListMember;
+};
+/**
+ * The distinct keys of the rows a JSON walk reaches, as a derived-table FROM
+ * (`SelectStatement.fromJsonKeys`). `source` is a JSON column of a common
+ * table of the statement (`source.table` names it); `steps` walk from that
+ * value to positional rows, each of which holds the text of its key columns
+ * in the slots `keys` name. Renders on PostgreSQL as
+ *
+ *   `(SELECT "__vibe_k"."<token>", CAST("__vibe_k"."<token>" AS <type>) AS "<alias>"
+ *     FROM (SELECT DISTINCT <row> ->> <slot> AS "<token>"
+ *           FROM json_array_elements((SELECT json_agg(<list>) FROM "<table>" AS "__vibe_s" WHERE <list> IS NOT NULL))
+ *                AS "__vibe_d0"("value")
+ *           CROSS JOIN LATERAL json_array_elements("__vibe_d0"."value") AS "__vibe_e0"("value")) AS "__vibe_k")
+ *    AS "<table.name>"`
+ *
+ * Each list on the way is read through ONE value that holds that level's
+ * lists of every row (an uncorrelated `json_agg`, planned once), and a
+ * second list on the way wraps the first walk the same way. PostgreSQL
+ * estimates every `json_array_elements` call at 100 rows whatever it reads:
+ * walked row by row, the estimate is rows x 100 per list on the way, and two
+ * lists over 2 000 rows were priced past the cost where the server's JIT
+ * compiler optimizes (measured: 249 ms against 94 ms with JIT off). Read
+ * through one value, each list on the way is 100 x 100 rows at any depth and
+ * any row count. The price: that one value holds a level's lists of the whole
+ * statement, so it is bound by PostgreSQL's 1 GB limit on a single value.
+ *
+ * The database groups the keys by their text and types each one from that
+ * text with the key-list's base types (`postgresKeyListElementType`), so the
+ * laterals joined to the derived table compare `child."fk" = "<table.name>"."<alias>"`
+ * under the column's own operator and index. A row the walk does not reach
+ * (a missing to-one, an empty list) contributes nothing or a NULL key.
+ * Needs the `sharedListDictionary` capability; never together with another
+ * FROM form, a `table.alias` or a `rowLock`.
+ */
+export type JsonKeys = {
+    readonly source: ColRef;
+    readonly steps: readonly JsonStep[];
+    readonly keys: readonly JsonKeyColumn[];
+};
+/**
+ * The rows of a common table, read back through arrays, as a FROM
+ * (`SelectStatement.fromTableArrays`): `columns` of the table `source`, each
+ * under the output name `alias`, in the order of the column `orderBy`.
+ * Renders on PostgreSQL as
+ *
+ *   `(SELECT array_agg("<source>"."<name>" ORDER BY "<source>"."<orderBy>") AS "__vibe_a0", …
+ *     FROM "<source>") AS "__vibe_a"
+ *    CROSS JOIN LATERAL unnest("__vibe_a"."__vibe_a0", …) AS "<table.name>"("<alias>", …)`
+ *
+ * It returns the rows a plain read of the table would, typed as the table's
+ * columns (no text on the way), and exists for two things the plain read
+ * does not give. The estimate: PostgreSQL expects 10 rows from `unnest` of an
+ * array it cannot see, while it expects one row per input row from a table
+ * grouped by a key it can trace to a unique column, and every lateral joined
+ * to the rows is priced once per expected row (measured: 20 000 rows of 10
+ * keys priced at 3.1 million against 129 000, which decides whether the
+ * server's JIT compiler runs). The order: laterals joined to the rows read
+ * their tables in `orderBy` order, not in a hash table's (measured: the same
+ * 20 000 index lookups in 440 ms against 1 066 ms). Needs the `carrierRows`
+ * capability on a dialect whose `lateralJson.carriedLists` is `"firstRow"`;
+ * never together with another FROM form, a `table.alias` or a `rowLock`.
+ */
+export type TableArrays = {
+    readonly source: string;
+    readonly columns: readonly {
+        readonly name: string;
+        readonly alias: string;
+    }[];
+    readonly orderBy: string;
+};
+/**
+ * A JSON list a statement returns on its first row only
+ * (`SelectStatement.firstRowLists`): `list` describes the list as a
+ * `jsonArray` lateral does (its select, row format and column alias; the join
+ * alias is unused), `ordinal` is the statement's row ordinal (see
+ * {@link WindowColumn} `ordinal`). Renders as a projection:
+ *
+ *   `CASE WHEN <ordinal> = 1 THEN (SELECT COALESCE(json_agg(<row>), '[]'::json)
+ *    FROM (<list.select>) AS "__sub") END AS "<list.columnAlias>"`
+ *
+ * The select must not read the statement's own row: an uncorrelated scalar
+ * subquery is planned and costed once and runs once, when the first row asks
+ * for it. A lateral gated on the ordinal returns the same rows, but
+ * PostgreSQL prices it once per row of the statement (measured: 500 rows
+ * priced the list 500 times, the estimate passed `jit_above_cost` and the
+ * statement spent 100 ms compiling against 5 ms running). Every other row
+ * holds SQL NULL. Needs the `sharedListDictionary` capability.
+ */
+export type FirstRowList = {
+    readonly ordinal: ColRef;
+    readonly list: LateralJoin;
+};
 /**
  * A PER-KEY PAGE of one child table as a derived-table FROM
  * (`SelectStatement.keyPage`): for every listed key tuple, the child rows
@@ -844,6 +1045,14 @@ export type GroupingSets = {
 };
 export type SelectStatement = {
     readonly kind: "select";
+    /**
+     * Common table expressions, rendered ahead of the select (`WITH a AS (…),
+     * b AS (…) SELECT …`) and bound first, in order. The statement and the
+     * tables after it read a table by its name as a plain `table`. Only on the
+     * outermost select of a statement; needs the `sharedListDictionary`
+     * capability. See {@link CommonTable}.
+     */
+    readonly with?: readonly CommonTable[];
     readonly table: TableRef;
     /** Empty array renders as `SELECT *` (unless `selectExpr` replaces it). */
     readonly columns: readonly ColRef[];
@@ -893,6 +1102,39 @@ export type SelectStatement = {
     readonly leftJoins?: readonly LeftJoin[];
     /** ROW_NUMBER window projection — see {@link RowNumberProjection}. */
     readonly rowNumber?: RowNumberProjection;
+    /** Window columns, rendered after `rowNumber` — see {@link WindowColumn}. */
+    readonly windows?: readonly WindowColumn[];
+    /** JSON lists of the first row, rendered after `windows` — see {@link FirstRowList}. */
+    readonly firstRowLists?: readonly FirstRowList[];
+    /**
+     * Every column of the statement's FROM, ahead of the other projections:
+     * `SELECT "<from>".*, …`. With `fromSelect` and an empty `columns` list (a
+     * level that adds window columns to the level below it re-exposes that
+     * level's columns without naming each one again), or over a common table
+     * of the statement's own `with`, read under `table.alias ?? table.name`,
+     * where the other projections follow it.
+     */
+    readonly allColumns?: true;
+    /**
+     * Derived-table FROM of exactly ONE row built from outer columns: renders
+     * `FROM (SELECT <column> AS "<alias>", …) AS "<table.name>"`. Inside a
+     * lateral it gives outer values the column names of a table row, so the
+     * laterals joined to it correlate as they would to that table's row
+     * (`child."fk" = "<table.name>"."id"`) and the table is not read again.
+     * Needs the `carrierRows` capability; never together with `fromSelect`,
+     * `keyPage`, `fromUnion`, `fromKeys`, a `table.alias` or a `rowLock`.
+     */
+    readonly fromRow?: readonly RowSourceColumn[];
+    /**
+     * Derived-table FROM over the distinct, typed keys of a JSON walk, named
+     * `table.name` — see {@link JsonKeys}.
+     */
+    readonly fromJsonKeys?: JsonKeys;
+    /**
+     * FROM over the rows of a common table read back through arrays, named
+     * `table.name` — see {@link TableArrays}.
+     */
+    readonly fromTableArrays?: TableArrays;
     /**
      * Fix lane Q1 (DB-01): derived-table FROM over a per-key page — renders
      * `FROM (<per-key page>) AS "<table.name>"` like `fromSelect` (and never
@@ -1044,7 +1286,18 @@ export type ReturningColumn = string | {
 } | {
     readonly name: string;
     readonly transform: "jsonText";
-} | CaptureReturningColumn | OtherRowReturningColumn;
+} | CaptureReturningColumn | OtherRowReturningColumn | ServerVersionReturningColumn;
+/**
+ * The server's `server_version_num` as text, exposed as `alias`:
+ * `pg_catalog.current_setting('server_version_num') AS "alias"`. Rides a write
+ * whose client does not know the server version yet, so the next statement can
+ * take the form that version allows without a read of its own. Dialects with
+ * the `rowCapture` capability only (the version decides whether it applies).
+ */
+export type ServerVersionReturningColumn = {
+    readonly serverVersion: true;
+    readonly alias: string;
+};
 /**
  * A RETURNING column read from a row OTHER than the one the statement wrote,
  * exposed as `alias` and projected like the written row's own column
@@ -1201,6 +1454,42 @@ export type OnConflictUpdate = {
      * mysql's ODKU has no WHERE and refuses it (`VIBE_UNSUPPORTED_CAPABILITY`).
      */
     readonly updateWhere?: SqlExpr;
+    /**
+     * Skip-unchanged guard: the conflicting row is updated only when at least
+     * one of these columns' stored value differs, NULL counting as a value,
+     * from the value its `update` assignment would write (each column must have
+     * one). Rendered as the first member of the update arm's `WHERE`, AND-ed
+     * with {@link OnConflictUpdate.updateWhere}; a skipped row writes nothing
+     * and returns nothing. On ON DUPLICATE KEY UPDATE (no WHERE) the columns it
+     * leaves out are assigned first, keeping their stored value when nothing
+     * else would change, and the dialect itself skips the unchanged row.
+     * Needs `upsertSkipUnchanged`.
+     */
+    readonly skipUnchanged?: readonly UnchangedColumn[];
+    /**
+     * The table's native row-security predicate, RAW SQL without parameters
+     * (the managed policy's check, columns qualified by the target table's
+     * name). With a guard on the arm ({@link OnConflictUpdate.updateWhere} or
+     * {@link OnConflictUpdate.skipUnchanged}) the arm's `WHERE` becomes
+     * `(<policy>) IS NOT TRUE OR (<guard>)`: PostgreSQL evaluates that `WHERE`
+     * before its row-security check of the conflicting row, so a row the policy
+     * hides must always take the update path and fail that check, whatever its
+     * values. Ignored when the arm has no guard; refused by a dialect without
+     * `nativeRowLevelSecurity`.
+     */
+    readonly rowPolicy?: string;
+    /**
+     * MySQL only, a single-row statement: the duplicate arm also runs
+     * `` `column` = IF(LAST_INSERT_ID(flag), `t`.`column`, `t`.`column`) `` (a
+     * self-assignment, rendered last), so the statement reports `flag` as its
+     * insert id exactly when the row took the update arm — the one signal that
+     * tells an inserted row from an unchanged one when the driver reports no
+     * `Duplicates:` info. `flag` is a decimal literal.
+     */
+    readonly duplicateFlag?: {
+        readonly column: string;
+        readonly flag: string;
+    };
     /**
      * MySQL only (`upsertForm: "onDuplicateKey"`): append
      * `` `col` = LAST_INSERT_ID(`col`) `` to the update list so the UPDATE arm
@@ -1210,6 +1499,41 @@ export type OnConflictUpdate = {
      */
     readonly lastInsertIdColumn?: string;
 };
+/**
+ * One column a skip-unchanged conflict arm compares. `json`: a Json column,
+ * compared as `jsonb` on postgres (its `json` type has no equality operator;
+ * `"list"` for a Json list).
+ */
+export type UnchangedColumn = {
+    readonly column: string;
+    readonly json?: "scalar" | "list";
+    /**
+     * A column whose SQL equality can be coarser than "the stored value would
+     * not change"; the renderer compares it exactly where the dialect needs it.
+     * See {@link UnchangedExactness}.
+     */
+    readonly bytes?: UnchangedExactness;
+    /**
+     * A text column the schema declares with a folding type or collation
+     * (`citext`, a `@collation` that is not byte-ordered): its equality may call
+     * `'x'` and `'X'` equal on any dialect, not only under MySQL's default.
+     */
+    readonly folds?: true;
+    /** The column is a list of `bytes`'s kind (a postgres array). */
+    readonly list?: true;
+};
+/**
+ * Why a compared column's own equality may call two different stored values
+ * equal:
+ * - `"text"`: a text column; MySQL's default `_ai_ci` collation folds case
+ *   and accents (and see `folds`).
+ * - `"decimal"`: a Decimal column without a declared scale (PostgreSQL's bare
+ *   `numeric` keeps `1.50` and `1.5` apart, its equality does not).
+ * - `"float"`: a float column (`-0` equals `0`).
+ * - `"other"`: a Json or list column, or a text-like column of another
+ *   declared type, compared by its bytes on MySQL.
+ */
+export type UnchangedExactness = "text" | "decimal" | "float" | "other";
 /**
  * Conflicting rows are skipped (`createMany({ skipDuplicates: true })`).
  * An empty/absent target means "any conflict" — the mysql form
@@ -1528,6 +1852,15 @@ export type ChainResult = {
      * guard, so it is evaluated exactly once, on the one guaranteed result row.
      */
     readonly veto?: readonly ChainVeto[];
+    /**
+     * A step whose rows every veto depends on: when it returned no row, no veto
+     * is checked and the statement succeeds, answering the one guaranteed row
+     * with NULL columns and the tally (rendered as the first CASE arm, `WHEN NOT
+     * EXISTS (SELECT 1 FROM "step") THEN <tally>`). A nested write whose
+     * missing parent is an answer, not an error, gates its children's vetoes on
+     * the parent step this way. Requires `tally` and at least one veto.
+     */
+    readonly vetoGate?: string;
     /**
      * One column `alias` on every result row: the number of rows the listed
      * data-modifying steps returned (their RETURNING rows = their direct

package/dist/codecs.d.ts

@@ -76,15 +76,30 @@ export type WireFidelity = {
      */
     readonly bytes?: "buffer";
     /**
-     * Zone-less date-time text (MySQL DATETIME / TIMESTAMP / DATE) is read as a
-     * UTC instant by the driver (`"utc"`: mysql2 with `timezone: "Z"`). Absent
-     * means another or an unknown zone (another `timezone` option, an injected
-     * pool). Never prunes a decoder: the runtime reads it to decide whether a
-     * dialect default of `"join"` keeps value identity — the JSON transport
-     * decodes that text as UTC (`lateralJson.requiresUtcDateTimeWire`, lane J).
+     * The zone the driver reads zone-less date-time text in (MySQL DATETIME /
+     * TIMESTAMP / DATE): `"utc"` (mysql2 with `timezone: "Z"`), a fixed offset
+     * in minutes east of UTC, or `"local"` (the process zone, read the way
+     * mysql2 builds a local `Date`). The MySQL DateTime decoders read the same
+     * text in the same zone wherever it arrives as text (the join strategy's
+     * JSON, a page key, `exactDates`), so one stored cell is one instant on every
+     * path; the adapter writes a bound parameter in it. Absent reads as UTC.
+     * Never prunes a decoder. `"utc"` alone also lets a dialect default of
+     * `"join"` apply (`lateralJson.requiresUtcDateTimeWire`): it is declared only
+     * where the zone is known to be UTC.
      */
-    readonly zoneLessDateTime?: "utc";
+    readonly zoneLessDateTime?: DateTimeZone;
 };
+/** A zone zone-less date-time text is read in: UTC, a fixed offset in minutes east of UTC, or the process's local zone. */
+export type DateTimeZone = "utc" | "local" | {
+    readonly offsetMinutes: number;
+};
+/**
+ * The cache-key fragment of a wire's date-time zone: `""` when zone-less text
+ * reads as UTC, so every UTC plan keeps its key; else `"local"` or the offset.
+ */
+export declare function dateTimeZoneKey(params: {
+    wire: WireFidelity | undefined;
+}): string;
 /**
  * Is this scalar type's DECODE a no-op under the declared wire fidelity?
  * Provable against the decode implementations in this file, identically on
@@ -115,7 +130,8 @@ export declare function decodeIsNoop(params: {
     wire: WireFidelity | undefined;
 }): boolean;
 /**
- * Parse date-time text into a `Date`, reading ZONE-LESS text as **UTC**.
+ * Parse date-time text into a `Date`, reading ZONE-LESS text as **UTC** — for
+ * text a CALLER wrote (a filter or data value, a validator's check).
  *
  * ECMA-262 reads `2026-01-15T12:00:00` as process-LOCAL time, so the same
  * stored value would decode to a different instant on every host time zone,
@@ -124,9 +140,12 @@ export declare function decodeIsNoop(params: {
  * that yields ONE instant everywhere (MYSQL-2, live-proven; the postgres
  * `timestamp` case is proven by apps/tests `timestamp-zones.e2e`). Text with
  * an explicit `Z`/offset and date-only text parse as ECMA-262 already reads
- * them (as written / UTC midnight); anything unparseable is `undefined` so the
- * caller keeps its own fallback. Fractions beyond milliseconds are truncated —
- * `Date` has no finer resolution and engines differ on longer fractions.
+ * them (as written / UTC midnight); any other form the engine reads
+ * (`Jan 15 2026 12:00 GMT`) is accepted as the engine reads it, and
+ * anything unparseable is `undefined` so the caller keeps its own fallback.
+ * Fractions beyond milliseconds are truncated — `Date` has no finer
+ * resolution and engines differ on longer fractions. Text from the DATABASE
+ * never takes that last, guessing step ({@link parseDatabaseDateTime}).
  */
 export declare function parseDateTimeText(params: {
     text: string;
@@ -144,11 +163,14 @@ export declare function parseDateTimeText(params: {
  * milliseconds, an offset with seconds applied exactly.
  *
  * `undefined` for every other text — a 4-digit AD value keeps the parse it
- * had — and for an instant outside the `Date` range. Exported for the adapters
+ * had, unless `anyYear` (the database-text parser, after its other forms
+ * declined: an offset with seconds) — and for an instant outside the `Date`
+ * range. Exported for the adapters
  * whose zone-less driver parsers fall back to it (one rule, rule 6).
  */
 export declare function parseExtendedDateTimeText(params: {
     text: string;
+    anyYear?: boolean;
 }): Date | undefined;
 /**
  * The decode refusal of a non-finite or unparseable DateTime — one error for
@@ -157,6 +179,78 @@ export declare function parseExtendedDateTimeText(params: {
  * reports exactly this error.
  */
 export declare function decodedDateTimeRefusal(): VibeError;
+/**
+ * The refusal of database date-time text no decoder reads, by its cause —
+ * each with its own `meta.reason`, so the message names the right remedy:
+ *
+ * - `"zero-date"`: a MySQL zero date or a zero month or day, which has no
+ *   instant (mysql2 renders a binary zero `DATETIME` as `undefined 00:00:00`);
+ * - `"datetime-out-of-range"`: ISO-shaped text with no `Date` (a year past
+ *   ±275760, `294276-12-31` in PostgreSQL, or a day the calendar lacks);
+ * - `"datetime-text-layout"`: any other layout; on PostgreSQL its cause is a
+ *   `DateStyle` other than ISO, and the error names that remedy
+ *   ({@link dateTimeTextLayoutError}).
+ *
+ * The text itself is never included.
+ */
+export declare function undecodableDateTimeText(params: {
+    text: string;
+    dialect: Dialect;
+}): VibeError;
+/**
+ * The refusal for database DateTime text outside the ISO layouts. On
+ * PostgreSQL its cause is a `DateStyle` other than ISO, set by the server,
+ * the database or the role; the message and `meta.fix` name the remedies.
+ * The text itself is never included.
+ */
+export declare function dateTimeTextLayoutError(): VibeError;
+/**
+ * The codec of a DateTime field whose native type is a date-only column on
+ * `dialect`, or `undefined` (the DateTime table row applies): MySQL's
+ * `@db.Date` ({@link mysqlDateOnlyCodec}). PostgreSQL's `date` input and
+ * SQLite's text need none.
+ */
+export declare function dateOnlyCodec(params: {
+    dialect: Dialect;
+    nativeType: string | undefined;
+}): ScalarCodec | undefined;
+/**
+ * The instant of zone-less date-time text a MySQL server printed (`DATETIME`,
+ * `DATE`, a `TIMESTAMP` in the session zone), read in `zone`, the zone mysql2
+ * reads the same cell in; the years 0-99 keep their year. `undefined` for any
+ * other text. For the adapter's raw path; ORM reads take the codec table.
+ */
+export declare function parseZoneLessDateTime(params: {
+    text: string;
+    zone: DateTimeZone | undefined;
+}): Date | undefined;
+/**
+ * `codec` as it reads under the adapter's declared zone
+ * (`wire.zoneLessDateTime`): a MySQL DateTime or date-only codec reads
+ * zone-less text in that zone when it is not UTC; every other codec, and every
+ * codec under UTC, is returned unchanged. Encode is never changed: a `Date`
+ * goes to the driver, which writes it in the same zone.
+ */
+export declare function zonedCodec(params: {
+    dialect: Dialect;
+    codec: ScalarCodec;
+    wire: WireFidelity | undefined;
+}): ScalarCodec;
+/**
+ * The text a MySQL adapter writes for a parameter the DateTime codec bound
+ * exactly (a `Date` read from the server's text, which carries more fraction
+ * digits than a `Date` holds): the wall clock it was read from when that text,
+ * read in `zone`, is this instant (so a wall clock in a daylight-saving gap
+ * under `"local"` addresses its own cell); else the instant's wall clock in
+ * `zone` (text with an offset, or read in another zone). Every fraction digit
+ * is kept, and at least three are written. `undefined` for every other value,
+ * which the driver writes as it always did. A keyset position over such a
+ * value carries the same text.
+ */
+export declare function mysqlBoundTimestampText(params: {
+    value: unknown;
+    zone: DateTimeZone | undefined;
+}): string | undefined;
 /**
  * The time-of-day codec for a DateTime field's native type, or `undefined`
  * when the native type is not `time`/`timetz` (the DateTime table row

package/dist/composable.d.ts

@@ -21,10 +21,22 @@ export type SqlTag = {
         value: NoInfer<T>;
         decoder?: ResultDecoder<T>;
     }) => SqlFragment;
-    readonly join: (params: {
-        items: readonly unknown[];
-        separator?: SqlFragment;
-    }) => SqlFragment;
+    /**
+     * A list: fragments spliced, anything else bound as one value each, joined
+     * by `separator` (default `, `). `sql.join(items, separator)` and
+     * `sql.join({ items, separator })` are the same call.
+     */
+    readonly join: {
+        (items: readonly unknown[], separator?: SqlFragment): SqlFragment;
+        (params: {
+            items: readonly unknown[];
+            separator?: SqlFragment;
+        }): SqlFragment;
+    };
+    /** Every condition must hold: `(a) AND (b)`, each part in parentheses; `undefined` parts are skipped, and none left is `TRUE`. */
+    readonly and: (parts: readonly (SqlFragment | undefined)[]) => SqlFragment;
+    /** Any condition may hold: `(a) OR (b)`, each part in parentheses; `undefined` parts are skipped, and none left is `FALSE`. */
+    readonly or: (parts: readonly (SqlFragment | undefined)[]) => SqlFragment;
     readonly existing: (params: {
         column: string;
     }) => SqlFragment;
@@ -62,6 +74,34 @@ export declare function compileSql(params: {
     text: string;
     values: unknown[];
 };
+/**
+ * A tagged template whose every interpolated value binds as one plain
+ * parameter (no fragment, no typed array or JSON-list parameter), captured
+ * without building a fragment. Its values are snapshotted when captured, as
+ * `sql` snapshots them; `compileSqlTemplate` renders it.
+ */
+export declare class PlainSqlTemplate {
+    readonly strings: TemplateStringsArray;
+    readonly values: readonly unknown[];
+    constructor(strings: TemplateStringsArray, values: readonly unknown[]);
+}
+/**
+ * What `sql` builds for a template, except that a template whose
+ * values all bind as plain parameters comes back as a `PlainSqlTemplate`:
+ * the same text and values once compiled, without a fragment per call.
+ */
+export declare function captureSqlTemplate(params: {
+    strings: TemplateStringsArray;
+    values: readonly unknown[];
+}): SqlFragment | PlainSqlTemplate;
+/** `compileSql` over what `captureSqlTemplate` returned. */
+export declare function compileSqlTemplate(params: {
+    dialect: SqlDialect;
+    query: SqlFragment | PlainSqlTemplate;
+}): {
+    text: string;
+    values: unknown[];
+};
 /** Whether a nested SQL fragment reads the incoming row (MySQL alias declaration). */
 export declare function sqlUsesIncoming(params: {
     fragment: SqlFragment;