uql-orm 0.56.0 → 0.58.0

package/dist/dialect/aliases.d.ts

@@ -14,13 +14,11 @@ export declare const COUNT_ALIAS = "_uql_count";
 export declare const TOTAL_ALIAS = "_uql_total";
 /** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
 export declare const DISTINCT_DERIVED_ALIAS = "_uql_distinct";
-/** Prefix for the derived table each branch of a per-parent bounded read is wrapped in. */
-export declare const PER_PARENT_BRANCH_ALIAS = "_uql_p";
-/** The row source a `LATERAL` per-parent read correlates each of its branches against. */
-export declare const PER_PARENT_KEYS_ALIAS = "_uql_keys";
-/** Prefix for the alias an exploded JSON array element is read through. */
-export declare const JSON_ELEM_ALIAS_PREFIX = "_uql_elem";
-/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */
+/** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
+export declare const RELATION_ROW_ALIAS = "_uql_row";
+/** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */
+export declare const JSON_ELEM_ALIAS = "_uql_elem";
+/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS}. */
 export declare const JSON_PULL_ALIAS = "_uql_pull";
 /** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
 export declare const REL_TEMP_PREFIX = "_uql_rel_";
@@ -40,3 +38,8 @@ export declare const UPSERT_SOURCE_ALIAS = "_uql_src";
  * ranks a field that is not there as all-equal rather than failing, so a drift would go unnoticed.
  */
 export declare function sortCountField(relKey: string): string;
+/**
+ * The column a relation's rows carry one sort term out in, beside the columns they answer under, for
+ * the aggregate reading them to order by: `_uql_sort_createdAt`.
+ */
+export declare function relationSortColumn(path: string): string;

package/dist/dialect/aliases.js

@@ -14,13 +14,11 @@ export const COUNT_ALIAS = '_uql_count';
 export const TOTAL_ALIAS = '_uql_total';
 /** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
 export const DISTINCT_DERIVED_ALIAS = '_uql_distinct';
-/** Prefix for the derived table each branch of a per-parent bounded read is wrapped in. */
-export const PER_PARENT_BRANCH_ALIAS = '_uql_p';
-/** The row source a `LATERAL` per-parent read correlates each of its branches against. */
-export const PER_PARENT_KEYS_ALIAS = '_uql_keys';
-/** Prefix for the alias an exploded JSON array element is read through. */
-export const JSON_ELEM_ALIAS_PREFIX = '_uql_elem';
-/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */
+/** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
+export const RELATION_ROW_ALIAS = '_uql_row';
+/** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */
+export const JSON_ELEM_ALIAS = '_uql_elem';
+/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS}. */
 export const JSON_PULL_ALIAS = '_uql_pull';
 /** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
 export const REL_TEMP_PREFIX = '_uql_rel_';
@@ -42,3 +40,10 @@ export const UPSERT_SOURCE_ALIAS = '_uql_src';
 export function sortCountField(relKey) {
     return `_uql_sort_count_${relKey}`;
 }
+/**
+ * The column a relation's rows carry one sort term out in, beside the columns they answer under, for
+ * the aggregate reading them to order by: `_uql_sort_createdAt`.
+ */
+export function relationSortColumn(path) {
+    return `_uql_sort_${path}`;
+}

package/dist/dialect/hydrateColumn.d.ts

@@ -2,9 +2,10 @@ import { type VectorCast } from './vectorCast.js';
 /**
  * How a stored column is decoded on read: the inverse of `AbstractSqlDialect.persistKind`. `json`
  * parses; a {@link VectorCast} says which literal; `boolean` undoes an engine with no boolean type,
- * `number` and `bigint` a driver that hands a wide integer or a decimal back as text.
+ * `number` and `bigint` a driver that hands a wide integer or a decimal back as text, and `date` and
+ * `bytes` a row that crossed JSON inside its parent's statement, which spells both as text.
  */
-export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | VectorCast;
+export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | 'date' | 'bytes' | VectorCast;
 /**
  * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
  * row walk, so classifying a column and decoding it stay one subject in one file.
@@ -14,3 +15,8 @@ export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | VectorCast;
  * that does not match its column's format is returned untouched rather than replaced by a guess.
  */
 export declare function decodeColumn(value: unknown, kind: HydrateKind): unknown;
+/**
+ * What bytes crossing JSON start with, before two hex digits per byte: Postgres's own text for `bytea`,
+ * which every dialect spells, so a string a driver reads from a column on its own is never mistaken.
+ */
+export declare const BYTES_PREFIX = "\\x";

package/dist/dialect/hydrateColumn.js

@@ -13,6 +13,14 @@ export function decodeColumn(value, kind) {
         // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
         return typeof value === 'boolean' ? value : Boolean(value);
     }
+    if (kind === 'date') {
+        return typeof value === 'string' ? (parseDate(value) ?? value) : value;
+    }
+    if (kind === 'bytes') {
+        return typeof value === 'string' && value.startsWith(BYTES_PREFIX)
+            ? hexBytes(value.slice(BYTES_PREFIX.length))
+            : value;
+    }
     const text = asText(value);
     if (kind === 'bigint') {
         if (typeof value === 'bigint') {
@@ -32,7 +40,7 @@ export function decodeColumn(value, kind) {
         return value;
     }
     if (kind === 'number') {
-        return Number.isNaN(Number(text)) ? value : decodeWideNumber(text);
+        return decodeWideNumber(text);
     }
     if (kind === 'json') {
         try {
@@ -45,6 +53,30 @@ export function decodeColumn(value, kind) {
     }
     return parseVectorLiteral(text, kind) ?? value;
 }
+/**
+ * An ISO 8601 timestamp as a `Date`, its fraction cut to the milliseconds one holds, and a bare date at
+ * local midnight, which is how `pg` reads a `date`. `undefined` for text that is neither.
+ */
+function parseDate(text) {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+    const date = day
+        ? new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3]))
+        : new Date(text.replace(/(\.\d{3})\d+/, '$1'));
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}
+/**
+ * What bytes crossing JSON start with, before two hex digits per byte: Postgres's own text for `bytea`,
+ * which every dialect spells, so a string a driver reads from a column on its own is never mistaken.
+ */
+export const BYTES_PREFIX = '\\x';
+/** Two hex digits per byte, back to bytes. */
+function hexBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let at = 0; at < bytes.length; at++) {
+        bytes[at] = Number.parseInt(hex.slice(at * 2, at * 2 + 2), 16);
+    }
+    return bytes;
+}
 /** Lazy so a consumer that never reads an encoded column never constructs one. */
 let decoder;
 /**

package/dist/dialect/jsonSql.d.ts

@@ -5,20 +5,28 @@ import type { FieldOptions, FieldType } from '../type/index.js';
  * differently from an ANSI string literal.
  */
 export declare function jsonPath(path: string, suffix?: string): string;
+/** How many argument groups of `size` fit in one call beside its target, under `maxArgs`. */
+export declare function groupsPerCall(maxArgs: number, size: number): number;
+/**
+ * `fn(target, ...groups)`, nested wherever one call would take more than `maxArgs` arguments: each call
+ * applies its share to what the call inside it returned, as `JSON_SET`, `JSON_REMOVE` and `json_insert`
+ * do. A group, such as a path and its value, stays in one call.
+ */
+export declare function chainedCall(fn: string, target: string, groups: readonly string[], size: number, maxArgs: number): string;
 /**
  * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`. `pathSuffix` appends an accessor per key
- * (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
+ * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`, nested past `maxArgs`. `pathSuffix` appends an
+ * accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
  * `jsonScalarParam` bound to its `QueryContext`.
  */
-export declare function jsonAssignCall(bindValue: (value: unknown) => string, fn: string, target: string, entries: Record<string, unknown>, pathSuffix?: string): string;
+export declare function jsonAssignCall(bindValue: (value: unknown) => string, fn: string, target: string, entries: Record<string, unknown>, maxArgs: number, pathSuffix?: string): string;
 /** The `$set` target: a nullable column needs a `COALESCE` fallback to build on. */
 export declare function jsonSetTarget(expr: string, field: FieldOptions | undefined, empty: string): string;
 /**
  * `FN(expr, path, ...)` - the multi-path JSON removal shape shared by MySQL's `JSON_REMOVE` and
- * SQLite's `json_remove`, both of which take every path in a single call.
+ * SQLite's `json_remove`, nested past `maxArgs`.
  */
-export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[]): string;
+export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[], maxArgs: number): string;
 /** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
 export declare function jsonElemExists(from: string, conditions: readonly string[]): string;
 /**

package/dist/dialect/jsonSql.js

@@ -9,15 +9,32 @@ export function jsonPath(path, suffix = '') {
     const segments = path.split('.').map(escapeSingleQuotes).join('.');
     return `'$.${segments}${suffix}'`;
 }
+/** How many argument groups of `size` fit in one call beside its target, under `maxArgs`. */
+export function groupsPerCall(maxArgs, size) {
+    return Math.max(1, Math.floor((maxArgs - 1) / size));
+}
+/**
+ * `fn(target, ...groups)`, nested wherever one call would take more than `maxArgs` arguments: each call
+ * applies its share to what the call inside it returned, as `JSON_SET`, `JSON_REMOVE` and `json_insert`
+ * do. A group, such as a path and its value, stays in one call.
+ */
+export function chainedCall(fn, target, groups, size, maxArgs) {
+    const perCall = groupsPerCall(maxArgs, size);
+    let call = target;
+    for (let at = 0; at < groups.length; at += perCall) {
+        call = `${fn}(${call}, ${groups.slice(at, at + perCall).join(', ')})`;
+    }
+    return call;
+}
 /**
  * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`. `pathSuffix` appends an accessor per key
- * (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
+ * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`, nested past `maxArgs`. `pathSuffix` appends an
+ * accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
  * `jsonScalarParam` bound to its `QueryContext`.
  */
-export function jsonAssignCall(bindValue, fn, target, entries, pathSuffix = '') {
+export function jsonAssignCall(bindValue, fn, target, entries, maxArgs, pathSuffix = '') {
     const pairs = Object.entries(entries).map(([key, value]) => `${jsonPath(key, pathSuffix)}, ${bindValue(value)}`);
-    return `${fn}(${target}, ${pairs.join(', ')})`;
+    return chainedCall(fn, target, pairs, 2, maxArgs);
 }
 /** The `$set` target: a nullable column needs a `COALESCE` fallback to build on. */
 export function jsonSetTarget(expr, field, empty) {
@@ -25,10 +42,10 @@ export function jsonSetTarget(expr, field, empty) {
 }
 /**
  * `FN(expr, path, ...)` - the multi-path JSON removal shape shared by MySQL's `JSON_REMOVE` and
- * SQLite's `json_remove`, both of which take every path in a single call.
+ * SQLite's `json_remove`, nested past `maxArgs`.
  */
-export function jsonRemoveCall(fn, expr, keys) {
-    return `${fn}(${expr}, ${keys.map((key) => jsonPath(key)).join(', ')})`;
+export function jsonRemoveCall(fn, expr, keys, maxArgs) {
+    return chainedCall(fn, expr, keys.map((key) => jsonPath(key)), 1, maxArgs);
 }
 /** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
 export function jsonElemExists(from, conditions) {

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,5 +1,5 @@
-import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, QueryConflictPaths, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
-import { AbstractSqlDialect } from './abstractSqlDialect.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
+import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from './abstractSqlDialect.js';
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
  *
@@ -64,11 +64,39 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      */
     protected readonly upsertNewRowAlias: string | undefined;
     readonly maxBindValues: number;
+    /**
+     * An ordered `GROUP_CONCAT` of each row's object, which reads as a JSON array: MySQL's `JSON_ARRAYAGG`
+     * takes no `ORDER BY`, and as a window over the rows it rebuilds the array for every one of them.
+     */
+    protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
+    /** A read's statement, with the settings it needs applied to it alone. */
+    find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    /** A `$distinct` read's count, which reads the relations the read does. */
+    countDistinct<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
+    private settled;
+    /**
+     * `name=value` for each variable a read's statement sets for itself alone. `GROUP_CONCAT`, and
+     * MariaDB's `JSON_ARRAYAGG` built on it, cut a relation's array at `group_concat_max_len`.
+     */
+    protected statementSettings<E>(entity: Type<E>, q: Query<E>): string[];
+    /** `sql` with `settings` scoped to it, in this engine's spelling. */
+    protected abstract applySettings(sql: string, settings: readonly string[]): string;
+    /** `JSON_OBJECT` of each key and its value. */
+    protected jsonObject(pairs: DerivedRelation['pairs']): string;
+    /**
+     * A number and bytes cross JSON as text, where JSON would round the one and spell the other as base64,
+     * and a vector as the engine reads one back: text on MariaDB, which stores it packed.
+     */
+    protected readonly carriedFields: {
+        numeric: (expr: string) => string;
+        blob: (expr: string) => string;
+        vector: (expr: string, field: FieldOptions) => string;
+    };
     escape(value: unknown): string;
     /**
      * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
      * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
-     * `@Index([...], { type: 'fulltext' })`.
+     * `@Index((post) => [...], { type: 'fulltext' })`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
     protected numericCast(expr: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,10 +1,15 @@
 import { getMeta } from '../entity/index.js';
 import { textSearchFields } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
-import { AbstractSqlDialect } from './abstractSqlDialect.js';
+import { AbstractSqlDialect, } from './abstractSqlDialect.js';
 import { COUNT_ALIAS, JSON_PULL_ALIAS } from './aliases.js';
+import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
-/** The row count MySQL's manual gives for "all rows from the offset on": the largest `BIGINT UNSIGNED`. */
+import { aggregatesRelations } from './queryJoins.js';
+/**
+ * The largest `BIGINT UNSIGNED`: the row count MySQL's manual gives for "all rows from the offset on",
+ * and the largest `group_concat_max_len` either engine takes.
+ */
 const MAX_LIMIT = BigInt.asUintN(64, -1n);
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
@@ -126,13 +131,60 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      */
     upsertNewRowAlias = undefined;
     maxBindValues = 65535;
+    /**
+     * An ordered `GROUP_CONCAT` of each row's object, which reads as a JSON array: MySQL's `JSON_ARRAYAGG`
+     * takes no `ORDER BY`, and as a window over the rows it rebuilds the array for every one of them.
+     */
+    appendRelationArray(ctx, rows) {
+        const { from, pairs, order } = this.derivedRelation(ctx, rows);
+        const objects = `${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''} SEPARATOR ','`;
+        ctx.append(`(SELECT COALESCE(CONCAT('[', GROUP_CONCAT(${objects}), ']'), '[]') FROM ${from})`);
+    }
+    /** A read's statement, with the settings it needs applied to it alone. */
+    find(ctx, entity, q = {}, opts, totalAlias) {
+        this.settled(ctx, entity, q, (statement) => super.find(statement, entity, q, opts, totalAlias));
+    }
+    /** A `$distinct` read's count, which reads the relations the read does. */
+    countDistinct(ctx, entity, q, opts) {
+        this.settled(ctx, entity, q, (statement) => super.countDistinct(statement, entity, q, opts));
+    }
+    settled(ctx, entity, q, build) {
+        const settings = this.statementSettings(entity, q);
+        if (!settings.length) {
+            build(ctx);
+            return;
+        }
+        const statement = ctx.createFragment();
+        build(statement);
+        ctx.append(this.applySettings(statement.sql, settings));
+    }
+    /**
+     * `name=value` for each variable a read's statement sets for itself alone. `GROUP_CONCAT`, and
+     * MariaDB's `JSON_ARRAYAGG` built on it, cut a relation's array at `group_concat_max_len`.
+     */
+    statementSettings(entity, q) {
+        return aggregatesRelations(getMeta(entity), q) ? [`group_concat_max_len=${MAX_LIMIT}`] : [];
+    }
+    /** `JSON_OBJECT` of each key and its value. */
+    jsonObject(pairs) {
+        return `JSON_OBJECT(${this.jsonObjectArgs(pairs)})`;
+    }
+    /**
+     * A number and bytes cross JSON as text, where JSON would round the one and spell the other as base64,
+     * and a vector as the engine reads one back: text on MariaDB, which stores it packed.
+     */
+    carriedFields = {
+        numeric: (expr) => `CAST(${expr} AS CHAR)`,
+        blob: (expr) => `CONCAT(${this.escape(BYTES_PREFIX)}, HEX(${expr}))`,
+        vector: (expr, field) => this.selectFieldExpr(expr, field),
+    };
     escape(value) {
         return escapeMysqlSqlLiteral(value);
     }
     /**
      * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
      * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
-     * `@Index([...], { type: 'fulltext' })`.
+     * `@Index((post) => [...], { type: 'fulltext' })`.
      */
     appendTextSearch(ctx, _entity, meta, search) {
         const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
@@ -169,7 +221,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * applicable: it requires the target column as the direct `JSON_SET` input.
      */
     jsonSet(ctx, expr, set, field) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', jsonSetTarget(expr, field, `'{}'`), set);
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', jsonSetTarget(expr, field, `'{}'`), set, this.maxFunctionArgs);
     }
     /**
      * `JSON_MERGE_PRESERVE` concatenates arrays and creates absent keys, so every pushed key is
@@ -181,7 +233,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         return `JSON_MERGE_PRESERVE(${expr}, JSON_OBJECT(${entries.join(', ')}))`;
     }
     jsonUnset(_ctx, expr, unset) {
-        return jsonRemoveCall('JSON_REMOVE', expr, unset);
+        return jsonRemoveCall('JSON_REMOVE', expr, unset, this.maxFunctionArgs);
     }
     /**
      * MySQL's `->`/`->>` take a full JSON path (`'$.a.b'`, never a bare key) and only apply to a

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,6 +1,5 @@
-import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type Type, type VectorDistance, type VectorOperatorMetric } from '../type/index.js';
-import { type ParentPartition } from '../util/relationQuery.util.js';
-import { AbstractSqlDialect } from './abstractSqlDialect.js';
+import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type Type } from '../type/index.js';
+import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
  * CockroachDB (wire- and SQL-compatible for everything below, including `TO_TSVECTOR`/`TO_TSQUERY`
@@ -23,28 +22,29 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly alterColumnStrategy = "separate-clauses";
     /**
-     * One `LATERAL` branch correlated against an array of the parent keys, in place of the base
-     * `UNION ALL` of a subquery per parent. Same rows and the same `parents x (skip + limit)` read, but
-     * the planner sees one correlated index loop rather than N branches to plan: flat in page size where
-     * `UNION ALL` is linear, and the statement's text stops changing with the number of parents, so one
-     * prepared statement serves every page.
-     *
-     * Postgres, CockroachDB, PGlite, Neon and bun-sql inherit it together. **MySQL has `LATERAL` and must
-     * not use it** - it does not plan this as a correlated index loop and measured slower than both its
-     * own `UNION ALL` and a query per parent, which is why this is an override rather than a capability
-     * flag. [The design](../../../../architecture/populate-limits.md).
+     * `JSON_AGG` of each row whole, read through a LATERAL projection of the columns it answers under:
+     * the sort terms carried out beside them order it without joining the object, and no function call
+     * builds it, so a wide row meets no argument limit. `json` has no equality, so under a parent's
+     * `DISTINCT` the array is compared as `jsonb`.
      */
-    protected appendPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, { joins, parents, parentFields }: ParentPartition): void;
+    protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
+    /**
+     * What JSON would round or cannot spell crosses it as text, for the field's own decode to read back:
+     * a column declared numeric, whatever it decodes as, a vector, and bytes as hex.
+     */
+    protected readonly carriedFields: {
+        numeric: (expr: string) => string;
+        vector: (expr: string) => string;
+        blob: (expr: string) => string;
+    };
     /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
     protected readonly upsertUpdateBindsInPlace = true;
     readonly insertIdSource = "returning";
     readonly maxBindValues: number;
-    /**
-     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
-     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
-     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
-     */
-    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorOperatorMetric>;
+    readonly vectorMetrics: ReadonlyMap<import("../type/vector.js").VectorDistance, {
+        readonly op: string;
+        readonly opsSuffix: string;
+    }>;
     /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
     readonly vectorTuningNeedsTransaction = true;
     /**

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,12 +1,11 @@
-import { canonicalToSql, fieldOptionsToCanonical } from '../schema/canonicalType.js';
 import { QueryRaw, } from '../type/index.js';
 import { hasVectorNear, textSearchFields } from '../util/dialect.util.js';
-import { raw } from '../util/raw.js';
-import { queryNarrowedTo } from '../util/relationQuery.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
-import { JSON_PULL_ALIAS, PER_PARENT_BRANCH_ALIAS, PER_PARENT_KEYS_ALIAS } from './aliases.js';
+import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
+import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonSetTarget } from './jsonSql.js';
+import { PG_VECTOR_METRICS } from './pgVectorMetrics.js';
 import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -52,56 +51,32 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     rollbackTransactionCommand = 'ROLLBACK';
     alterColumnStrategy = 'separate-clauses';
     /**
-     * One `LATERAL` branch correlated against an array of the parent keys, in place of the base
-     * `UNION ALL` of a subquery per parent. Same rows and the same `parents x (skip + limit)` read, but
-     * the planner sees one correlated index loop rather than N branches to plan: flat in page size where
-     * `UNION ALL` is linear, and the statement's text stops changing with the number of parents, so one
-     * prepared statement serves every page.
-     *
-     * Postgres, CockroachDB, PGlite, Neon and bun-sql inherit it together. **MySQL has `LATERAL` and must
-     * not use it** - it does not plan this as a correlated index loop and measured slower than both its
-     * own `UNION ALL` and a query per parent, which is why this is an override rather than a capability
-     * flag. [The design](../../../../architecture/populate-limits.md).
+     * `JSON_AGG` of each row whole, read through a LATERAL projection of the columns it answers under:
+     * the sort terms carried out beside them order it without joining the object, and no function call
+     * builds it, so a wide row meets no argument limit. `json` has no equality, so under a parent's
+     * `DISTINCT` the array is compared as `jsonb`.
      */
-    appendPerParent(ctx, entity, q, { joins, parents, parentFields }) {
-        const keys = this.escapeId(ctx.nextAlias(PER_PARENT_KEYS_ALIAS));
-        const branch = this.escapeId(ctx.nextAlias(PER_PARENT_BRANCH_ALIAS));
-        const column = (index) => `${keys}.k${index}`;
-        // `UNNEST` resolves an uncast parameter to `unknown` and refuses it ("function unnest(unknown) is
-        // not unique"), so the array says its type. It comes from the parent's key column, which always
-        // declares one, rather than the child's foreign key, which would have to be resolved through the
-        // reference it takes its own type from.
-        const sources = joins.map(({ parent }) => {
-            const field = parentFields[parent];
-            if (!field) {
-                throw new TypeError(`cannot page a relation per parent: '${parent}' is not a field of the parent entity`);
-            }
-            const values = parents.map((it) => it[parent]);
-            return `${this.addValue(ctx.values, values)}::${canonicalToSql(fieldOptionsToCanonical(field), this)}[]`;
-        });
-        const rowSource = `UNNEST(${sources.join(', ')}) AS ${keys}(${joins.map((_, index) => `k${index}`).join(', ')})`;
-        // The keys come from the row source rather than as values, which is the whole point of correlating:
-        // one branch, planned once, instead of one per parent.
-        const correlated = Object.fromEntries(joins.map(({ joined }, index) => [joined, raw(({ ctx: inner }) => inner.append(column(index)))]));
-        ctx.append(`SELECT ${branch}.* FROM ${rowSource} JOIN LATERAL (`);
-        this.find(ctx, entity, queryNarrowedTo(q, correlated));
-        ctx.append(`) ${branch} ON TRUE`);
+    appendRelationArray(ctx, rows) {
+        const { from, pairs, order } = this.derivedRelation(ctx, rows);
+        const row = this.escapeId(RELATION_ROW_ALIAS, true);
+        const columns = pairs.map(([, column]) => column).join(', ');
+        const array = /*sql*/ `(SELECT COALESCE(JSON_AGG(${row}${order ? ` ORDER BY ${order}` : ''}), '[]'::json) FROM ${from} CROSS JOIN LATERAL (SELECT ${columns}) ${row})`;
+        ctx.append(rows.distinct ? `${array}::jsonb` : array);
     }
+    /**
+     * What JSON would round or cannot spell crosses it as text, for the field's own decode to read back:
+     * a column declared numeric, whatever it decodes as, a vector, and bytes as hex.
+     */
+    carriedFields = {
+        numeric: (expr) => `${expr}::text`,
+        vector: (expr) => `${expr}::text`,
+        blob: (expr) => `${this.escape(BYTES_PREFIX)} || ENCODE(${expr}, 'hex')`,
+    };
     /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
     upsertUpdateBindsInPlace = true;
     insertIdSource = 'returning';
     maxBindValues = 65535;
-    /**
-     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
-     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
-     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
-     */
-    vectorMetrics = new Map([
-        ['cosine', { op: '<=>', opsSuffix: 'cosine' }],
-        ['l2', { op: '<->', opsSuffix: 'l2' }],
-        ['inner', { op: '<#>', opsSuffix: 'ip' }],
-        ['l1', { op: '<+>', opsSuffix: 'l1' }],
-    ]);
+    vectorMetrics = PG_VECTOR_METRICS;
     /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
     vectorTuningNeedsTransaction = true;
     /**

package/dist/dialect/pgVectorMetrics.d.ts

@@ -0,0 +1,13 @@
+import type { VectorDistance, VectorOperatorMetric } from '../type/index.js';
+/**
+ * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one list
+ * so a dialect cannot have the operator but not the opclass. Its own module because the two ends live
+ * apart: the operator on the dialect, the opclass in the migrator's index DDL.
+ */
+export declare const PG_VECTOR_METRICS: ReadonlyMap<VectorDistance, VectorOperatorMetric>;
+/**
+ * CockroachDB's three: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
+ * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
+ * Re-check that issue before adding `l1`; it is omitted on purpose.
+ */
+export declare const COCKROACH_VECTOR_METRICS: ReadonlyMap<VectorDistance, VectorOperatorMetric>;

package/dist/dialect/pgVectorMetrics.js

@@ -0,0 +1,17 @@
+/**
+ * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one list
+ * so a dialect cannot have the operator but not the opclass. Its own module because the two ends live
+ * apart: the operator on the dialect, the opclass in the migrator's index DDL.
+ */
+export const PG_VECTOR_METRICS = new Map([
+    ['cosine', { op: '<=>', opsSuffix: 'cosine' }],
+    ['l2', { op: '<->', opsSuffix: 'l2' }],
+    ['inner', { op: '<#>', opsSuffix: 'ip' }],
+    ['l1', { op: '<+>', opsSuffix: 'l1' }],
+]);
+/**
+ * CockroachDB's three: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
+ * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
+ * Re-check that issue before adding `l1`; it is omitted on purpose.
+ */
+export const COCKROACH_VECTOR_METRICS = new Map([...PG_VECTOR_METRICS].filter(([metric]) => metric !== 'l1'));

package/dist/dialect/queryContext.d.ts

@@ -11,14 +11,14 @@ export declare class SqlQueryContext implements QueryContext {
     private readonly statement?;
     private readonly sqlChunks;
     private readonly params;
-    private aliasCounter;
+    private readonly tableAliases;
     /**
      * @param dialect The SQL dialect used to determine how values should be formatted as placeholders.
      * @param params An existing values array to bind into instead of a fresh one - shared by a
      * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
      * placeholder is numbered correctly against the real query from the moment it's added, rather
      * than needing to be reconciled after the fact.
-     * @param statement The context this one renders a fragment of, which owns the alias counter: a
+     * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
      * fragment is part of one statement, so its aliases have to be unique across the whole of it.
      */
     constructor(dialect: QueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined);
@@ -46,11 +46,7 @@ export declare class SqlQueryContext implements QueryContext {
      * @returns The current context instance for method chaining.
      */
     pushValue(...values: unknown[]): this;
-    /**
-     * A fresh alias unique within the statement being built, e.g. `nextAlias('_uql_elem')` ->
-     * `'_uql_elem_1'`, `'_uql_elem_2'`, ...
-     */
-    nextAlias(prefix: string): string;
+    claimAlias(name: string, parent?: string): string;
     /**
      * Returns the complete SQL query string by joining all accumulated chunks.
      */

package/dist/dialect/queryContext.js

@@ -10,14 +10,14 @@ export class SqlQueryContext {
     statement;
     sqlChunks = [];
     params;
-    aliasCounter = 0;
+    tableAliases = new Set();
     /**
      * @param dialect The SQL dialect used to determine how values should be formatted as placeholders.
      * @param params An existing values array to bind into instead of a fresh one - shared by a
      * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
      * placeholder is numbered correctly against the real query from the moment it's added, rather
      * than needing to be reconciled after the fact.
-     * @param statement The context this one renders a fragment of, which owns the alias counter: a
+     * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
      * fragment is part of one statement, so its aliases have to be unique across the whole of it.
      */
     constructor(dialect, params = [], statement) {
@@ -62,12 +62,17 @@ export class SqlQueryContext {
         this.params.push(...values.map((v) => this.dialect.normalizeValue(v)));
         return this;
     }
-    /**
-     * A fresh alias unique within the statement being built, e.g. `nextAlias('_uql_elem')` ->
-     * `'_uql_elem_1'`, `'_uql_elem_2'`, ...
-     */
-    nextAlias(prefix) {
-        return this.statement ? this.statement.nextAlias(prefix) : `${prefix}_${++this.aliasCounter}`;
+    claimAlias(name, parent) {
+        if (this.statement) {
+            return this.statement.claimAlias(name, parent);
+        }
+        const reserved = parent?.toLowerCase();
+        let alias = name;
+        for (let n = 2; this.tableAliases.has(alias.toLowerCase()) || alias.toLowerCase() === reserved; n++) {
+            alias = `${name}_${n}`;
+        }
+        this.tableAliases.add(alias.toLowerCase());
+        return alias;
     }
     /**
      * Returns the complete SQL query string by joining all accumulated chunks.