uql-orm 0.56.0 → 0.58.0

package/dist/type/entity.d.ts

@@ -172,10 +172,10 @@ export type EntityData<E> = Pick<E, FieldKey<E> | RelationKey<E>>;
  * accept `QueryRaw` or `JsonUpdateOp` (for JSON fields), which gives IDE autocomplete for
  * `$set`/`$push`/`$pull` keys via `Json<infer T>`.
  */
-export type UpdatePayload<E> = {
-    [K in FieldKey<E>]?: UpdateFieldValue<E[K]>;
+export type UpdatePayload<E, F extends keyof E = FieldKey<E>, R extends keyof E = RelationKey<E>> = {
+    [K in F]?: UpdateFieldValue<E[K]>;
 } & {
-    [K in RelationKey<E>]?: E[K];
+    [K in R]?: E[K];
 };
 /**
  * Infers the field values of an entity
@@ -212,9 +212,7 @@ export type IdKey<E> = ([NamedIdKey<E>] extends [never] ? FieldKey<E> : NamedIdK
  */
 export type IdValue<E> = E[IdKey<E>];
 /** Every column of a key, which is how a composite row is named and what a `$where` reduces to. */
-type IdMap<E> = {
-    [K in IdKey<E>]?: E[K];
-};
+type IdMap<E> = Partial<Pick<E, IdKey<E>>>;
 /**
  * How a row is addressed by its primary key: the value for a single key, an object carrying every
  * key for a composite - which is also the `$where` map it reduces to, so both spellings are one type.
@@ -425,7 +423,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;
     /**
@@ -477,17 +476,25 @@ export type FieldOptionsFor<V> = (FieldOptions<NonNullable<V>> & {
  * The entity a relation field points at: `Company` for both `company?: Company` and
  * `companies?: Company[]`.
  */
-export type RelationTarget<V> = NonNullable<Unpacked<NonNullable<V>>>;
+export type RelationTarget<V> = Extract<Unpacked<V>, object>;
 /**
  * {@link RelationOptions} for a relation field declared as `V`, with `entity` required and pinned to
  * `V`'s own type, and the cardinality restricted to the ones that field shape can hold. Together those
  * reject `@ManyToOne({ entity: () => Other })` on a `Company` field, and any to-many cardinality on a
- * field that is not an array. An array field additionally needs a {@link RelationJoin}.
+ * field that is not an array. A to-many additionally needs a {@link RelationJoin}.
+ *
+ * The join is required through the `cardinality` written rather than through `IsMany<V>`: a conditional
+ * member of the intersection leaves a `mappedBy` callback without a contextual type inside a generic
+ * call (`defineEntity`), where a union keyed on a property does not.
  */
-export type RelationOptionsFor<V> = Omit<RelationOptions<RelationTarget<V>>, 'entity' | 'cardinality'> & {
+export type RelationOptionsFor<V, O = unknown> = Omit<RelationOptions<RelationTarget<V>, O>, 'entity' | 'cardinality'> & {
     readonly entity: EntityGetter<RelationTarget<V>>;
     readonly cardinality: IsMany<V> extends true ? '1m' | 'mm' : '11' | 'm1';
-} & (IsMany<V> extends true ? RelationJoin<RelationTarget<V>> : unknown);
+} & (({
+    readonly cardinality: '1m' | 'mm';
+} & RelationJoin<RelationTarget<V>, O>) | {
+    readonly cardinality: '11' | 'm1';
+});
 /**
  * The method names of an entity, so hook registrations name a method that exists.
  */
@@ -503,9 +510,13 @@ export type MethodKey<E> = {
  * entity graph almost always has. Nothing about the standard decorator spec changes that; it only removed
  * the reflected `design:type` that used to make `entity` optional.
  */
-export type EntityGetter<E = any> = () => Type<E>;
+export type EntityGetter<E = object> = () => Type<E>;
 export type CascadeType = 'persist' | 'delete';
-export type RelationOptions<E = any> = {
+/**
+ * `E` is the relation's target and `O` the entity declaring it, whose fields `references` names on its
+ * `local` side; the relation decorators infer `O` from the class they sit on.
+ */
+export type RelationOptions<E, O = unknown> = {
     entity: EntityGetter<E>;
     cardinality: RelationCardinality;
     readonly cascade?: boolean | CascadeType;
@@ -518,13 +529,24 @@ export type RelationOptions<E = any> = {
      */
     readonly onDelete?: ForeignKeyAction;
     readonly onUpdate?: ForeignKeyAction;
-    mappedBy?: RelationMappedBy<E>;
+    /** The inverse side: the member of the target holding the foreign key or the owning relation, `(post) => post.author`. */
+    mappedBy?: (keys: KeyMap<E>) => Key<E>;
     /**
      * The pivot entity of a many-to-many. Unconstrained by `E`: a pivot holds foreign keys to both
      * sides and is not a relation value of the target, so nothing about it is derivable from `E`.
      */
     through?: EntityGetter;
-    references?: RelationReferences;
+    /**
+     * The join columns where no convention fits: each pairs a field of the declaring entity with one of
+     * the target, `(order, customer) => [{ local: order.customerCode, foreign: customer.code }]`. A
+     * `through` relation takes none: its junction's columns follow the convention.
+     */
+    references?: (local: KeyMap<O>, foreign: KeyMap<E>) => readonly RelationReference<O, E>[];
+};
+/** One pair of join columns, each a field read off its entity's key map. */
+export type RelationReference<O, E> = {
+    readonly local: FieldKey<O>;
+    readonly foreign: FieldKey<E>;
 };
 /**
  * A relation once `getMeta` has resolved it: `references` is filled in and `mappedBy` is the key its
@@ -537,46 +559,48 @@ export type RelationOptions<E = any> = {
  * from "declared, but an inverse side too, so neither owns the foreign key" needs the unresolved shape
  * still there to find. A phase-split metadata map costs more than the call parentheses it saves.
  */
-export type RelationMeta<E = any> = Omit<RelationOptions<E>, 'mappedBy' | 'references'> & {
-    mappedBy?: Key<E>;
+export type RelationMeta = RelationRegistration & {
     references: RelationReferences;
 };
-/** How a to-many owner reaches its children: a junction entity, or the join columns by name. */
-type RelationOwnerJoin<E> = Required<Pick<RelationOptions<E>, 'through'>> | Required<Pick<RelationOptions<E>, 'references'>>;
+/**
+ * A relation as the registry takes it, whichever entity it targets: `mappedBy` and `references` read
+ * off their key maps down to the names they give, `references` unset until `getMeta` settles it.
+ */
+export type RelationRegistration = Omit<RelationOptions<object>, 'mappedBy' | 'references'> & {
+    mappedBy?: string;
+    references?: RelationReferences;
+};
+/** How a to-many owner reaches its children: a junction entity or the join columns, never both. */
+type RelationOwnerJoin<E, O> = (Required<Pick<RelationOptions<E, O>, 'through'>> & {
+    readonly references?: never;
+}) | (Required<Pick<RelationOptions<E, O>, 'references'>> & {
+    readonly through?: never;
+});
 /**
  * Every way a to-many can say where its rows are. Required because nothing about the field implies it:
  * without one of the three, resolution has no columns to join on and throws.
  */
-type RelationJoin<E> = RelationOwnerJoin<E> | Required<Pick<RelationOptions<E>, 'mappedBy'>>;
-type RelationOptionsOwner<E> = Pick<RelationOptions<E>, 'entity' | 'references' | 'cascade' | 'onDelete' | 'onUpdate'>;
+type RelationJoin<E, O> = RelationOwnerJoin<E, O> | Required<Pick<RelationOptions<E>, 'mappedBy'>>;
+type RelationOptionsOwner<E, O> = Pick<RelationOptions<E, O>, 'entity' | 'references' | 'cascade' | 'onDelete' | 'onUpdate'>;
 type RelationOptionsInverseSide<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & Required<Pick<RelationOptions<E>, 'mappedBy'>>;
-type RelationOptionsThroughOwner<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & RelationOwnerJoin<E>;
+type RelationOptionsThroughOwner<E, O> = Pick<RelationOptions<E, O>, 'entity' | 'cascade'> & RelationOwnerJoin<E, O>;
 /**
- * The key names of `E` as values, so `mappedBy` can be written as `(user) => user.company` instead of
- * a string literal and survive a rename.
- *
- * Mapping over `Key<E>` rather than `keyof E` is what makes the callback usable: a homomorphic
- * `[K in keyof E]` inherits the entity's optional modifiers, so `user.company` is
- * `'company' | undefined` and {@link RelationKeyMapper} rejects it - every callback needed a `!`.
- *
- * At runtime a callback only ever reads one property off the map, so a single `Proxy` returning its
- * own key stands in for every entity's: see `RELATION_KEY_MAP`. A key that names neither a field nor
- * a relation of the target is rejected when the entity resolves.
+ * The key names of `E` as values, so a definition reads a member off it - `(post) => post.author` -
+ * and follows a rename. Homomorphic in `E`, which is what keeps that link, and `-?` so an optional
+ * member still names itself. At runtime one `Proxy` answering its own key serves every entity.
  */
-export type RelationKeyMap<E> = {
-    readonly [K in Key<E>]: K;
+export type KeyMap<E> = {
+    readonly [K in keyof E]-?: K;
 };
-export type RelationKeyMapper<E> = (keyMap: RelationKeyMap<E>) => Key<E>;
 export type RelationReferences = {
     readonly local: string;
     readonly foreign: string;
 }[];
-export type RelationMappedBy<E> = Key<E> | RelationKeyMapper<E>;
 export type RelationCardinality = '11' | 'm1' | '1m' | 'mm';
-export type RelationOneToOneOptions<E> = RelationOptionsOwner<E> | RelationOptionsInverseSide<E>;
-export type RelationOneToManyOptions<E> = RelationOptionsInverseSide<E> | RelationOptionsThroughOwner<E>;
-export type RelationManyToOneOptions<E> = RelationOptionsOwner<E>;
-export type RelationManyToManyOptions<E> = RelationOptionsThroughOwner<E> | RelationOptionsInverseSide<E>;
+export type RelationOneToOneOptions<E, O = unknown> = RelationOptionsOwner<E, O> | RelationOptionsInverseSide<E>;
+export type RelationOneToManyOptions<E, O = unknown> = RelationOptionsInverseSide<E> | RelationOptionsThroughOwner<E, O>;
+export type RelationManyToOneOptions<E, O = unknown> = RelationOptionsOwner<E, O>;
+export type RelationManyToManyOptions<E, O = unknown> = RelationOptionsThroughOwner<E, O> | RelationOptionsInverseSide<E>;
 /**
  * Lifecycle hook event names.
  */
@@ -613,10 +637,10 @@ export type IndexTypeOptions = {
  *
  * @example
  * ```ts
- * @Index(['tenantId', { column: 'createdAt', order: 'desc' }])   // keyset pagination
- * @Index([raw`lower("email")`], { unique: true })                // case-insensitive uniqueness
- * @Index([{ column: 'body', length: 64 }])                       // MySQL needs a prefix on TEXT
- * @Index(['data'], { type: 'gin' })                              // JSONB containment
+ * @Index((post) => [post.tenantId, { column: post.createdAt, order: 'desc' }]) // keyset pagination
+ * @Index(() => [raw`lower("email")`], { unique: true })                      // case-insensitive uniqueness
+ * @Index((post) => [{ column: post.body, length: 64 }])                       // MySQL needs a prefix on TEXT
+ * @Index((post) => [post.data], { type: 'gin' })                              // JSONB containment
  * ```
  *
  * `C` is the entity's `FieldKey` on the `@Index`/`defineEntity` paths, where the decorated class says
@@ -704,8 +728,8 @@ export type IndexColumnModifiers = {
  *
  * @example
  * ```ts
- * @Index([{ column: 'kind', jsonPath: { path: 'theme.color', type: String } }]) // 'kind.theme.color': 'red'
- * @Index([{ column: 'kind', jsonPath: { path: 'rating', type: Number } }])      // 'kind.rating': { $gte: 4 }
+ * @Index((user) => [{ column: user.kind, jsonPath: { path: 'theme.color', type: String } }]) // 'kind.theme.color': 'red'
+ * @Index((user) => [{ column: user.kind, jsonPath: { path: 'rating', type: Number } }])      // 'kind.rating': { $gte: 4 }
  * ```
  */
 export type IndexJsonPath = {
@@ -724,8 +748,8 @@ export type IndexJsonPath = {
  *
  * @example
  * ```ts
- * @Index([{ column: 'tags', jsonArray: { type: String, length: 64 } }]) // tags: { $all: [...] }
- * @Index([{ column: 'kind', jsonArray: { path: 'ids', type: Number } }]) // 'kind.ids': { $all: [...] }
+ * @Index((user) => [{ column: user.tags, jsonArray: { type: String, length: 64 } }]) // tags: { $all: [...] }
+ * @Index((user) => [{ column: user.kind, jsonArray: { path: 'ids', type: Number } }]) // 'kind.ids': { $all: [...] }
  * ```
  */
 export type IndexJsonArray = {
@@ -741,6 +765,8 @@ type IndexColumnPlainModifiers = Except<IndexColumnModifiers, 'jsonPath' | 'json
 export type IndexColumnOptions<C extends string = string> = IndexColumnPlainModifiers & {
     /** The column to index, or `raw(...)` for an expression. */
     readonly column: C | QueryRaw;
+    readonly jsonPath?: never;
+    readonly jsonArray?: never;
 };
 /**
  * One index entry, normalized: {@link IndexColumnInput}'s three authored shapes all reduce to this
@@ -829,9 +855,21 @@ export type CheckOptions = {
  */
 export type EntityMembers = {
     readonly fields?: Readonly<Record<string, FieldOptions | undefined>>;
-    readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
+    readonly relations?: Readonly<Record<string, RelationRegistration | undefined>>;
     readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
 };
+/** An entity's fields as `defineEntity` takes them, keyed like every entity map (see `QuerySelect`). */
+type EntityFieldOptions<E, F extends keyof E = FieldKey<E>> = {
+    readonly [K in F]?: FieldOptionsFor<E[K]>;
+};
+/**
+ * An entity's relations as `defineEntity` takes them. Keyed over every member rather than `RelationKey<E>`:
+ * inside the generic call, only a map over `keyof E` gives a `mappedBy` callback its contextual type. A
+ * field named here still fails, on its options, since its value is no entity.
+ */
+type EntityRelationOptions<E> = {
+    readonly [K in keyof E]?: RelationOptionsFor<E[K], E>;
+};
 /**
  * Configurable options for an entity (`@Entity()` / `defineEntity`).
  *
@@ -848,38 +886,41 @@ export type EntityOptions<E = unknown> = {
     /** Named, default-on `$where` filters (soft-delete is auto-registered from `@Field({ softDelete })`). */
     readonly filters?: Record<string, FilterOptions<E>>;
     /** Scalar fields; use `isId: true` on exactly one field for the primary key. */
-    readonly fields?: {
-        readonly [K in FieldKey<E>]?: FieldOptionsFor<E[K]>;
-    };
-    readonly relations?: {
-        readonly [K in RelationKey<E>]?: RelationOptionsFor<E[K]>;
-    };
-    readonly indexes?: readonly EntityIndexInput<FieldKey<E>, E>[];
+    readonly fields?: EntityFieldOptions<E>;
+    readonly relations?: EntityRelationOptions<E>;
+    readonly indexes?: readonly EntityIndexInput<E>[];
     /** Table-level `CHECK` constraints. See {@link CheckOptions}. */
     readonly checks?: readonly CheckOptions[];
-    /** Map hook events to method names on the entity class. */
-    readonly hooks?: Partial<Record<HookEvent, readonly MethodKey<E>[]>>;
+    /** Each lifecycle event and the methods it runs, read off the key map: `{ beforeInsert: (post) => [post.stamp] }`. */
+    readonly hooks?: Partial<Record<HookEvent, (keys: KeyMap<E>) => readonly MethodKey<E>[]>>;
 };
 /**
- * Everything an index carries beyond its columns, shared by `@Index`, `defineEntity` and the
- * migration builder's `table.index(...)`. `Except` (not plain `Omit`) keeps `type`/`distance` a
- * discriminated pair: omitting `distance` on a vector index type is a compile error.
+ * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,
+ * and through {@link EntityIndexOptions} `@Index` and `defineEntity`. `Except` (not plain `Omit`) keeps
+ * `type`/`distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
  */
-export type IndexOptions<E = unknown> = Except<EntityIndexMeta, 'columns' | 'include' | 'where'> & {
-    /** Non-key columns stored in the index; a typo builds nothing, the server refusing the statement. */
-    readonly include?: readonly IndexFieldKey<E>[];
+export type IndexOptions = Except<EntityIndexMeta, 'columns' | 'include' | 'where'> & {
+    /** Non-key columns stored in the index, by column name; a typo builds nothing, the server refusing it. */
+    readonly include?: readonly string[];
     /**
      * Partial-index predicate. `raw` with no interpolation, like an index expression: this is DDL, so
      * there is no placeholder for a bound value. A bare string is the older spelling and still works.
      */
     readonly where?: string | QueryRaw;
 };
-/** A field of `E`, or any name where there is no entity to check it against - the migration builder. */
-type IndexFieldKey<E> = unknown extends E ? string : FieldKey<E>;
 /**
- * An index as authored, before `defineIndex` normalizes its columns.
+ * {@link IndexOptions} on an entity, whose stored columns are read off its key map, `(post) => [post.slug]`,
+ * so they are checked against it and follow a rename. The migration builder names raw columns instead.
+ */
+export type EntityIndexOptions<E> = Except<IndexOptions, 'include'> & {
+    readonly include?: (keys: KeyMap<E>) => readonly FieldKey<E>[];
+};
+/**
+ * An index as authored on an entity, before `defineIndex` reads its columns off the key map. Only the
+ * member lists are callbacks: TypeScript never checks a callback's returned literal for excess properties,
+ * so the options stay a literal of their own, where `uniqe: true` is a compile error.
  */
-export type EntityIndexInput<C extends string = string, E = unknown> = IndexOptions<E> & {
-    readonly columns: readonly IndexColumnInput<C, E>[];
+export type EntityIndexInput<E> = EntityIndexOptions<E> & {
+    readonly columns: (keys: KeyMap<E>) => readonly IndexColumnInput<FieldKey<E>, E>[];
 };
 export {};

package/dist/type/migration.d.ts

@@ -73,7 +73,7 @@ export interface MigratorOptions {
     /**
      * Entities to use for schema generation
      */
-    readonly entities?: Type<unknown>[];
+    readonly entities?: Type<object>[];
     /**
      * Default action for foreign key ON DELETE and ON UPDATE clauses.
      */
@@ -141,7 +141,7 @@ export interface IndexSchema extends VectorIndexOptions {
     /**
      * What the index is over, in order. Named `entries` and not `columns` because an entry need not be
      * a column at all: ``raw`lower(email)` `` is one, and so is a column carrying a prefix length or a
-     * stored order. The authored form, `@Index([...])`, still spells this `columns`, since that is what
+     * stored order. The authored form, `@Index`, still spells this `columns`, since that is what
      * it reads like at the call site.
      */
     readonly entries: readonly IndexColumnSchema[];
@@ -234,7 +234,7 @@ export interface SyncOptions {
     readonly drop?: boolean;
     readonly logging?: boolean;
     /** One entity instead of every registered one, for a schema that grows while the process runs. */
-    readonly entity?: Type<unknown>;
+    readonly entity?: Type<object>;
     /** Drop every table and recreate it. Development only: it is the one option that loses data. */
     readonly force?: boolean;
 }
@@ -266,13 +266,13 @@ export interface SchemaGenerator {
      * cross-entity foreign key has nothing to resolve against and is dropped: all three call sites that
      * used to work that way emitted schemas with no referential integrity.
      */
-    generateCreateSchema(entities: readonly Type<unknown>[], options?: CreateSchemaOptions): string[];
+    generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
      * Every `DROP TABLE` for `entities`, dependents first. The inverse of {@link generateCreateSchema},
      * and the reason it takes the whole set: dropping in any order that ignores the relation graph is
      * rejected once the foreign keys are really there.
      */
-    generateDropSchema(entities: readonly Type<unknown>[], options?: DropSchemaOptions): string[];
+    generateDropSchema(entities: readonly Type<object>[], options?: DropSchemaOptions): string[];
     /** Generate DROP TABLE statement. */
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
     /**
@@ -303,7 +303,7 @@ export interface SchemaGenerator {
      * reads as missing from both sides, which is a match and no statement. Defaults to this entity
      * alone, which is right only where it has no relations.
      */
-    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
+    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
     /**
      * The entity side as an AST, to hand to every {@link diffSchema} of one run - building it per
      * entity instead is quadratic in the number of entities.
@@ -311,7 +311,7 @@ export interface SchemaGenerator {
      * Optional because not every generator compares one: MongoDB has no foreign keys and diffs only
      * indexes, so it neither implements this nor reads the argument.
      */
-    buildAST?(entities: readonly Type<unknown>[]): SchemaAST;
+    buildAST?(entities: readonly Type<object>[]): SchemaAST;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
      * `SchemaAST` stores it and how a diff finds it again.

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/querierPool.d.ts

@@ -76,9 +76,9 @@ export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDial
 export interface SqlQuerierPool<Q extends SqlQuerier = SqlQuerier, D extends AbstractSqlDialect = AbstractSqlDialect> extends QuerierPool<Q, D>, Pick<SqlQuerier, 'all' | 'run'> {
 }
 /** Dialect class used by pool `P` (when `P` is a {@link QuerierPool}). */
-export type QuerierPoolDialect<P> = P extends QuerierPool<any, infer D> ? D : never;
+export type QuerierPoolDialect<P> = P extends QuerierPool<infer _Q, infer D> ? D : never;
 /** Querier type produced by pool `P`. */
-export type QuerierPoolQuerier<P> = P extends QuerierPool<infer Q, any> ? Q : never;
+export type QuerierPoolQuerier<P> = P extends QuerierPool<infer Q, infer _D> ? Q : never;
 /**
  * Represents a high-compatibility SQL pool shim for Node.js integrations (e.g., express-session).
  */

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,23 +25,13 @@ 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
- * scalars come with it. Relations go in `$populate`.
+ * Field selection - `{ name: true }` whitelists fields; relations go in `$populate`. Declared over
+ * `F extends keyof E`, like every map keyed by an entity's members, so each key stays linked to its
+ * property and an editor rename reaches it. `F` is also how a projection passes its captured key set.
  */
-export type QuerySelect<E> = {
-    [K in FieldKey<E>]?: BooleanLike;
+export type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {
+    [K in F]?: V;
 };
 /**
  * Accepted `$select` value: a field map, or raw SQL projections built with `raw()`
@@ -56,8 +46,8 @@ export type QueryExclude<E> = QuerySelect<E>;
 /**
  * relation population map.
  */
-export type QueryPopulate<E> = {
-    [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
+export type QueryPopulate<E, R extends keyof E = RelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
 };
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
@@ -66,23 +56,20 @@ 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]>>;
+export type QueryCount<E, R extends keyof E = ToManyRelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
 };
 /**
  * query conflict paths - subset of field keys used to detect upsert conflicts.
  */
-export type QueryConflictPaths<E> = {
-    [K in FieldKey<E>]?: true;
-};
+export type QueryConflictPaths<E> = QuerySelect<E, FieldKey<E>, true>;
 /**
  * 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;
 };
 /**
@@ -160,9 +147,11 @@ export type QuerySortByCount = {
  * against an intersection is repeated per constituent, which made this the single most expensive
  * type in the package to check.
  */
-export type QuerySortMap<E, Vector extends boolean = true> = {
-    [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E> ? IsMany<E[K]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
-};
+export type QuerySortMap<E, Vector extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {
+    [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[P]>, false> : Vector extends true ? NonNullable<E[P]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
+} & ([JsonFieldPaths<E>] extends [never] ? unknown : {
+    [P in JsonFieldPaths<E>]?: QuerySortDirection;
+});
 /**
  * pager options.
  */
@@ -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,33 +313,12 @@ 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>> = {
-    $select?: {
-        [K in S]?: V;
-    } | readonly QueryRaw[];
-    $exclude?: {
-        [K in X]?: V;
-    };
-    $populate?: {
-        [K in P]?: QueryPopulate<E>[K];
-    };
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
+    $select?: QuerySelect<E, S, V> | readonly QueryRaw[];
+    $exclude?: QuerySelect<E, X, V>;
+    $populate?: QueryPopulate<E, P>;
+    $count?: QueryCount<E, C & ToManyRelationKey<E>>;
 };
-/**
- * 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 +334,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 +363,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. */