uql-orm 0.57.0 → 0.59.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.
@@ -478,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.
  */
@@ -504,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;
@@ -519,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
@@ -538,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.
  */
@@ -614,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
@@ -705,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 = {
@@ -725,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 = {
@@ -742,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
@@ -830,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`).
  *
@@ -841,6 +878,13 @@ export type EntityMembers = {
  */
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
+    /**
+     * The base to inherit fields, relations, hooks and filters from, for a class that cannot extend one
+     * (minted at runtime, or its base chosen from data): the merge `class Child extends Base` does, with
+     * the class's real base nearer, so it wins. Checked against whatever properties the entity declares,
+     * which a class behind an index signature has none of. See the Inheritance guide.
+     */
+    readonly extends?: string extends keyof E ? Type<object> : Type<Partial<E>>;
     /**
      * The schema (in MySQL terms, database) this table lives in, pinning it whichever pool reads it;
      * unset follows the pool's own. Not in `name`: a dotted `name` is rejected.
@@ -849,38 +893,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/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

@@ -26,12 +26,12 @@ export type QueryOptions = {
     autoPrefix?: 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()`
@@ -46,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
@@ -59,15 +59,13 @@ export declare const COUNT_RESULT_KEY = "_count";
  * 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.
  */
@@ -149,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.
  */
@@ -314,18 +314,10 @@ export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$popula
  * @internal
  */
 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[];
-    $exclude?: {
-        [K in X]?: V;
-    };
-    $populate?: {
-        [K in P]?: QueryPopulate<E>[K];
-    };
-    $count?: {
-        [K in C & keyof QueryCount<E>]?: QueryCount<E>[K];
-    };
+    $select?: QuerySelect<E, S, V> | readonly QueryRaw[];
+    $exclude?: QuerySelect<E, X, V>;
+    $populate?: QueryPopulate<E, P>;
+    $count?: QueryCount<E, C & ToManyRelationKey<E>>;
 };
 /**
  * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.

package/dist/type/queryAggregate.d.ts

@@ -1,9 +1,9 @@
 import type { FieldKey } from './entity.js';
-import type { QueryPager, QuerySortDirection } from './query.js';
+import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
 /**
  * Maps the offending keys to `never`, turning an excess key into a compile error; resolves to
- * `unknown` (an inert intersection member) when there are none. Needed because `$group`/`$agg` are
+ * `unknown` (an inert intersection member) when there are none. Needed because `$group`/`$select` are
  * captured as whole maps, and TypeScript skips excess-property checking on a naked type parameter.
  * A find captures key sets instead, where an unknown key fails the capture's own constraint.
  * @internal
@@ -21,7 +21,7 @@ type GroupedKeys<G> = {
 }[keyof G];
 /**
  * The keys `T` declares by name, or `never` when `T` is only an index signature - which is what an
- * uninferred `$agg` is, and what would otherwise make every key look like a declared alias.
+ * uninferred `$select` is, and what would otherwise make every key look like a declared alias.
  * @internal
  */
 type NamedKeys<T> = string extends keyof T ? never : keyof T;
@@ -57,8 +57,20 @@ export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
     distinct: boolean;
 };
+/**
+ * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
+ * so the chosen key stays linked to `T`'s own property and renames follow it through.
+ */
+type ExactlyOne<T> = {
+    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
+}[keyof T];
+/**
+ * One field named as a key - `{ amount: true }` - the way a statement names every field, so an editor
+ * rename reaches it where a string never would. `F` narrows which fields qualify.
+ */
+export type QueryFieldRef<E, F extends keyof E = FieldKey<E>> = ExactlyOne<Required<QuerySelect<E, F, true>>>;
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
-export type QueryAggregateArg<E> = FieldKey<E> | '*';
+export type QueryAggregateArg<E> = QueryFieldRef<E> | '*';
 /**
  * Fields `SUM`/`AVG` can total. Restricted to numeric columns because the result is declared
  * `number`: totalling a text or date column is either an engine error or a coercion, and neither
@@ -81,21 +93,17 @@ type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
  * Every aggregate op mapped to the argument it accepts: `$count` a field or `'*'` (`COUNT(*)`),
  * the totalling ops a numeric field, `$min`/`$max`/`$countDistinct` any field.
  */
-type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, NumericFieldKey<E>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, FieldKey<E>>;
-/** Exactly one key of `T`: the chosen op with its value; every other op key is forbidden (`never`). */
-type ExactlyOne<T> = {
-    [K in keyof T]: Readonly<Record<K, T[K]>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
-}[keyof T];
+type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
  * An aggregate function applied to a field. Exactly one operation per entry (a second op is a
  * compile error). Only `$count` accepts `'*'` (i.e. `COUNT(*)`); every other op requires a field.
  * DISTINCT variants are flat ops (`$countDistinct`/`$sumDistinct`/`$avgDistinct`) taking a field.
  *
- * @example { $count: '*' }            -> COUNT(*)
- * @example { $countDistinct: 'id' }   -> COUNT(DISTINCT "id")
- * @example { $sum: 'amount' }         -> SUM("amount")
- * @example { $sumDistinct: 'amount' } -> SUM(DISTINCT "amount")
- * @example { $avg: 'age' }            -> AVG("age")
+ * @example { $count: '*' }                    -> COUNT(*)
+ * @example { $countDistinct: { id: true } }   -> COUNT(DISTINCT "id")
+ * @example { $sum: { amount: true } }         -> SUM("amount")
+ * @example { $sumDistinct: { amount: true } } -> SUM(DISTINCT "amount")
+ * @example { $avg: { age: true } }            -> AVG("age")
  */
 export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
 /** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
@@ -109,16 +117,14 @@ type CountingOp = OpsOf<'$count' | '$countDistinct'>;
 /**
  * Group-by columns: an object mapping entity field keys to `true`, exactly like {@link QuerySelect}.
  * Typed against the entity, so a typo'd column is a compile error. Compute aggregate columns with
- * {@link QueryAggMap} (the `$agg` key), not here.
+ * {@link QueryAggMap} (the `$select` key), not here.
  *
  * @example
  * ```ts
  * { status: true } // -> GROUP BY "status"
  * ```
  */
-export type QueryGroupMap<E> = {
-    readonly [K in FieldKey<E>]?: true;
-};
+export type QueryGroupMap<E> = Readonly<QuerySelect<E, FieldKey<E>, true>>;
 /**
  * Computed aggregate columns: an object mapping your chosen output alias to an aggregate function.
  * Alias names are free (you are naming new columns); the aggregated field reference inside each
@@ -126,7 +132,7 @@ export type QueryGroupMap<E> = {
  *
  * @example
  * ```ts
- * { count: { $count: '*' }, avgAge: { $avg: 'age' } }
+ * { count: { $count: '*' }, avgAge: { $avg: { age: true } } }
  * // -> COUNT(*) AS "count", AVG("age") AS "avgAge"
  * ```
  */
@@ -151,7 +157,7 @@ type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number :
     readonly $min: infer F;
 } | {
     readonly $max: infer F;
-} ? FieldValueType<E, F> | null : unknown;
+} ? FieldValueType<E, keyof F> | null : unknown;
 /**
  * Flattens an intersection into a single object literal for readable editor hovers.
  * @internal
@@ -166,9 +172,7 @@ type Simplify<T> = {
  * Grouped columns come from {@link GroupedKeys}, not `keyof G`, so a `$group` the compiler could
  * not read contributes none rather than all of them.
  */
-export type QueryAggregateResult<E, G, A> = Simplify<{
-    -readonly [K in GroupedKeys<G> & FieldKey<E>]: E[K];
-} & {
+export type QueryAggregateResult<E, G, A> = Simplify<Pick<E, GroupedKeys<G> & FieldKey<E>> & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
 /**
@@ -190,7 +194,7 @@ export type QueryHavingMap = {
  * querier.aggregate(User, {
  *   $where: { deletedAt: { $isNull: true } },
  *   $group: { status: true },
- *   $agg: { count: { $count: '*' }, avgAge: { $avg: 'age' } },
+ *   $select: { count: { $count: '*' }, avgAge: { $avg: { age: true } } },
  *   $having: { count: { $gt: 5 } },
  *   $sort: { count: -1 },
  * });
@@ -203,17 +207,22 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
     readonly $where?: QueryWhere<E>;
     /**
      * Columns to group by - `{ status: true }`, typed against the entity like `$select`. A computed
-     * aggregate wrongly placed here (it belongs in `$agg`) is rejected via {@link Reject}, since
-     * `$group` is captured as a generic and a bare generic skips excess-property checking.
+     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link Reject}, since
+     * `$group` is captured as a generic and a bare generic skips excess-property checking. The captured
+     * map meets its schema, {@link QueryGroupMap}, so each key keeps its link to the entity property.
      */
-    readonly $group?: G & Reject<Exclude<keyof G, FieldKey<E>>>;
+    readonly $group?: G & QueryGroupMap<E> & Reject<Exclude<keyof G, FieldKey<E>>>;
     /**
-     * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: 'age' } }`.
+     * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. The
+     * captured map meets its schema over the same aliases, as `$group` does, so field keys stay linked
+     * (a `Record<keyof A, ...>` spelling of the same type breaks the inference of `A`).
      *
      * An alias repeating a `$group` column is rejected: both would be emitted under that one name,
      * leaving the driver to keep whichever it read last.
      */
-    readonly $agg?: A & Reject<NamedKeys<A> & GroupedKeys<G>>;
+    readonly $select?: A & {
+        readonly [K in keyof A]: QueryAggregateFn<E>;
+    } & Reject<NamedKeys<A> & GroupedKeys<G>>;
     /**
      * Post-aggregation filtering, applied after grouping (SQL `HAVING`, MongoDB post-group `$match`).
      * Keyed by the result columns (grouped columns + computed aliases), and each value is typed to that