objection 4.0.0-rc.2 → 4.0.0-rc.3

package/typings/objection/index.d.ts

@@ -18,7 +18,8 @@ import { Knex } from 'knex';
 // Only the declarations marked with `export` are exported.
 export {};
 
-// Phantom brand of the relation types, used by `TypedRelationMappings`.
+// Phantom brand of the relation types, used by `TypedRelationMappings` and
+// `FromModel`.
 declare const relationKind: unique symbol;
 // Phantom brand of `Generated` properties.
 declare const generated: unique symbol;
@@ -197,7 +198,7 @@ export interface CallbackVoid<T> {
 }
 
 export type Identity<T> = (value: T) => T;
-export type AnyQueryBuilder = QueryBuilder<any, any>;
+export type AnyQueryBuilder = QueryBuilder<any, any, any>;
 export type AnyModelConstructor = ModelConstructor<Model>;
 export type ModifierFunction<QB extends AnyQueryBuilder> = (qb: QB, ...args: any[]) => void;
 export type Modifier<QB extends AnyQueryBuilder = AnyQueryBuilder> =
@@ -398,7 +399,7 @@ export type WithGraphTreeQueryBuilder<QB extends AnyQueryBuilder, T> = [keyof T]
         ? QB
         : WithResultKind<
             QB,
-            WithGraph<ModelType<QB>, T>['QueryBuilderType'],
+            KeepExtra<WithGraph<ModelType<QB>, T>['QueryBuilderType'], ExtraType<QB>>,
             ModelType<QB>,
             ResultType<QB>,
             T
@@ -477,8 +478,9 @@ export type NonFunctionPropertyNames<T> = {
   [K in keyof T]: T[K] extends Function ? never : K;
 }[keyof T];
 
-// The type-only members of models, which aren't data.
-type ModelTypeMembers = 'QueryBuilderType' | 'ColumnNameMapping';
+// The type-only members of models, which aren't data, also the keys of the
+// virtual attributes that `FromModel` adds.
+type ModelTypeMembers = 'QueryBuilderType' | 'ColumnNameMapping' | `~virtual:${string}`;
 
 /**
  * Type that attempts to only select the user-defined model properties.
@@ -501,15 +503,24 @@ export type ModelObject<T extends Model> = Pick<T, DataPropertyNames<T>>;
 
 /**
  * The JSON of model M, as `toJSON()` returns it: its properties without
- * methods, and the related models as JSON too. Values aren't converted, e.g.
- * dates stay dates.
+ * methods, the results of the methods in `virtualAttributes` on models with
+ * `FromModel`, and the related models as JSON too. Values aren't converted,
+ * e.g. dates stay dates.
  */
 export type ModelJson<M> = {
-  [K in keyof Pick<M, DataPropertyNames<M> & keyof M>]: K extends RelationPropertyNames<M>
+  [
+    K in keyof Pick<M, (DataPropertyNames<M> | VirtualAttributeNames<M>) & keyof M>
+  ]: K extends RelationPropertyNames<M>
     ? RelationJson<M[K]>
-    : M[K];
+    : M[K] extends (...args: any) => infer R
+      ? RelationJson<R>
+      : M[K];
 };
 
+type VirtualAttributeNames<M> = {
+  [K in keyof M]: K extends `~virtual:${infer N}` ? N : never;
+}[keyof M];
+
 type RelationJson<P> = P extends (infer I)[]
   ? ModelJson<I>[]
   : P extends readonly (infer I)[]
@@ -728,16 +739,34 @@ export type ModelType<T extends { ModelType: any }> = T['ModelType'];
 export type ResultType<T extends { ResultType: any }> = T['ResultType'];
 
 /**
- * Re-instantiates the query builder QB with the model type M and the result
- * type R, through its `RebindType`. The `~rebind` slot is `unknown`, so the
- * intersection resolves it to exactly `[M, R]`. Rebinding QB's own
- * `RebindType` instead of QB keeps the intersection small, which TypeScript
- * checks much faster.
+ * Re-instantiates the query builder QB with the model type M, the result
+ * type R and the extra type X, through its `RebindType`. The `~rebind` slot is
+ * `unknown`, so the intersection resolves it to exactly `[M, R, X]`.
+ * Rebinding QB's own `RebindType` instead of QB keeps the intersection small,
+ * which TypeScript checks much faster.
  */
-type Rebind<QB extends AnyQueryBuilder, M extends Model, R> = (QB['RebindType'] & {
-  '~rebind': [M, R];
+type Rebind<
+  QB extends AnyQueryBuilder,
+  M extends Model,
+  R,
+  X = IfStrict<unknown, ExtraType<QB>>,
+> = (QB['RebindType'] & {
+  '~rebind': [M, R, X];
 })['RebindType'];
 
+/**
+ * Gets the extra type from a query builder type: what the types know about
+ * the query beyond its model and result, see `QueryExtra`.
+ */
+export type ExtraType<T extends { ExtraType: any }> = T['ExtraType'];
+
+type WithExtra<QB extends AnyQueryBuilder, X> = Rebind<QB, ModelType<QB>, ResultType<QB>, X>;
+
+// The narrowed query builders of `withGraph*()` start without the extra type
+// of QB, so it is passed on, if there is one.
+type KeepExtra<NQB extends AnyQueryBuilder, X> =
+  X extends QueryExtra<any, any, any> ? WithExtra<NQB, X> : NQB;
+
 /**
  * Gets the single item query builder type for a query builder.
  */
@@ -763,18 +792,18 @@ export type NumberQueryBuilder<QB extends AnyQueryBuilder> = QB['~number'];
  */
 export type PageQueryBuilder<QB extends AnyQueryBuilder> = QB['~page'];
 
-// Strict mode, on by default, checks the column names and values of queries
-// against the models. Augment `TypeConfig` to opt out:
+// Strict mode checks the column names and values of queries against the
+// models. Augment `TypeConfig` to opt in:
 //
 //   declare module 'objection' {
 //     interface TypeConfig {
-//       strict: false;
+//       strict: true;
 //     }
 //   }
 
 export interface TypeConfig {}
 
-type IsStrict = TypeConfig extends { strict: false } ? false : true;
+type IsStrict = TypeConfig extends { strict: true } ? true : false;
 
 // As IsStrict isn't generic, IfStrict resolves eagerly.
 type IfStrict<Loose, Strict> = IsStrict extends true ? Strict : Loose;
@@ -1159,6 +1188,18 @@ export type SelectedBrand<A> = { readonly [selected]: A };
  */
 export type ExtractedBrand<A> = { readonly [extracted]: A };
 
+/**
+ * The extra type of queries in strict mode: the model class C that started the
+ * query, e.g. with `Person.query()`, and the modifiers P registered with
+ * `modifiers()`, to check the names of modifiers, and the id I of the class,
+ * for `findById()` and the other `*ById()` methods.
+ */
+export interface QueryExtra<C = unknown, P = unknown, I = MaybeCompositeId> {
+  modelClass: C;
+  registered: P;
+  id: I;
+}
+
 // The results whose rows have `jsonExtract()` values, which `withGraph*()`
 // keeps instead of converting the result kind:
 type ExtractedRows =
@@ -1276,17 +1317,222 @@ type UnknownRelations<M, T> = {
 
 /**
  * In strict mode, relation expressions are intersected with this, to reject
- * the names of unknown relations.
+ * the names of unknown relations, and of unknown modifiers, checked against
+ * the related class of each node and the modifiers registered on query
+ * builder QB.
  */
-type CheckRelationExpression<M, E> = IfStrict<
+type CheckRelationExpression<M, E, QB extends AnyQueryBuilder = never> = IfStrict<
   unknown,
   IsConcreteModel<M> extends true
     ? [UnknownRelations<M, ParseRelationExpression<E>>] extends [never]
-      ? unknown
+      ? CheckModifierExpression<E, QB>
       : { '~unknownRelation': UnknownRelations<M, ParseRelationExpression<E>> }
     : unknown
 >;
 
+type CheckModifierExpression<E, QB extends AnyQueryBuilder> =
+  HasQueryClass<QB> extends true
+    ? [CheckedModifiers<E, QB>] extends [never]
+      ? unknown
+      : { '~unknownModifier': CheckedModifiers<E, QB> }
+    : unknown;
+
+// Queries in generic code, where the model class can't be resolved, aren't
+// checked.
+type HasQueryClass<QB extends AnyQueryBuilder> =
+  IsConcreteModel<ModelType<QB>> extends false
+    ? false
+    : [QueryClass<QB>] extends [never]
+      ? false
+      : true;
+
+// Only expressions with modifiers are checked for them.
+type CheckedModifiers<E, QB> = E extends `${string}(${string}` | object
+  ? UnknownModifiers<
+      ClassMappings<QueryClass<QB>>,
+      ParseModifierExpression<E>,
+      keyof RegisteredModifiers<QB>
+    >
+  : never;
+
+/**
+ * The modifiers that a modifier name can refer to on query builder QB: the
+ * `modifiers` of the model class that started the query, and those registered
+ * with `modifiers()` before. Unknown names are only rejected in strict mode,
+ * and only on queries of model classes with literal `modifiers`.
+ */
+type KnownModifiers<QB> = ClassModifiers<QueryClass<QB>> & RegisteredModifiers<QB>;
+
+// The model class that started the query, if any.
+type QueryClass<QB> = [QB] extends [never]
+  ? never
+  : QB extends { ExtraType: QueryExtra<infer C, any, any> }
+    ? unknown extends C
+      ? never
+      : C
+    : never;
+
+type ClassModifiers<C> = C extends { modifiers: infer O } ? O : {};
+
+type ClassMappings<C> = C extends { relationMappings: infer T }
+  ? T extends () => infer R
+    ? R
+    : T
+  : {};
+
+type RegisteredModifiers<QB> = [QB] extends [never]
+  ? {}
+  : QB extends { ExtraType: { registered: infer P } }
+    ? P
+    : {};
+
+/**
+ * The id that `findById()` and the other `*ById()` methods take on query
+ * builder QB: in strict mode, the type of the property of the class's literal
+ * `idColumn`, or a tuple of them for composite ids, e.g. with
+ * `static idColumn = ['groupId', 'memberId'] as const`.
+ */
+type IdArg<QB extends AnyQueryBuilder> = IfStrict<
+  MaybeCompositeId,
+  [QueryClass<QB>] extends [never]
+    ? MaybeCompositeId
+    : QB extends { ExtraType: QueryExtra<any, any, infer I> }
+      ? I
+      : MaybeCompositeId
+>;
+
+// The id of a related class, read from its instances.
+type ClassId<C> = C extends { idColumn: infer K; prototype: infer M }
+  ? ColumnsId<K, M>
+  : MaybeCompositeId;
+
+// The inherited `idColumn` and other general types give any id.
+type ColumnsId<K, M> = [K] extends [string]
+  ? string extends K
+    ? MaybeCompositeId
+    : PropertyId<M, K, MaybeCompositeId>
+  : [K] extends [readonly string[]]
+    ? string extends K[number]
+      ? MaybeCompositeId
+      : { readonly [I in keyof K]: PropertyId<M, K[I] & string, Id> }
+    : MaybeCompositeId;
+
+// The id column is a database column, named after the property by the
+// model's `ColumnNameMapping`. Columns without a property give the fallback F.
+type PropertyId<M, C extends string, F> =
+  ResultKey<M, C> extends infer P extends keyof M ? NonNullable<M[P]> : F;
+
+// Modifiers with their general type, e.g. inherited from `Model`, aren't
+// checked.
+type ChecksModifiers<QB extends AnyQueryBuilder> = IfStrict<
+  false,
+  HasQueryClass<QB> extends true ? ChecksClassModifiers<ClassModifiers<QueryClass<QB>>> : false
+>;
+
+type ChecksClassModifiers<O> = string extends keyof O ? false : true;
+
+// The names that `modify()` takes on query builder QB, also in lists. Names
+// in variables typed `string` are rejected where they are checked.
+type ModifierName<QB extends AnyQueryBuilder> =
+  ChecksModifiers<QB> extends true ? keyof KnownModifiers<QB> & string : string;
+
+type ModifyArg<QB extends AnyQueryBuilder> =
+  | ModifierName<QB>
+  | ModifierName<QB>[]
+  | ModifierFunction<QB>
+  | Record<string, Expression<PrimitiveValue>>;
+
+// The related classes are found through the relation mappings, at each step
+// of the path. P are the names registered with `modifiers()`.
+type UnknownModifiers<Mappings, T, P> = T extends unknown
+  ? {
+      [K in keyof T & string]: T[K] extends { names: infer N; children: infer Children }
+        ? MappedClass<Mappings, K> extends infer C
+          ? [C] extends [never]
+            ? never
+            : | (ChecksClassModifiers<ClassModifiers<C>> extends true
+                  ? Exclude<N, keyof ClassModifiers<C> | P>
+                  : never)
+              | UnknownModifiers<ClassMappings<C>, Children, P>
+          : never
+        : never;
+    }[keyof T & string]
+  : never;
+
+// Mappings with their general type, e.g. inherited from `Model`, give no class.
+type MappedClass<Mappings, K> = string extends keyof Mappings
+  ? never
+  : K extends keyof Mappings
+    ? Mappings[K] extends { modelClass: infer C }
+      ? C extends abstract new (...args: any) => any
+        ? C
+        : C extends () => infer RC
+          ? RC
+          : never
+      : never
+    : never;
+
+/**
+ * Parses the modifiers of relation expressions into a tree of the relations
+ * with their modifier names: 'pets(a, b).owner' ->
+ * `{ pets: { names: 'a' | 'b', children: { owner: ... } } }`. It is separate
+ * from `ParseRelationExpression`, so that the narrowing types don't carry the
+ * names.
+ */
+type ParseModifierExpression<E> = string extends E
+  ? {}
+  : E extends string
+    ? ParseModifierString<E>
+    : ParseModifierObject<E>;
+
+// A union of the trees of the list items, as they can name the same relation.
+type ParseModifierList<L extends string[], Acc = never> = L extends [
+  infer H extends string,
+  ...infer T extends string[],
+]
+  ? ParseModifierList<T, Acc | ParseModifierString<H>>
+  : Acc;
+
+type ParseModifierString<S extends string> =
+  Trim<S> extends `[${infer Inner}]`
+    ? ParseModifierList<SplitList<Inner>>
+    : Trim<S> extends `${infer Head}.${infer Rest}`
+      ? IsBalanced<Head> extends true
+        ? ModifierNode<Head, ParseModifierString<Rest>>
+        : {}
+      : ModifierNode<S, {}>;
+
+type ModifierNode<S extends string, Children> = [RelationName<S>] extends [never]
+  ? {}
+  : { [K in RelationName<S>]: { names: ModifierNames<S>; children: Children } };
+
+// Empty arguments, e.g. of 'pets()' or a trailing comma, are no names.
+type ModifierNames<S extends string> =
+  Trim<S> extends `${string}(${infer Args})` ? Exclude<Trim<SplitList<Args>[number]>, ''> : never;
+
+type ParseModifierObject<E> = string extends keyof E
+  ? {}
+  : {
+      [
+        K in keyof E as K extends `$${string}`
+          ? never
+          : false extends E[K]
+            ? never
+            : E[K] extends { $relation: any }
+              ? never
+              : K
+      ]: {
+        names: E[K] extends { $modify: infer N }
+          ? N extends readonly (infer I extends string)[]
+            ? I
+            : N extends string
+              ? N
+              : never
+          : never;
+        children: E[K] extends object ? ParseModifierObject<E[K]> : {};
+      };
+    };
+
 export interface ForClassMethod {
   <M extends Model>(modelClass: ModelConstructor<M>): QueryBuilderType<M>;
 }
@@ -1664,7 +1910,7 @@ export interface JoinRelatedOptions {
 
 export interface JoinRelatedMethod<out QB extends AnyQueryBuilder> {
   <QBP extends QB, const E extends RelationExpression<ModelType<QBP>> = never>(
-    expr: E & CheckRelationExpression<ModelType<QBP>, E>,
+    expr: E & CheckRelationExpression<ModelType<QBP>, E, QBP>,
     opt?: JoinRelatedOptions,
   ): QB;
 }
@@ -2033,11 +2279,24 @@ export interface ClearContextMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface ModifyMethod<out QB extends AnyQueryBuilder> {
-  (modifier: Modifier<QB> | Modifier<QB>[], ...args: any[]): QB;
+  (modifier: ModifyArg<QB> | ModifyArg<QB>[], ...args: any[]): QB;
 }
 
-export interface ModifiersMethod<out QB extends AnyQueryBuilder> {
-  (modifiers: Modifiers): QB;
+// Registered modifiers add up, on queries with and without a model class.
+type RegisterModifiers<X, O> =
+  X extends QueryExtra<infer C, infer P, infer I>
+    ? QueryExtra<C, P & O, I>
+    : QueryExtra<unknown, O>;
+
+export interface ModifiersMethod<
+  out QB extends AnyQueryBuilder,
+  M extends Model = ModelType<QB>,
+  R = ResultType<QB>,
+  X = ExtraType<QB>,
+> {
+  <const O extends Modifiers>(
+    modifiers: O,
+  ): IfStrict<QB, Rebind<QB, M, R, RegisterModifiers<X, O>>>;
   (): QB;
 }
 
@@ -2051,7 +2310,11 @@ export interface CatchablePromiseLike<R> extends PromiseLike<R> {
   ): Promise<R | FR>;
 }
 
-export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseLike<R> {
+export class QueryBuilder<
+  M extends Model,
+  R = M[],
+  X = unknown,
+> implements CatchablePromiseLike<R> {
   static forClass: ForClassMethod;
 
   constructor(modelClass: ModelConstructor<M>);
@@ -2240,35 +2503,35 @@ export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseL
   groupBy: GroupByMethod<this>;
   groupByRaw: RawInterface<this>;
 
-  findById(id: MaybeCompositeId): MaybeSingleQueryBuilder<this>;
-  findByIds(ids: MaybeCompositeId[]): this;
+  findById(id: IdArg<this>): MaybeSingleQueryBuilder<this>;
+  findByIds(ids: IdArg<this>[]): this;
   findOne: WhereMethod<MaybeSingleQueryBuilder<this>>;
 
   execute(): Promise<R>;
   castTo<MC extends Model>(modelClass: ModelConstructor<MC>): QueryBuilderType<MC>;
-  castTo<R>(): QueryBuilder<M, R>;
+  castTo<R>(): QueryBuilder<M, R, X>;
 
   update(update: PartialModelRow<M>): NumberQueryBuilder<this>;
   update(): NumberQueryBuilder<this>;
   updateById(
-    id: MaybeCompositeId,
+    id: IdArg<this>,
     update: PartialModelRow<M>,
   ): NumberQueryBuilder<MaybeSingleQueryBuilder<this>>;
   updateAndFetch(update: PartialModelRow<M>): SingleQueryBuilder<this>;
-  updateAndFetchById(id: MaybeCompositeId, update: PartialModelRow<M>): SingleQueryBuilder<this>;
+  updateAndFetchById(id: IdArg<this>, update: PartialModelRow<M>): SingleQueryBuilder<this>;
 
   patch(update: PartialModelPatch<M>): NumberQueryBuilder<this>;
   patch(): NumberQueryBuilder<this>;
   patchById(
-    id: MaybeCompositeId,
+    id: IdArg<this>,
     update: PartialModelPatch<M>,
   ): NumberQueryBuilder<MaybeSingleQueryBuilder<this>>;
   patchAndFetch(update: PartialModelPatch<M>): SingleQueryBuilder<this>;
-  patchAndFetchById(id: MaybeCompositeId, update: PartialModelPatch<M>): SingleQueryBuilder<this>;
+  patchAndFetchById(id: IdArg<this>, update: PartialModelPatch<M>): SingleQueryBuilder<this>;
 
   del(): NumberQueryBuilder<this>;
   delete(): NumberQueryBuilder<this>;
-  deleteById(id: MaybeCompositeId): NumberQueryBuilder<MaybeSingleQueryBuilder<this>>;
+  deleteById(id: IdArg<this>): NumberQueryBuilder<MaybeSingleQueryBuilder<this>>;
 
   insert(insert: PartialModelRow<M>): SingleQueryBuilder<this>;
   insert(insert: PartialModelRow<M>[]): ArrayQueryBuilder<this>;
@@ -2292,15 +2555,15 @@ export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseL
   // With literal relation expressions, the fetched relations become required
   // on the result type, see WithGraphQueryBuilder.
   withGraphFetched<const E extends RelationExpression<M>>(
-    expr: E & CheckRelationExpression<M, E>,
+    expr: E & CheckRelationExpression<M, E, this>,
     options?: GraphOptions,
   ): WithGraphQueryBuilder<this, E>;
   withGraphJoined<const E extends RelationExpression<M>>(
-    expr: E & CheckRelationExpression<M, E>,
+    expr: E & CheckRelationExpression<M, E, this>,
     options?: GraphOptions,
   ): WithGraphQueryBuilder<this, E>;
   withGraph<const E extends RelationExpression<M>>(
-    expr: E & CheckRelationExpression<M, E>,
+    expr: E & CheckRelationExpression<M, E, this>,
     options?: WithGraphOptions,
   ): WithGraphQueryBuilder<this, E>;
 
@@ -2378,7 +2641,7 @@ export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseL
   clearContext: ClearContextMethod<this>;
 
   modify: ModifyMethod<this>;
-  modifiers: ModifiersMethod<this>;
+  modifiers: ModifiersMethod<this, M, R, X>;
 
   isFind: BooleanReturningMethod;
   isExecutable: BooleanReturningMethod;
@@ -2404,27 +2667,29 @@ export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseL
 
   ModelType: M;
   ResultType: R;
+  ExtraType: X;
 
-  // The model and result types that `RebindType` is instantiated with. They
-  // are `any` where `this` isn't rebound, e.g. when TypeScript checks the
-  // members of a custom query builder against this class.
+  // The model, result and extra types that `RebindType` is instantiated
+  // with. They are `any` where `this` isn't rebound, e.g. when TypeScript
+  // checks the members of a custom query builder against this class.
   '~rebind': unknown;
-  '~M': this['~rebind'] extends [any, any] ? this['~rebind'][0] : any;
-  '~R': this['~rebind'] extends [any, any] ? this['~rebind'][1] : any;
+  '~M': this['~rebind'] extends [any, any, any] ? this['~rebind'][0] : any;
+  '~R': this['~rebind'] extends [any, any, any] ? this['~rebind'][1] : any;
+  '~X': this['~rebind'] extends [any, any, any] ? this['~rebind'][2] : any;
 
   /**
-   * This query builder, re-instantiated with other model and result types,
-   * e.g. by `first()` or `page()`. Custom query builders redeclare it to keep
-   * their own type:
+   * This query builder, re-instantiated with other model, result and extra
+   * types, e.g. by `first()` or `page()`. Custom query builders redeclare it
+   * to keep their own type:
    *
-   *   declare RebindType: MyQueryBuilder<this['~M'], this['~R']>;
+   *   declare RebindType: MyQueryBuilder<this['~M'], this['~R'], this['~X']>;
    */
-  RebindType: QueryBuilder<this['~M'], this['~R']>;
+  RebindType: QueryBuilder<this['~M'], this['~R'], this['~X']>;
 
   // The query builder rebound to the result kinds of the helper types, e.g.
   // `SingleQueryBuilder`. As members, they also resolve where `this` is
   // generic, e.g. in the methods of custom query builders. Of the members
-  // starting with `~`, only `~M` and `~R` are API, for `RebindType`.
+  // starting with `~`, only `~M`, `~R` and `~X` are API, for `RebindType`.
   '~single': Rebind<this, M, ResultItem<R, M>>;
   '~maybeSingle': Rebind<this, M, ResultItem<R, M> | undefined>;
   '~array': Rebind<this, M, ResultItem<R, M>[]>;
@@ -2808,7 +3073,7 @@ export interface ModelClass<M extends Model> extends ModelConstructor<M> {
   relationMappings: RelationMappings | RelationMappingsThunk;
   modelPaths: string[];
   jsonAttributes: string[] | readonly string[];
-  virtualAttributes: string[];
+  virtualAttributes: readonly string[];
   uidProp: string;
   uidRefProp: string;
   dbRefProp: string;
@@ -2921,7 +3186,7 @@ export class Model {
   static relationMappings: RelationMappings | RelationMappingsThunk;
   static modelPaths: string[];
   static jsonAttributes: string[] | readonly string[];
-  static virtualAttributes: string[];
+  static virtualAttributes: readonly string[];
   static uidProp: string;
   static uidRefProp: string;
   static dbRefProp: string;
@@ -2949,16 +3214,28 @@ export class Model {
 
   static defaultGraphOptions?: GraphOptions;
 
-  static query<M extends Model>(
-    this: ConstructorType<M>,
+  // The id column K is inferred separately from the class C, so that it
+  // resolves through the constraint of a generic class, e.g. in static helpers
+  // with `this: T`.
+  static query<M extends Model, C = unknown, K = unknown>(
+    this: ConstructorType<M> & IfStrict<unknown, C & { idColumn?: K }>,
     trxOrKnex?: TransactionOrKnex,
-  ): QueryBuilderType<M>;
+  ): IfStrict<
+    QueryBuilderType<M>,
+    WithExtra<QueryBuilderType<M>, QueryExtra<C, {}, ColumnsId<K, M>>>
+  >;
 
-  static relatedQuery<M extends Model, K extends keyof M>(
-    this: ConstructorType<M>,
+  static relatedQuery<M extends Model, K extends keyof M, C = unknown>(
+    this: ConstructorType<M> & IfStrict<unknown, C>,
     relationName: K,
     trxOrKnex?: TransactionOrKnex,
-  ): ArrayRelatedQueryBuilder<M[K]>;
+  ): IfStrict<
+    ArrayRelatedQueryBuilder<M[K]>,
+    WithExtra<
+      ArrayRelatedQueryBuilder<M[K]>,
+      QueryExtra<MappedClass<ClassMappings<C>, K>, {}, ClassId<MappedClass<ClassMappings<C>, K>>>
+    >
+  >;
 
   static relatedQuery<RM extends Model>(
     relationName: string,
@@ -3215,32 +3492,26 @@ export interface initialize {
 
 /**
  * The type of the values that a JSON schema declared with `as const`
- * describes, e.g. the properties of a model from its `jsonSchema`:
+ * describes, e.g. of JSON columns, or of models that subclasses extend, whose
+ * `jsonSchema` has the general type for `FromModel`:
  *
- *   class Person extends Model {
- *     static jsonSchema = {
- *       type: 'object',
- *       required: ['firstName'],
- *       properties: {
- *         id: { type: 'integer' },
- *         firstName: { type: 'string' },
- *         age: { type: ['integer', 'null'] },
- *       },
- *     } as const;
+ *   const entrySchema = { type: 'object', properties: { ... } } as const;
  *
- *     pets?: Animal[];
+ *   class Entry extends Model {
+ *     static jsonSchema: ReadonlyJSONSchema = entrySchema;
  *   }
  *
- *   interface Person extends FromSchema<typeof Person.jsonSchema> {}
+ *   interface Entry extends FromJSONSchema<typeof entrySchema>, FromModel<typeof Entry> {}
  *
  * Supports `type` (also as an array), `required`, `nullable`, `enum`,
  * `const`, `items` (also as a tuple), nested `properties`, `anyOf` and
- * `oneOf`. Formats like 'date-time' stay strings, as in JSON. Properties
- * that aren't required are optional. Next to `type` or `properties`, `anyOf`
- * and `oneOf` only add constraints, e.g. alternative `required` lists, and
- * don't change the type.
+ * `oneOf`. Formats like 'date-time' stay strings, as in JSON, see the
+ * timestamps recipe for the dates that drivers return. Properties that aren't
+ * required are optional. Next to `type` or `properties`, `anyOf` and `oneOf`
+ * only add constraints, e.g. alternative `required` lists, and don't change
+ * the type.
  */
-export type FromSchema<S> = S extends boolean
+export type FromJSONSchema<S> = S extends boolean
   ? unknown
   : S extends { const: infer C }
     ? Extract<C, SchemaType<S>>
@@ -3251,7 +3522,7 @@ export type FromSchema<S> = S extends boolean
         : S extends { properties: object }
           ? SchemaObject<S>
           : S extends { anyOf: readonly (infer A)[] } | { oneOf: readonly (infer A)[] }
-            ? FromSchema<A> | SchemaNullable<S>
+            ? FromJSONSchema<A> | SchemaNullable<S>
             : unknown;
 
 // The type that `type` allows, which `enum` and `const` values are narrowed
@@ -3280,7 +3551,7 @@ type SchemaTypeName<N, S> = N extends 'string'
 type SchemaArray<S> = S extends { items: infer I }
   ? I extends readonly unknown[]
     ? SchemaTuple<I, S>
-    : FromSchema<I>[]
+    : FromJSONSchema<I>[]
   : unknown[];
 
 // Tuple `items` only check the items that are present: they are required
@@ -3288,12 +3559,12 @@ type SchemaArray<S> = S extends { items: infer I }
 // `additionalItems` restricts them.
 type SchemaTuple<I extends readonly unknown[], S> = [
   ...(S extends { minItems: I['length'] }
-    ? { -readonly [K in keyof I]: FromSchema<I[K]> }
-    : { -readonly [K in keyof I]?: FromSchema<I[K]> }),
+    ? { -readonly [K in keyof I]: FromJSONSchema<I[K]> }
+    : { -readonly [K in keyof I]?: FromJSONSchema<I[K]> }),
   ...(S extends { additionalItems: false }
     ? []
     : S extends { additionalItems: infer A }
-      ? FromSchema<A>[]
+      ? FromJSONSchema<A>[]
       : unknown[]),
 ];
 
@@ -3305,16 +3576,97 @@ type SchemaObject<S> = S extends { properties: infer P }
 
 // The intersection is flattened into one object type for readable hovers.
 type SchemaProperties<P, R> = {
-  -readonly [K in keyof P as K extends R ? K : never]: FromSchema<P[K]>;
+  -readonly [K in keyof P as K extends R ? K : never]: FromJSONSchema<P[K]>;
 } & {
-  -readonly [K in keyof P as K extends R ? never : K]?: FromSchema<P[K]>;
+  -readonly [K in keyof P as K extends R ? never : K]?: FromJSONSchema<P[K]>;
 } extends infer O
   ? { [K in keyof O]: O[K] }
   : never;
 
+/**
+ * The properties of a model class, derived from its `jsonSchema` declared
+ * `as const` and its `relationMappings`:
+ *
+ *   class Person extends Model {
+ *     static jsonSchema = { ... } as const;
+ *
+ *     static relationMappings = () => ({
+ *       parent: {
+ *         relation: Model.BelongsToOneRelation,
+ *         modelClass: Person,
+ *         join: { from: 'persons.parentId', to: 'persons.id' },
+ *       },
+ *     });
+ *   }
+ *
+ *   interface Person extends FromModel<typeof Person> {}
+ *
+ * The properties are typed as with `FromJSONSchema`. Relations are optional, as
+ * they are only present when fetched: to-one relations are typed `M | null`,
+ * as `withGraphFetched()` sets missing ones to `null`, and to-many relations
+ * `M[]`. Relations with a module path as `modelClass`, and mappings declared
+ * as `RelationMapping` instead of inferred, are left out, as are a schema and
+ * mappings with their general types, e.g. inherited from `Model`. The names of
+ * `virtualAttributes` declared `as const` are kept for `ModelJson`.
+ */
+export type FromModel<C extends { jsonSchema: unknown; relationMappings: unknown }> =
+  ModelSchemaProperties<C['jsonSchema']> &
+    ModelRelationProperties<C['relationMappings']> &
+    VirtualAttributeKeys<C>;
+
+// One key per name, so that subclasses that add virtual attributes have the
+// same keys as their parent for the inherited ones.
+type VirtualAttributeKeys<C> = C extends { virtualAttributes: infer V extends readonly string[] }
+  ? string extends V[number]
+    ? {}
+    : { readonly [K in V[number] as `~virtual:${K}`]?: true }
+  : {};
+
+type ModelSchemaProperties<S> = ReadonlyJSONSchema extends S
+  ? {}
+  : FromJSONSchema<S> extends infer P extends object
+    ? P
+    : {};
+
+// Relations are picked by their mappings, as resolving the related models
+// while the model's own type is built would make it its own base type.
+type ModelRelationProperties<T, R = T extends () => infer M ? M : T> = string extends keyof R
+  ? {}
+  : {
+      -readonly [K in keyof R as IsMappedRelation<R[K]> extends true ? K : never]?: MappedRelation<
+        R[K]
+      >;
+    };
+
+// Relation types without a brand and module paths can't be resolved.
+type IsMappedRelation<M> = M extends { relation: infer T; modelClass: infer C }
+  ? [MappedKind<T>] extends [never]
+    ? false
+    : C extends string
+      ? false
+      : true
+  : false;
+
+// The related model is inferred from the constructor without checking it
+// against `Model`, as that check would circle back through the relations of
+// self-referencing models.
+type MappedRelation<M> = M extends { relation: infer T; modelClass: infer C }
+  ? MappedKind<T> extends 'HasMany' | 'ManyToMany' | 'BelongsToMany'
+    ? MappedModel<C>[]
+    : MappedModel<C> | null
+  : never;
+
+type MappedKind<T> = T extends { readonly [relationKind]?: infer K } ? K : never;
+
+type MappedModel<C> = C extends abstract new (...args: any) => infer I
+  ? I
+  : C extends () => abstract new (...args: any) => infer I
+    ? I
+    : never;
+
 /**
  * A JSON schema with readonly arrays, the type of `static jsonSchema`, so that
- * it takes schemas declared `as const`, for `FromSchema`. A `JSONSchema` is
+ * it takes schemas declared `as const`, for `FromJSONSchema`. A `JSONSchema` is
  * assignable to it.
  */
 export type ReadonlyJSONSchema = ReadonlyDeep<JSONSchema>;