@vibeorm/sql 5.10.0 → 5.11.0

package/dist/ast.d.ts

@@ -611,6 +611,13 @@ export type LateralJoin = {
      * 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;
 };
@@ -777,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
@@ -869,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[];
@@ -918,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

package/dist/dialect.d.ts

@@ -210,6 +210,55 @@ export type SqlDialect = {
          * where every adapter pins zone-less values to UTC (postgres).
          */
         readonly requiresUtcDateTimeWire: boolean;
+        /**
+         * How a dictionary of shared lists reads its distinct keys back out of
+         * the JSON the statement built (`SelectStatement.fromJsonKeys`).
+         * `"elements"`: one set-returning call per list on the way and a cast of
+         * the key text to the key-list's base type (postgres). `"jsonTable"`:
+         * one `JSON_TABLE` whose row path walks the lists, `JSON`-typed columns
+         * grouped as JSON and unquoted outside (MySQL; see
+         * `dialects/mysql-json-keys.ts` for why no other form is both right and
+         * indexed).
+         */
+        readonly keysFromJson: "elements" | "jsonTable";
+        /**
+         * How a common table is held to one evaluation (`CommonTable.materialized`):
+         * `"keyword"` — `AS MATERIALIZED (…)`; `"limit"` — the dialect has no such
+         * keyword and merges a common table into each reference unless its select
+         * is limited, so an unlimited select gets the largest `LIMIT` (MySQL).
+         */
+        readonly pinnedCommonTable: "keyword" | "limit";
+        /**
+         * Where a statement with carrier rows returns the lists it builds once
+         * per distinct target. `"firstRow"`: all of them as one JSON list on the
+         * statement's first row, built by an uncorrelated scalar subquery over the
+         * distinct keys (`SelectStatement.fromTableArrays`); PostgreSQL prices that
+         * subquery once, where it prices a lateral once per row of the statement
+         * and the estimate alone starts the JIT compiler from about 1 000 rows.
+         * `"carrierRow"`: each target's lists on the first row that reads it, from
+         * a lateral gated on that row (`SelectStatement.fromRow`); MySQL has no
+         * JIT compiler, runs the gated lateral once per target, and has no arrays
+         * to read the keys back through. The runtime builds `"carrierRow"` on a
+         * `"firstRow"` dialect too where a statement's root is proven to return
+         * a few rows: the estimate is bounded there and the statement is cheaper.
+         */
+        readonly carriedLists: "firstRow" | "carrierRow";
+        /**
+         * The server setting that caps one JSON value where the server can answer
+         * a larger one without failing the statement (MySQL `max_allowed_packet`,
+         * 64 MB by default). Measured on MySQL 26.7 with the statements the
+         * runtime builds: a carried row whose lists together pass the cap arrives
+         * as SQL NULL with warning 1301, a dictionary past it as its JSON text cut
+         * a little past the cap with the same warning, and one list past it fails
+         * the statement (errno 1301), which leaves a transaction open. The
+         * runtime reads a NULL or unparsable text where the statement always
+         * builds a JSON value as that overflow (`VIBE_RESULT_TOO_LARGE`), and the
+         * client answers a find that fails with that code under the `"query"`
+         * strategy. `null`: the server fails the statement itself and the error
+         * reaches the caller (PostgreSQL: 1 GB, and a failed statement aborts its
+         * transaction).
+         */
+        readonly silentSizeLimit: string | null;
     } | null;
     /**
      * The relation strategy a client uses when neither the call nor the client

package/dist/dialects/mysql-json-keys.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MySQL's text for the two pieces of a dictionary of shared lists that it
+ * cannot share with PostgreSQL: the distinct keys read back out of the JSON a
+ * statement built (`SelectStatement.fromJsonKeys`), and a common table that
+ * must be evaluated once (`CommonTable.materialized`).
+ *
+ * Every choice below was measured on MySQL 26.7 (500 roots, 1 000 keys):
+ *
+ * - A `VARCHAR` column of `JSON_TABLE` takes the CONNECTION's collation with
+ *   implicit coercibility. Compared with a foreign-key column it fails
+ *   (`ER_CANT_AGGREGATE_2COLLATIONS`) whenever the two collations differ, and
+ *   mysql2 connects as `utf8mb4_unicode_ci` while MySQL creates columns as
+ *   `utf8mb4_0900_ai_ci`.
+ * - The same column declared `COLLATE utf8mb4_bin` runs, but the binary
+ *   collation wins the comparison and the foreign-key index is not used
+ *   (627 ms against 25 ms).
+ * - `JSON_UNQUOTE(<a JSON value>)` is coercible like a bound literal, also
+ *   through a materialized derived table, so the COLUMN's collation decides
+ *   the comparison and its index serves it: the key matches its children
+ *   exactly as `WHERE fk IN (?)` matches them.
+ * - `DISTINCT` on a `JSON` column compares the values exactly. On text under
+ *   `utf8mb4_bin` it pads (`'a'` and `'a '` are one key), which would lose an
+ *   entry where the key column's own collation does not pad.
+ */
+export {};
+//# sourceMappingURL=mysql-json-keys.d.ts.map

package/dist/index.d.ts

@@ -48,7 +48,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, AdvisoryLocksStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainCapture, CaptureReturningColumn, CaptureCascade, CaptureCascadeReturningColumn, CaptureCell, CaptureHop, OtherRowReturningColumn, ServerVersionReturningColumn, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, GroupKeyExpression, GroupingSets, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, UnchangedColumn, UnchangedExactness, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, SourceColumnRef, UpdateSource, UpdateTableSource, UpdateSelectSource, TableRef, UpdateStatement, } from "./ast.ts";
+export type { AdvisoryLockKey, AdvisoryLockStatement, AdvisoryLocksStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainCapture, CaptureReturningColumn, CaptureCascade, CaptureCascadeReturningColumn, CaptureCell, CaptureHop, OtherRowReturningColumn, ServerVersionReturningColumn, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, GroupKeyExpression, GroupingSets, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, UnchangedColumn, UnchangedExactness, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, RowSourceColumn, CommonTable, FirstRowList, JsonKeyColumn, JsonKeys, TableArrays, JsonSlot, JsonStep, WindowColumn, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, SourceColumnRef, UpdateSource, UpdateTableSource, UpdateSelectSource, TableRef, UpdateStatement, } from "./ast.ts";
 export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, COALESCE_REF_NAME, SQL_DEFAULT_CELL, SQL_KEEP_CELL, chainVetoToken, coalesceRef, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isSqlKeepCell, isStepColumnRef, isSourceColumnRef, sourceColumnRef, isCaptureReturningColumn, isOtherRowReturningColumn, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
 export type { AdvisoryLockFunctions, AdvisoryLockModeFunctions, RowLockSyntax, EmptyInsertSyntax, SqlDialect, } from "./dialect.ts";
 export { ADVISORY_KEY_BOUNDS, describeRowLock, renderAdvisoryLock, renderAdvisoryLocks, renderRowLockClause } from "./locks.ts";
@@ -58,7 +58,8 @@ export { sqliteDialect } from "./dialects/sqlite.ts";
 export { mysqlDialect } from "./dialects/mysql.ts";
 export { SQL_DIALECTS, getSqlDialect } from "./dialects/registry.ts";
 export { tableDefinitionParts } from "./dialects/sqlite-table-definition.ts";
-export { keyListBindsUntypedRows, postgresBulkInsertArrayCastOf, postgresKeyListElementTypeOf } from "./key-list.ts";
+export { jsonKeyTokenCast, jsonKeysTyped, keyListBindsUntypedRows, mysqlJsonKeyTypeOf, postgresBulkInsertArrayCastOf, postgresKeyListElementTypeOf } from "./key-list.ts";
+export type { MysqlJsonKeyType } from "./key-list.ts";
 export { renderPredicate, renderSchemaExpression } from "./predicate.ts";
 export { renderLocalDateCheck } from "./local-date.ts";
 export { isTimeZoneName, renderDateTruncation } from "./date-truncation.ts";