uql-orm 0.55.0 → 0.57.0

package/dist/schema/schemaASTBuilder.js

@@ -10,6 +10,7 @@ import { ddlText } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
+import { definedEntries } from '../util/object.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
 import { fieldOptionsToCanonical } from './canonicalType.js';
 import { createTableNode, SchemaAST } from './schemaAST.js';
@@ -79,11 +80,7 @@ function addTableFromEntity(ctx, meta) {
     const { columns, primaryKey } = table;
     table.checks?.push(...(meta.checks ?? []));
     // Add columns from fields
-    const fields = meta.fields;
-    for (const key of Object.keys(fields)) {
-        const field = fields[key];
-        if (!field)
-            continue;
+    for (const [key, field] of definedEntries(meta.fields)) {
         // An inlined expression has no column; a stored one is a column like any other.
         if (isInlinedExpression(field))
             continue;
@@ -126,11 +123,7 @@ function addRelationshipsFromEntity(ctx, meta) {
     const table = tableOf(ctx, meta);
     if (!table)
         return;
-    const relations = meta.relations;
-    for (const key of Object.keys(relations)) {
-        const relation = relations[key];
-        if (!relation)
-            continue;
+    for (const [key, relation] of definedEntries(meta.relations)) {
         const relatedMeta = getMeta(relation.entity());
         const relatedTable = tableOf(ctx, relatedMeta);
         if (!relatedTable)
@@ -175,8 +168,8 @@ function addRelationshipsFromEntity(ctx, meta) {
     }
 }
 /**
- * Add indexes from field options (`@Field({ index })`) and from `@Index([...])`, which have nothing
- * in common beyond their target table.
+ * Add indexes from field options (`@Field({ index })`), from `@Index([...])`, and for every foreign
+ * key none of those already serves.
  */
 function addIndexesFromEntity(ctx, meta) {
     const table = tableOf(ctx, meta);
@@ -201,6 +194,35 @@ function addIndexesFromEntity(ctx, meta) {
     for (const idxMeta of meta.indexes ?? []) {
         addCompositeIndex(ctx, table, meta, idxMeta);
     }
+    addForeignKeyIndexes(ctx, meta, table);
+}
+/**
+ * An index over each foreign key the table owns, unless one already leads with its columns or a field
+ * of it says `index: false`. A relation looks its rows up by these columns, and MySQL alone indexes
+ * them on its own. Last, so it sees every index the entity declared.
+ */
+function addForeignKeyIndexes(ctx, meta, table) {
+    const optedOut = new Set(definedEntries(meta.fields).flatMap(([key, field]) => field.index === false ? [ctx.resolveColumnName(key, field)] : []));
+    for (const { from } of table.outgoingRelations) {
+        const columns = from.columns.map((column) => column.name);
+        if (columns.some((column) => optedOut.has(column)) || isIndexedBy(table, columns))
+            continue;
+        ctx.ast.addIndex({
+            name: derivedIndexName(table.name, columns),
+            table,
+            entries: columns.map((column) => ({ column })),
+            unique: false,
+            source: 'entity',
+            syncStatus: 'entity_only',
+        });
+    }
+}
+/** Whether the key, a unique column or an index already leads with `columns`, which is all a lookup needs. */
+function isIndexedBy(table, columns) {
+    const leads = (indexed) => columns.every((column, at) => indexed[at] === column);
+    return (leads(table.primaryKey.map((column) => column.name)) ||
+        (columns.length === 1 && table.columns.get(columns[0])?.isUnique === true) ||
+        table.indexes.some((index) => leads(index.entries.map((entry) => entry.expression || entry.jsonPath || entry.jsonArray ? undefined : entry.column))));
 }
 /** An `include` column is named like any other, so a naming strategy has to reach it too. */
 function resolveIncludeColumn(ctx, meta, column) {

package/dist/schema/schemaASTDiffer.d.ts

@@ -10,7 +10,7 @@
 import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
-import type { RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
+import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
 /**
  * Options for schema diffing.
  */
@@ -59,7 +59,10 @@ export declare function diffSchemas(source: SchemaAST, target: SchemaAST, option
  * against the one the database reported, then projects the result into a `SchemaDiff`. One
  * comparison serves both, so drift and migrations can no longer disagree about what has changed.
  */
-export declare function diffTable(source: TableNode, target: TableNode, options?: DiffOptions): TableDiff | undefined;
+export declare function diffTable(source: TableNode, target: TableNode, options?: DiffOptions): (TableDiff & {
+    readonly columnDiffs: ColumnDiff[];
+    readonly indexDiffs: IndexDiff[];
+}) | undefined;
 /**
  * Compare two lists of relationships.
  *
@@ -70,3 +73,8 @@ export declare function diffTable(source: TableNode, target: TableNode, options?
  * pairing on names would report every hand-named one as a drop and an add.
  */
 export declare function diffRelationshipNodes(source: readonly RelationshipNode[], target: readonly RelationshipNode[], opts?: DiffOptions): RelationshipDiff[];
+/** A relationship's `ON DELETE` and `ON UPDATE`, an unstated one read as the action the database applies. */
+export declare function referentialActions(rel: RelationshipNode): {
+    readonly onDelete: ForeignKeyAction;
+    readonly onUpdate: ForeignKeyAction;
+};

package/dist/schema/schemaASTDiffer.js

@@ -61,8 +61,8 @@ export function diffSchemas(source, target, options = {}) {
     const tablesToAlter = matched
         .map(([sourceTable, targetTable]) => diffTable(sourceTable, targetTable, opts))
         .filter((tableDiff) => tableDiff !== undefined);
-    const columnDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.columnDiffs ?? []);
-    const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs ?? []);
+    const columnDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.columnDiffs);
+    const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs);
     const primaryKeyDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.primaryKeyDiff ?? []);
     // Relationships span tables, so they are compared over the whole schema rather than per table.
     const relationshipDiffs = opts.compareRelationships
@@ -179,7 +179,7 @@ function diffColumn(tableName, source, target, opts) {
     const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
     const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
     if (typeChanged) {
-        differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
+        differences.push(`type: ${formatType(source.type)} -> ${formatType(target.type)}`);
     }
     // Signedness is the one thing compared on a generated key, because it is the one part of the serial
     // spelling that does round trip - and a key left unsigned refuses every foreign key pointing at it,
@@ -187,14 +187,14 @@ function diffColumn(tableName, source, target, opts) {
     // a database created before the serial became signed could never gain a foreign key.
     const signednessChanged = generatedType && !!source.type.unsigned !== !!target.type.unsigned;
     if (signednessChanged) {
-        differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
+        differences.push(`type: ${formatType(source.type)} -> ${formatType(target.type)}`);
     }
     if (!impliedNotNull && source.nullable !== target.nullable) {
-        differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
+        differences.push(`nullable: ${target.nullable} -> ${source.nullable}`);
     }
     // Compare unique constraint
     if (source.isUnique !== target.isUnique) {
-        differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
+        differences.push(`unique: ${target.isUnique} -> ${source.isUnique}`);
     }
     // Four things are deliberately not compared, all for one reason: a difference here could only be
     // reported, never settled, because no statement this generator emits would change it.
@@ -206,7 +206,7 @@ function diffColumn(tableName, source, target, opts) {
     // The same rule `describeIndexDifferences` follows for what it cannot read.
     // Compare default values (if both defined)
     if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
-        differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);
+        differences.push(`default: ${target.defaultValue ?? 'NULL'} -> ${source.defaultValue ?? 'NULL'}`);
     }
     if (differences.length === 0) {
         return undefined;
@@ -265,16 +265,17 @@ export function diffRelationshipNodes(source, target, opts = {}) {
             .filter((diff) => diff !== undefined),
     ];
 }
-/**
- * Compare two relationships.
- */
+/** A relationship's `ON DELETE` and `ON UPDATE`, an unstated one read as the action the database applies. */
+export function referentialActions(rel) {
+    return {
+        onDelete: rel.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION,
+        onUpdate: rel.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION,
+    };
+}
+/** Two relationships over the same columns differ only in what they do when the row they point at goes. */
 function diffRelationship(source, target) {
-    // Compare on delete/update actions (normalizing defaults)
-    const sDelete = source.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
-    const tDelete = target.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
-    const sUpdate = source.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
-    const tUpdate = target.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
-    if (sDelete !== tDelete || sUpdate !== tUpdate) {
+    const [expected, actual] = [referentialActions(source), referentialActions(target)];
+    if (expected.onDelete !== actual.onDelete || expected.onUpdate !== actual.onUpdate) {
         return { ...relationEnds(source), type: 'alter', expected: source, actual: target };
     }
     return undefined;

package/dist/schema/types.d.ts

@@ -342,7 +342,7 @@ export type DriftSeverity = 'critical' | 'warning' | 'info';
 /**
  * Type of schema drift.
  */
-export type DriftType = 'missing_table' | 'unexpected_table' | 'missing_column' | 'unexpected_column' | 'type_mismatch' | 'constraint_mismatch' | 'missing_index' | 'unexpected_index' | 'index_mismatch' | 'missing_relationship' | 'unexpected_relationship';
+export type DriftType = 'missing_table' | 'unexpected_table' | 'missing_column' | 'unexpected_column' | 'type_mismatch' | 'constraint_mismatch' | 'missing_index' | 'unexpected_index' | 'index_mismatch' | 'missing_relationship' | 'unexpected_relationship' | 'relationship_mismatch';
 /**
  * A single schema drift issue.
  */

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,4 +1,4 @@
-import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
+import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
@@ -16,6 +16,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
     readonly supportsRowLocks = false;
     readonly booleanLiteral = "integer";
+    /** A function call takes 127 arguments before SQLite 3.48, as libSQL and Turso embed. */
+    readonly maxFunctionArgs: number;
     readonly insertIdSource = "returning";
     /**
      * The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
@@ -36,6 +38,23 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * SQLite's own spelling of "no limit", where the MySQL family uses its largest `BIGINT`.
      */
     pager(ctx: QueryContext, opts: QueryPager): void;
+    /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
+    protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
+    /**
+     * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
+     * addressing each key as one path segment.
+     */
+    protected jsonObject(pairs: DerivedRelation['pairs']): string;
+    /**
+     * An integer crosses JSON as its exact text, which JSON would round past 2^53, and bytes as hex, which
+     * `json_object` cannot hold at all. A real stays a number, since SQLite writes one to text with 15 digits.
+     */
+    protected readonly carriedFields: {
+        numeric: (expr: string, field: FieldOptions) => string;
+        blob: (expr: string) => string;
+    };
+    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
+    protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
      * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).

package/dist/sqlite/sqliteDialect.js

@@ -1,6 +1,9 @@
-import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS } from '../dialect/aliases.js';
-import { jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget } from '../dialect/jsonSql.js';
+import { AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
+import { JSON_ELEM_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
+import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
+import { chainedCall, groupsPerCall, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
+import { textSearchFields } from '../util/dialect.util.js';
+import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 export class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     featureDefaults = {
@@ -36,6 +39,8 @@ export class SqliteDialect extends AbstractSqlDialect {
     /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
     supportsRowLocks = false;
     booleanLiteral = 'integer';
+    /** A function call takes 127 arguments before SQLite 3.48, as libSQL and Turso embed. */
+    maxFunctionArgs = 127;
     // SQLite supports `RETURNING` (including on `INSERT ... ON CONFLICT`), so IDs are exact per row.
     insertIdSource = 'returning';
     /**
@@ -81,12 +86,39 @@ export class SqliteDialect extends AbstractSqlDialect {
         }
         super.pager(ctx, opts);
     }
+    /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
+    appendRelationArray(ctx, rows) {
+        const { from, pairs, order } = this.derivedRelation(ctx, rows);
+        ctx.append(`(SELECT json_group_array(${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''}) FROM ${from})`);
+    }
+    /**
+     * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
+     * addressing each key as one path segment.
+     */
+    jsonObject(pairs) {
+        const perCall = groupsPerCall(this.maxFunctionArgs, 2);
+        const object = `json_object(${this.jsonObjectArgs(pairs.slice(0, perCall))})`;
+        const inserts = pairs.slice(perCall).map(([key, sql]) => `${this.escape(`$."${key}"`)}, ${sql}`);
+        return chainedCall('json_insert', object, inserts, 2, this.maxFunctionArgs);
+    }
+    /**
+     * An integer crosses JSON as its exact text, which JSON would round past 2^53, and bytes as hex, which
+     * `json_object` cannot hold at all. A real stays a number, since SQLite writes one to text with 15 digits.
+     */
+    carriedFields = {
+        numeric: (expr, field) => (isIntegerColumn(field) ? `CAST(${expr} AS TEXT)` : expr),
+        blob: (expr) => `${this.escape(BYTES_PREFIX)} || hex(${expr})`,
+    };
+    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
+    hydrateKind(field) {
+        return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
+    }
     /**
      * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).
      */
     appendTextSearch(ctx, entity, meta, search) {
-        const columns = search.$fields.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
         ctx.append(`${this.escapedTableName(meta)} MATCH {${columns.join(' ')}} : `);
         ctx.addValue(search.$value);
     }
@@ -103,7 +135,7 @@ export class SqliteDialect extends AbstractSqlDialect {
      * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
      */
     jsonAll(ctx, jsonField, value) {
-        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
         const from = this.jsonElemFrom(jsonField, [], alias);
         const conditions = value.map((val) => jsonElemExists(from, [`${jsonField} -> ${alias}.fullkey = ${this.jsonScalarParam(ctx, val)}`]));
         return `(${conditions.join(' AND ')})`;
@@ -142,7 +174,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         return `JSON_REPLACE(${expr}, ${path}, (${kept}))`;
     }
     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);
     }
     /**
      * `[#]` appends, creating the array when the key is absent.
@@ -152,9 +184,9 @@ export class SqliteDialect extends AbstractSqlDialect {
      * so it silently drops the element when the array already exists.
      */
     jsonPush(ctx, expr, push) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', expr, push, '[#]');
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', expr, push, this.maxFunctionArgs, '[#]');
     }
     jsonUnset(_ctx, expr, unset) {
-        return jsonRemoveCall('JSON_REMOVE', expr, unset);
+        return jsonRemoveCall('JSON_REMOVE', expr, unset, this.maxFunctionArgs);
     }
 }

package/dist/turso/tursoDialect.d.ts

@@ -12,4 +12,6 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
 export declare class TursoDialect extends LibsqlDialect {
     /** The Rust engine adds a dot-product distance to libSQL's cosine and L2. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
+    protected readonly orderedAggregates = false;
 }

package/dist/turso/tursoDialect.js

@@ -15,4 +15,6 @@ export class TursoDialect extends LibsqlDialect {
         ['l2', { fn: 'vector_distance_l2' }],
         ['inner', { fn: 'vector_distance_dot' }],
     ]);
+    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
+    orderedAggregates = false;
 }

package/dist/type/config.d.ts

@@ -1,5 +1,5 @@
-import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { ForeignKeyAction } from '../schema/types.js';
+import type { MigratorDialect } from './migratorDialect.js';
 import type { Querier } from './querier.js';
 import type { QuerierPool } from './querierPool.js';
 import type { Type } from './utility.js';
@@ -12,7 +12,7 @@ export interface Config {
      * This is required for both the application and the migrations CLI.
      * Must expose {@link QuerierPool.dialect}; migrations and the CLI read `pool.dialect.dialectName`.
      */
-    pool: QuerierPool<Querier, AbstractDialect>;
+    pool: QuerierPool<Querier, MigratorDialect>;
     /**
      * List of entity classes to be managed by the ORM.
      * If omitted, classes that completed `defineEntity` (including via `@Entity()`) are discovered via `getEntities()`.

package/dist/type/dialect.d.ts

@@ -33,12 +33,11 @@ export interface QueryContext {
     addValue(value: unknown): this;
     pushValue(...values: unknown[]): this;
     /**
-     * A fresh derived-table/subquery alias, unique within this query: `nextAlias('_uql_elem')` returns
-     * `'_uql_elem_1'`, then `'_uql_elem_2'`, etc. Needed wherever a hook (e.g. exploding a JSON array)
-     * might recurse into itself at a deeper nesting level within the same query - a fixed, reused
-     * alias would let the inner occurrence shadow the outer one it needs to correlate against.
+     * An alias for a table or row source the statement reads: `name`, or `name_2`, `name_3`... - the
+     * first no other took, so a nested one never shadows what it correlates against, and never `parent`,
+     * the one a correlated subquery compares against. Compared without case, as MySQL does on macOS.
      */
-    nextAlias(prefix: string): string;
+    claimAlias(name: string, parent?: string): string;
     /**
      * A context for a fragment of this same statement: it renders its own SQL in isolation while
      * sharing the bound values and the generated aliases, so both stay unique and correctly numbered

package/dist/type/entity.d.ts

@@ -425,7 +425,8 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      */
     readonly autoIncrement?: boolean;
     /**
-     * Index configuration. true for simple index, string for named index.
+     * `true` for an index over the column, a string to name it. A foreign key column is indexed unless
+     * this is `false`.
      */
     readonly index?: boolean | string;
     /**

package/dist/type/migratorDialect.d.ts

@@ -1,4 +1,8 @@
+import type { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
+import type { MongoDialect } from '../mongo/mongoDialect.js';
 import type { DialectName } from './querier.js';
+/** The dialects the migrator runs on, which `dialectName` tells apart: every SQL engine, and MongoDB. */
+export type MigratorDialect = AbstractSqlDialect | MongoDialect;
 declare const KNOWN_MIGRATOR_DIALECTS: readonly ["postgres", "cockroachdb", "mysql", "mariadb", "sqlite", "mssql", "mongodb"];
 export type KnownMigratorDialect = (typeof KNOWN_MIGRATOR_DIALECTS)[number];
 /**

package/dist/type/querier.d.ts

@@ -4,7 +4,7 @@ import type { SqlDialectName } from './dialect.js';
 import type { FieldKey, HookEvent, RelationKey } from './entity.js';
 import type { LoggingOptions } from './logger.js';
 import type { NamingStrategy } from './namingStrategy.js';
-import type { QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
+import type { QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpdateResult } from './query.js';
 import type { UniversalQuerier } from './universalQuerier.js';
 import type { Type } from './utility.js';
 /**
@@ -47,13 +47,13 @@ export interface Querier extends UniversalQuerier {
     }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     /**
-     * Stream records as an async iterable. Supports both patterns.
-     * Does not fill relations or fire lifecycle hooks.
+     * Stream records as an async iterable, in both patterns, each with the relations and counts
+     * `findMany` reads. Fires no lifecycle hooks.
      */
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryStreamProjected<E, S, V, X, P> & {
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
-    }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
+    }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     /**
      * Find many records and count. Supports both patterns.
      */

package/dist/type/query.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, IdKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
+import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -25,16 +25,6 @@ export type QueryOptions = {
      */
     autoPrefix?: boolean;
 };
-export type QuerySelectOptions = {
-    /**
-     * prefix the query with this.
-     */
-    prefix?: string;
-    /**
-     * automatically add the prefix for the alias.
-     */
-    autoPrefixAlias?: boolean;
-};
 /**
  * Query field selection - `{ name: true }` whitelists specific fields. Fields only: a relation is a
  * sub-query rather than a projection flag, and a whitelist naming one could not say whether the
@@ -66,9 +56,8 @@ export type QueryPopulate<E> = {
 export declare const COUNT_RESULT_KEY = "_count";
 /**
  * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
- * which ones count. One statement per relation named here, batched over every parent at once, so it
- * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
- * a relation of the same name that `$populate` filled with rows.
+ * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes
+ * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.
  */
 export type QueryCount<E> = {
     [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
@@ -82,7 +71,7 @@ export type QueryConflictPaths<E> = {
 /**
  * Options to populate a relation declared as `V`, by its cardinality.
  */
-export type QueryPopulateRelationOptions<V> = (IsMany<V> extends true ? Except<Query<RelationTarget<V>>, '$lock'> : QueryUnique<RelationTarget<V>>) & {
+export type QueryPopulateRelationOptions<V> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>> : QueryUnique<RelationTarget<V>> & {
     $required?: boolean;
 };
 /**
@@ -276,14 +265,13 @@ export type Query<E> = {
  * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
  * rather than the runtime if a clause is ever renamed.
  *
- * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's
- * query accepts, so leaving it out is what excludes it from both.
+ * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
+ * accepts it.
  */
 export declare const QUERY_OBJECT_CLAUSES: readonly ["$select", "$populate", "$exclude", "$where", "$sort"];
 /**
- * Object clauses only the statement itself takes, never a relation's own query - the mirror of
- * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a
- * populated relation's rows are assembled after that, so there is nothing for a nested one to count.
+ * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
+ * so a `$count` inside one would have no `_count` to land in.
  */
 export declare const QUERY_ROOT_OBJECT_CLAUSES: readonly ["$count"];
 export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
@@ -294,6 +282,16 @@ export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
  */
 export declare const QUERY_ROOT_NUMBER_CLAUSES: readonly ["$candidates"];
 export declare const QUERY_BOOLEAN_CLAUSES: readonly ["$distinct"];
+/** The clauses that describe the statement, which a populated relation's own query refuses by name. */
+export declare const QUERY_STATEMENT_CLAUSES: readonly ["$lock", "$count", "$candidates"];
+type RelationClause = (typeof QUERY_OBJECT_CLAUSES | typeof QUERY_NUMBER_CLAUSES | typeof QUERY_BOOLEAN_CLAUSES)[number];
+/**
+ * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot
+ * drift, and a clause added to {@link Query} stays off it until it joins one of them.
+ */
+export type RelationQuery<E = object> = Pick<Query<E>, RelationClause> & {
+    $required?: boolean;
+};
 /**
  * options to get a single record.
  */
@@ -315,18 +313,7 @@ export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$popula
  * populated relation's own query - stays the concrete {@link Query} it is today.
  * @internal
  */
-type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = QueryStreamProjection<E, S, V, X, P> & {
-    $count?: {
-        [K in C & keyof QueryCount<E>]?: QueryCount<E>[K];
-    };
-};
-/**
- * {@link QueryProjection} without `$count`, which a stream cannot honor. Split out rather than
- * subtracted afterwards: an optional key is a *known* key even when its value maps over `never`, so
- * a statement that must not take the clause has to be built without it in the first place.
- * @internal
- */
-type QueryStreamProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = {
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
     $select?: {
         [K in S]?: V;
     } | readonly QueryRaw[];
@@ -336,12 +323,10 @@ type QueryStreamProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P
     $populate?: {
         [K in P]?: QueryPopulate<E>[K];
     };
+    $count?: {
+        [K in C & keyof QueryCount<E>]?: QueryCount<E>[K];
+    };
 };
-/**
- * A {@link QueryProjected} a stream can honor: no `$count`, which is batched over a result set a
- * stream never holds all of.
- */
-export type QueryStreamProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = Except<Query<E>, '$count'> & QueryStreamProjection<E, S, V, X, P>;
 /**
  * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
@@ -357,15 +342,7 @@ export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>
  * why `$exclude` is only read on the branch where there is none.
  * @internal
  */
-type ProjectedKeys<E, S, V, X, P, C> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P | ([P | C] extends [never] ? never : NamedIdKey<E>);
-/**
- * The id key when it can be named, and nothing when it cannot: {@link IdKey} widens to *every* field
- * for an entity whose id is neither branded nor called `id`/`_id`/`uuid`, and adding that back would
- * hand the caller a row claiming fields the query never fetched. Missing an id costs a `$select`
- * entry; promising absent fields is the bug this type exists to prevent.
- * @internal
- */
-type NamedIdKey<E> = [FieldKey<E>] extends [IdKey<E>] ? never : IdKey<E>;
+type ProjectedKeys<E, S, V, X, P> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P;
 /**
  * Whether every entry of the captured map says the same thing: all selected, or all subtracted.
  * @internal
@@ -394,8 +371,8 @@ type CountedRelations<C extends PropertyKey> = [C] extends [never] ? unknown : {
     };
 };
 /** @internal */
-type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? Pick<E, ProjectedKeys<E, S, V, X, P, C> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
-Pick<E, Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> & keyof E> & {
+type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? Pick<E, ProjectedKeys<E, S, V, X, P> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
+Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E> & {
     [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;
 } : E;
 /** The to-many relations a query populated, which come back as lists rather than as optional ones. */

package/dist/type/query.js

@@ -9,8 +9,8 @@ export const COUNT_RESULT_KEY = '_count';
  * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
  * rather than the runtime if a clause is ever renamed.
  *
- * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's
- * query accepts, so leaving it out is what excludes it from both.
+ * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
+ * accepts it.
  */
 export const QUERY_OBJECT_CLAUSES = [
     '$select',
@@ -20,9 +20,8 @@ export const QUERY_OBJECT_CLAUSES = [
     '$sort',
 ];
 /**
- * Object clauses only the statement itself takes, never a relation's own query - the mirror of
- * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a
- * populated relation's rows are assembled after that, so there is nothing for a nested one to count.
+ * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
+ * so a `$count` inside one would have no `_count` to land in.
  */
 export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
@@ -33,3 +32,9 @@ export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
  */
 export const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];
+/** The clauses that describe the statement, which a populated relation's own query refuses by name. */
+export const QUERY_STATEMENT_CLAUSES = [
+    '$lock',
+    ...QUERY_ROOT_OBJECT_CLAUSES,
+    ...QUERY_ROOT_NUMBER_CLAUSES,
+];