objection 3.1.5 → 3.3.0

package/typings/objection/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 
 // Type definitions for Objection.js
-// Project: <http://vincit.github.io/objection.js/>
+// Project: <https://ditojs.github.io/objection/>
 //
 // Contributions by:
 // * Matthew McEachen <https://github.com/mceachen>
@@ -30,17 +30,20 @@ declare namespace Objection {
 
   const snakeCaseMappers: SnakeCaseMappersFactory;
   const knexSnakeCaseMappers: KnexSnakeCaseMappersFactory;
+  const knexIdentifierMapping: KnexIdentifierMappingFactory;
 
   const transaction: transaction;
   const initialize: initialize;
 
-  const DBError: typeof dbErrors.DBError;
-  const DataError: typeof dbErrors.DataError;
-  const CheckViolationError: typeof dbErrors.CheckViolationError;
-  const UniqueViolationError: typeof dbErrors.UniqueViolationError;
-  const ConstraintViolationError: typeof dbErrors.ConstraintViolationError;
-  const ForeignKeyViolationError: typeof dbErrors.ForeignKeyViolationError;
-  const NotNullViolationError: typeof dbErrors.NotNullViolationError;
+  // Import aliases re-export both the value and the type side of the classes,
+  // so they can be used with `instanceof` as well as in type annotations.
+  export import DBError = dbErrors.DBError;
+  export import DataError = dbErrors.DataError;
+  export import CheckViolationError = dbErrors.CheckViolationError;
+  export import UniqueViolationError = dbErrors.UniqueViolationError;
+  export import ConstraintViolationError = dbErrors.ConstraintViolationError;
+  export import ForeignKeyViolationError = dbErrors.ForeignKeyViolationError;
+  export import NotNullViolationError = dbErrors.NotNullViolationError;
 
   export interface RawBuilder extends Aliasable {}
 
@@ -126,11 +129,13 @@ declare namespace Objection {
     | string
     | number
     | boolean
+    | bigint
     | Date
     | Buffer
     | string[]
     | number[]
     | boolean[]
+    | bigint[]
     | Date[]
     | Buffer[]
     | null;
@@ -158,10 +163,7 @@ declare namespace Objection {
   type AnyModelConstructor = ModelConstructor<Model>;
   type ModifierFunction<QB extends AnyQueryBuilder> = (qb: QB, ...args: any[]) => void;
   type Modifier<QB extends AnyQueryBuilder = AnyQueryBuilder> =
-    | ModifierFunction<QB>
-    | string
-    | string[]
-    | Record<string, Expression<PrimitiveValue>>;
+    ModifierFunction<QB> | string | string[] | Record<string, Expression<PrimitiveValue>>;
   type OrderByDirection = 'asc' | 'desc' | 'ASC' | 'DESC';
   type OrderByNulls = 'first' | 'last';
 
@@ -171,6 +173,216 @@ declare namespace Objection {
 
   type RelationExpression<M extends Model> = string | object;
 
+  // Type-level parsing of relation expressions, used to narrow the result
+  // types of `withGraphFetched()`, `withGraphJoined()` and `fetchGraph()`.
+
+  /**
+   * Parses a relation expression, in string or object notation, into a tree
+   * of fetched relations: '[pets.owner, children]' and
+   * `{ pets: { owner: true }, children: true }` both become
+   * `{ pets: { owner: {} }, children: {} }`.
+   *
+   * Anything that isn't a literal expression (e.g. a `string` variable) yields
+   * `{}`, and so do nodes the parser doesn't understand (aliases, `*`,
+   * recursion with `^`), so these simply don't narrow.
+   */
+  type ParseRelationExpression<E> = string extends E
+    ? {}
+    : E extends string
+      ? ParseRelationString<E>
+      : ParseRelationObject<E>;
+
+  type Whitespace = ' ' | '\n' | '\r' | '\t';
+
+  type Trim<S extends string> = S extends `${Whitespace}${infer R}`
+    ? Trim<R>
+    : S extends `${infer L}${Whitespace}`
+      ? Trim<L>
+      : S;
+
+  /**
+   * Counts the occurrences of character C in S, as a tuple length.
+   */
+  type CountChar<
+    S extends string,
+    C extends string,
+    N extends 0[] = [],
+  > = S extends `${string}${C}${infer R}` ? CountChar<R, C, [...N, 0]> : N['length'];
+
+  /**
+   * True if S has as many opening as closing brackets and parentheses.
+   */
+  type IsBalanced<S extends string> =
+    CountChar<S, '['> extends CountChar<S, ']'>
+      ? CountChar<S, '('> extends CountChar<S, ')'>
+        ? true
+        : false
+      : false;
+
+  /**
+   * Splits a list of expressions at the commas that aren't nested inside
+   * brackets or parentheses: 'a, b.[c, d]' -> ['a', 'b.[c, d]'].
+   */
+  type SplitList<
+    S extends string,
+    Acc extends string = '',
+    Out extends string[] = [],
+  > = S extends `${infer Head},${infer Rest}`
+    ? IsBalanced<`${Acc}${Head}`> extends true
+      ? SplitList<Rest, '', [...Out, `${Acc}${Head}`]>
+      : SplitList<Rest, `${Acc}${Head},`, Out>
+    : [...Out, `${Acc}${S}`];
+
+  type ParseRelationList<L extends string[], Acc = {}> = L extends [
+    infer H extends string,
+    ...infer T extends string[],
+  ]
+    ? ParseRelationList<T, Acc & ParseRelationString<H>>
+    : Acc;
+
+  /**
+   * Parses '[a, b]', 'a.b' and 'a' style expressions.
+   */
+  type ParseRelationString<S extends string> =
+    Trim<S> extends `[${infer Inner}]`
+      ? ParseRelationList<SplitList<Inner>>
+      : Trim<S> extends `${infer Head}.${infer Rest}`
+        ? IsBalanced<Head> extends true
+          ? RelationNode<RelationName<Head>, ParseRelationString<Rest>>
+          : {}
+        : RelationNode<RelationName<S>, {}>;
+
+  /**
+   * Extracts the relation name from a single node, dropping modifiers:
+   * 'pets(selectName)' -> 'pets'. Returns never for nodes that can't be
+   * narrowed: aliases ('pets as p'), '*' and recursion ('^', '^2').
+   */
+  type RelationName<S extends string> =
+    Trim<S> extends `${infer Name}(${string})`
+      ? RelationName<Name>
+      : Trim<S> extends infer Name extends string
+        ? Name extends '' | '*' | `^${string}` | `${string}${Whitespace}${string}`
+          ? never
+          : string extends Name
+            ? never
+            : Name
+        : never;
+
+  type RelationNode<Name extends string, Children> = [Name] extends [never]
+    ? {}
+    : { [K in Name]: Children };
+
+  /**
+   * Parses `{ a: true, b: { c: true } }` style expressions. Keys starting with
+   * `$` are options, and aliased nodes (`{ p: { $relation: 'pets' } }`) are
+   * skipped.
+   */
+  type ParseRelationObject<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
+        ]: E[K] extends object ? ParseRelationObject<E[K]> : {};
+      };
+
+  /**
+   * Marks the relations in tree T as fetched on model M: they become required
+   * and are narrowed recursively. Only `undefined` is removed: declared `null`
+   * is kept, as to-one relations can be null when there is no related row.
+   */
+  type WithGraph<M, T> = [keyof T] extends [never]
+    ? M
+    : WithGraphRelations<M, T, FetchedRelations<M, T>>;
+
+  type WithGraphRelations<M, T, K extends keyof M & keyof T> = [K] extends [never]
+    ? M
+    : { -readonly [P in K]-?: WithGraphProperty<Defined<M[P]>, T[P]> } & UnnarrowedMethods<M> & M;
+
+  /**
+   * `$query()` of the un-narrowed model M, as it doesn't fetch the relations
+   * that were fetched on the instance. Otherwise its polymorphic `this` would
+   * resolve to the narrowed model. With chained narrowing, the first `$query`
+   * signature of the intersection wins, which is the one of the innermost,
+   * un-narrowed model.
+   */
+  type UnnarrowedMethods<M> = Pick<M, Extract<'$query', keyof M>>;
+
+  /**
+   * The keys of tree T that are relation properties of model M.
+   */
+  type FetchedRelations<M, T> = {
+    [K in keyof M & keyof T]: NonNullable<M[K]> extends Model | Model[] ? K : never;
+  }[keyof M & keyof T];
+
+  type WithGraphProperty<P, T> = [keyof T] extends [never]
+    ? P
+    : P extends Array<infer I>
+      ? WithGraph<I, T>[]
+      : P extends Model
+        ? WithGraph<P, T>
+        : P;
+
+  /**
+   * The model type after fetching the relation expression E on model M.
+   */
+  type WithGraphModel<M, E> = WithGraph<M, ParseRelationExpression<E>>;
+
+  /**
+   * The query builder type for model M after fetching relation expression E.
+   * `M extends unknown` makes this distributive, so that in generic code (e.g.
+   * `this` in model methods), TypeScript can resolve it through the constraint
+   * of M.
+   */
+  type WithGraphModelQueryBuilder<M extends Model, E> = M extends unknown
+    ? WithGraphModel<M, E>['QueryBuilderType']
+    : never;
+
+  /**
+   * The query builder type after `withGraphFetched(E)` / `withGraphJoined(E)`
+   * on QB. The model type is narrowed, and the query builder for the narrowed
+   * model is looked up through its `QueryBuilderType`, so custom query
+   * builders are kept. Falls back to QB if nothing can be narrowed, or if the
+   * model type is `any` (`0 extends 1 & M`), e.g. for AnyQueryBuilder.
+   * `QB extends unknown` below serves the same purpose as in
+   * WithGraphModelQueryBuilder.
+   */
+  type WithGraphQueryBuilder<QB extends AnyQueryBuilder, E> = WithGraphTreeQueryBuilder<
+    QB,
+    ParseRelationExpression<E>
+  >;
+
+  type WithGraphTreeQueryBuilder<QB extends AnyQueryBuilder, T> = [keyof T] extends [never]
+    ? QB
+    : QB extends unknown
+      ? 0 extends 1 & ModelType<QB>
+        ? QB
+        : [FetchedRelations<ModelType<QB>, T>] extends [never]
+          ? QB
+          : WithResultKind<QB, WithGraph<ModelType<QB>, T>['QueryBuilderType']>
+      : never;
+
+  /**
+   * Converts the query builder NQB to the same result kind as QB:
+   * array, single, maybe-single or page.
+   */
+  type WithResultKind<QB extends AnyQueryBuilder, NQB extends AnyQueryBuilder> = [
+    ResultType<QB>,
+  ] extends [ModelType<QB>[]]
+    ? ArrayQueryBuilder<NQB>
+    : [ResultType<QB>] extends [ModelType<QB>]
+      ? SingleQueryBuilder<NQB>
+      : [ResultType<QB>] extends [ModelType<QB> | undefined]
+        ? MaybeSingleQueryBuilder<NQB>
+        : [ResultType<QB>] extends [Page<ModelType<QB>>]
+          ? PageQueryBuilder<NQB>
+          : QB;
+
   /**
    * If T is an array, returns the item type, otherwise returns T.
    */
@@ -201,14 +413,24 @@ declare namespace Objection {
    */
   type PartialModelObject<T extends Model> = {
     [K in DataPropertyNames<T>]?: Defined<T[K]> extends Model
-      ? T[K]
+      ? T[K] | PartialModelObject<Defined<T[K]>>
       : Defined<T[K]> extends Array<infer I>
         ? I extends Model
-          ? I[]
+          ? I[] | PartialModelObject<I>[]
           : Expression<T[K]>
         : Expression<T[K]>;
   };
 
+  /**
+   * Like PartialModelObject, but relation properties are not allowed. Unlike
+   * PartialModelObject, this doesn't depend on the relation types, so query
+   * builders for models with narrowed relations (see WithGraphModel) remain
+   * assignable to the query builders for the plain models.
+   */
+  type PartialModelProps<T extends Model> = {
+    [K in DataPropertyNames<T>]?: Defined<T[K]> extends Model | Model[] ? never : Expression<T[K]>;
+  };
+
   /**
    * Additional optional parameters that may be used in graphs.
    */
@@ -216,6 +438,8 @@ declare namespace Objection {
     '#dbRef'?: MaybeCompositeId;
     '#ref'?: string;
     '#id'?: string;
+    '#unrelate'?: boolean;
+    '#delete'?: boolean;
   };
 
   /**
@@ -341,7 +565,7 @@ declare namespace Objection {
   }
 
   /**
-   * https://vincit.github.io/objection.js/api/types/#type-fieldexpression
+   * https://ditojs.github.io/objection/api/types/#type-fieldexpression
    */
   type FieldExpression = string;
 
@@ -440,7 +664,7 @@ declare namespace Objection {
     (raw: Raw): QB;
     <QBA extends AnyQueryBuilder>(qb: QBA): QB;
 
-    (obj: PartialModelObject<ModelType<QB>>): QB;
+    (obj: PartialModelProps<ModelType<QB>>): QB;
     // We must allow any keys in the object. The previous type
     // is kind of useless, but maybe one day vscode and other
     // tools can autocomplete using it.
@@ -597,6 +821,7 @@ declare namespace Objection {
 
   interface WithMethod<QB extends AnyQueryBuilder> {
     (alias: string, expr: CallbackVoid<QB> | AnyQueryBuilder | Raw): QB;
+    (alias: string, columns: string[], expr: CallbackVoid<QB> | AnyQueryBuilder | Raw): QB;
   }
 
   interface JoinRelatedOptions {
@@ -612,6 +837,7 @@ declare namespace Objection {
     (table: TableRef<QB>, leftCol: ColumnRef, op: Operator, rightCol: ColumnRef): QB;
     (table: TableRef<QB>, leftCol: ColumnRef, rightCol: ColumnRef): QB;
     (table: TableRef<QB>, cb: CallbackVoid<Knex.JoinClause>): QB;
+    (table: TableRef<QB>, columns: { [leftCol: string]: ColumnRef }): QB;
     (table: TableRef<QB>, raw: Raw): QB;
     (raw: Raw): QB;
   }
@@ -624,6 +850,7 @@ declare namespace Objection {
 
   interface AggregateMethod<QB extends AnyQueryBuilder> {
     (column: ColumnRef): QB;
+    (aliasToColumnDict: { [alias: string]: ColumnRef }): QB;
   }
 
   interface CountMethod<QB extends AnyQueryBuilder> {
@@ -655,7 +882,7 @@ declare namespace Objection {
   interface FirstMethod {
     <QB extends AnyQueryBuilder>(
       this: QB,
-    ): QB extends ArrayQueryBuilder<QB> ? MaybeSingleQueryBuilder<QB> : QB;
+    ): [ResultType<QB>] extends [any[]] ? MaybeSingleQueryBuilder<QB> : QB;
   }
 
   type ForIdValue = MaybeCompositeId | AnyQueryBuilder;
@@ -693,10 +920,11 @@ declare namespace Objection {
   }
 
   interface TableRefForMethod {
-    (modelClass: ModelClass<Model> | typeof Model): string;
+    (modelClassOrTableName: string | AnyModelConstructor): string;
   }
 
   interface AliasForMethod<QB extends AnyQueryBuilder> {
+    (modelClassOrTableName: string | AnyModelConstructor): string | null;
     (modelClassOrTableName: string | AnyModelConstructor, alias: string): QB;
   }
 
@@ -704,10 +932,15 @@ declare namespace Objection {
     (): ModelClass<M>;
   }
 
+  interface ReturningOptions {
+    includeTriggerModifications?: boolean;
+  }
+
   interface ReturningMethod {
     <QB extends AnyQueryBuilder>(
       this: QB,
-      column: string | Raw | (string | Raw)[],
+      column: string | Raw | (string | Raw)[] | readonly (string | Raw)[],
+      options?: ReturningOptions,
     ): QB extends NumberQueryBuilder<QB> ? ArrayQueryBuilder<QB> : QB;
   }
 
@@ -818,6 +1051,10 @@ declare namespace Objection {
     maxBatchSize?: number;
   }
 
+  export interface WithGraphOptions extends GraphOptions {
+    algorithm?: 'fetch' | 'join';
+  }
+
   interface ModifyGraphMethod<QB extends AnyQueryBuilder> {
     <M extends Model>(
       expr: RelationExpression<ModelType<QB>>,
@@ -856,6 +1093,8 @@ declare namespace Objection {
   export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseLike<R> {
     static forClass: ForClassMethod;
 
+    constructor(modelClass: ModelConstructor<M>);
+
     select: SelectMethod<this>;
     columns: SelectMethod<this>;
     column: SelectMethod<this>;
@@ -1031,6 +1270,7 @@ declare namespace Objection {
     increment: IncrementDecrementMethod<this>;
     decrement: IncrementDecrementMethod<this>;
     first: FirstMethod;
+    none: IdentityMethod<this>;
 
     orderBy: OrderByMethod<this>;
     orderByRaw: OrderByRawMethod<this>;
@@ -1048,6 +1288,7 @@ declare namespace Objection {
 
     update(update: PartialModelObject<M>): NumberQueryBuilder<this>;
     update(): NumberQueryBuilder<this>;
+    updateById(id: MaybeCompositeId, update: PartialModelObject<M>): NumberQueryBuilder<this>;
     updateAndFetch(update: PartialModelObject<M>): SingleQueryBuilder<this>;
     updateAndFetchById(
       id: MaybeCompositeId,
@@ -1056,6 +1297,7 @@ declare namespace Objection {
 
     patch(update: PartialModelObject<M>): NumberQueryBuilder<this>;
     patch(): NumberQueryBuilder<this>;
+    patchById(id: MaybeCompositeId, update: PartialModelObject<M>): NumberQueryBuilder<this>;
     patchAndFetch(update: PartialModelObject<M>): SingleQueryBuilder<this>;
     patchAndFetchById(
       id: MaybeCompositeId,
@@ -1085,15 +1327,25 @@ declare namespace Objection {
     unrelate(): NumberQueryBuilder<this>;
     for(ids: ForIdValue | ForIdValue[]): this;
 
-    withGraphFetched(expr: RelationExpression<M>, options?: GraphOptions): this;
-    withGraphJoined(expr: RelationExpression<M>, options?: GraphOptions): this;
+    // With literal relation expressions, the fetched relations become required
+    // on the result type, see WithGraphQueryBuilder.
+    withGraphFetched<const E extends RelationExpression<M>>(
+      expr: E,
+      options?: GraphOptions,
+    ): WithGraphQueryBuilder<this, E>;
+    withGraphJoined<const E extends RelationExpression<M>>(
+      expr: E,
+      options?: GraphOptions,
+    ): WithGraphQueryBuilder<this, E>;
+    withGraph<const E extends RelationExpression<M>>(
+      expr: E,
+      options?: WithGraphOptions,
+    ): WithGraphQueryBuilder<this, E>;
 
     truncate(): Promise<void>;
     allowGraph: AllowGraphMethod<this>;
 
-    throwIfNotFound: (
-      arg?: any,
-    ) => R extends Model | undefined ? SingleQueryBuilder<QueryBuilder<M, M>> : this;
+    throwIfNotFound: (arg?: any) => R extends Model | undefined ? SingleQueryBuilder<this> : this;
 
     returning: ReturningMethod;
     forUpdate: IdentityMethod<this>;
@@ -1110,6 +1362,8 @@ declare namespace Objection {
     modelClass: ModelClassMethod<M>;
     tableNameFor: TableRefForMethod;
     tableRefFor: TableRefForMethod;
+    tableName(): string;
+    tableRef(): string;
     reject: OneArgMethod<any, this>;
     resolve: OneArgMethod<any, this>;
     transacting: OneArgMethod<TransactionOrKnex, this>;
@@ -1120,12 +1374,13 @@ declare namespace Objection {
     toKnexQuery<T extends {} = ModelObject<M>>(): Knex.QueryBuilder<T, T[]>;
     knex(knex?: Knex): Knex;
     clone(): this;
+    emptyInstance(): this;
 
     page(page: number, pageSize: number): PageQueryBuilder<this>;
     range(): PageQueryBuilder<this>;
     range(start: number, end: number): PageQueryBuilder<this>;
-    offset(offset: number): this;
-    limit(limit: number): this;
+    offset(offset: number, options?: boolean | { skipBinding?: boolean }): this;
+    limit(limit: number, options?: boolean | { skipBinding?: boolean }): this;
     resultSize(): Promise<number>;
 
     runBefore: RunBeforeMethod<this>;
@@ -1159,6 +1414,7 @@ declare namespace Objection {
     isRelate: BooleanReturningMethod;
     isUnrelate: BooleanReturningMethod;
     isInternal: BooleanReturningMethod;
+    isJoinChildQuery: BooleanReturningMethod;
     hasWheres: BooleanReturningMethod;
     hasSelects: BooleanReturningMethod;
     hasWithGraph: BooleanReturningMethod;
@@ -1302,6 +1558,7 @@ declare namespace Objection {
 
   export interface ToJsonOptions extends CloneOptions {
     virtuals?: boolean | string[];
+    format?: Pojo;
   }
 
   export interface ValidatorContext {
@@ -1334,6 +1591,13 @@ declare namespace Objection {
     upperCase?: boolean;
     underscoreBeforeDigits?: boolean;
     underscoreBetweenUppercaseLetters?: boolean;
+    noDoubleUnderscores?: boolean;
+    /**
+     * Only convert the column part of field expressions like
+     * `jsonColumn:someKey` and keep their JSON keys as written.
+     * Only used by `snakeCaseMappers`.
+     */
+    preserveJsonKeys?: boolean;
   }
 
   export interface ColumnNameMappers {
@@ -1354,11 +1618,12 @@ declare namespace Objection {
     (options?: SnakeCaseMappersOptions): KnexMappers;
   }
 
+  export interface KnexIdentifierMappingFactory {
+    (colToProp: Record<string, string>): KnexMappers;
+  }
+
   export type ValidationErrorType =
-    | 'ModelValidation'
-    | 'RelationExpression'
-    | 'UnallowedRelation'
-    | 'InvalidGraph';
+    'ModelValidation' | 'RelationExpression' | 'UnallowedRelation' | 'InvalidGraph';
 
   export class ValidationError extends Error {
     constructor(args: CreateValidationErrorArgs & { modelClass?: ModelClass<Model> });
@@ -1426,15 +1691,17 @@ declare namespace Objection {
   interface PrototypeType<T> extends Function {
     prototype: T;
   }
-  
+
   interface ConstructorFunctionType<T = any> extends PrototypeType<T> {
     new (...args: any[]): T;
   }
-  
+
   // for internal use on generic static this deduction, copied from https://github.com/microsoft/TypeScript/issues/5863#issuecomment-1483978415
-  type ConstructorType<T = unknown, Static extends Record<string, any> = PrototypeType<T>> = (ConstructorFunctionType<T> | PrototypeType<T>) & {
+  type ConstructorType<T = unknown, Static extends Record<string, any> = PrototypeType<T>> = (
+    ConstructorFunctionType<T> | PrototypeType<T>
+  ) & {
     [Key in keyof Static]: Static[Key];
-  };  
+  };
 
   export interface ModelConstructor<M extends Model> extends Constructor<M> {}
 
@@ -1442,16 +1709,18 @@ declare namespace Objection {
     QueryBuilder: typeof QueryBuilder;
 
     tableName: string;
-    idColumn: string | string[];
+    idColumn: null | string | string[] | readonly string[];
     jsonSchema: JSONSchema;
     relationMappings: RelationMappings | RelationMappingsThunk;
     modelPaths: string[];
-    jsonAttributes: string[];
+    jsonAttributes: string[] | readonly string[];
     virtualAttributes: string[];
     uidProp: string;
     uidRefProp: string;
     dbRefProp: string;
     propRefRegex: RegExp;
+    graphUnrelateProp: string;
+    graphDeleteProp: string;
     pickJsonSchemaProperties: boolean;
     relatedFindQueryMutates: boolean;
     relatedInsertQueryMutates: boolean;
@@ -1509,17 +1778,17 @@ declare namespace Objection {
     bindKnex(trxOrKnex: TransactionOrKnex): this;
     bindTransaction(trxOrKnex: TransactionOrKnex): this;
 
-    fetchGraph(
+    fetchGraph<const E extends RelationExpression<M>>(
       modelOrObject: PartialModelObject<M>,
-      expression: RelationExpression<M>,
+      expression: E,
       options?: FetchGraphOptions,
-    ): SingleQueryBuilder<QueryBuilderType<M>>;
+    ): SingleQueryBuilder<WithGraphModelQueryBuilder<M, E>>;
 
-    fetchGraph(
+    fetchGraph<const E extends RelationExpression<M>>(
       modelOrObject: PartialModelObject<M>[],
-      expression: RelationExpression<M>,
+      expression: E,
       options?: FetchGraphOptions,
-    ): QueryBuilderType<M>;
+    ): WithGraphModelQueryBuilder<M, E>;
 
     getRelations(): Relations;
     getRelation(name: string): Relation;
@@ -1551,16 +1820,18 @@ declare namespace Objection {
     static QueryBuilder: typeof QueryBuilder;
 
     static tableName: string;
-    static idColumn: string | string[];
+    static idColumn: null | string | string[] | readonly string[];
     static jsonSchema: JSONSchema;
     static relationMappings: RelationMappings | RelationMappingsThunk;
     static modelPaths: string[];
-    static jsonAttributes: string[];
+    static jsonAttributes: string[] | readonly string[];
     static virtualAttributes: string[];
     static uidProp: string;
     static uidRefProp: string;
     static dbRefProp: string;
     static propRefRegex: RegExp;
+    static graphUnrelateProp: string;
+    static graphDeleteProp: string;
     static pickJsonSchemaProperties: boolean;
     static relatedFindQueryMutates: boolean;
     static relatedInsertQueryMutates: boolean;
@@ -1581,7 +1852,7 @@ declare namespace Objection {
     static defaultGraphOptions?: GraphOptions;
 
     static query<M extends Model>(
-      this: Constructor<M>,
+      this: ConstructorType<M>,
       trxOrKnex?: TransactionOrKnex,
     ): QueryBuilderType<M>;
 
@@ -1596,8 +1867,8 @@ declare namespace Objection {
       trxOrKnex?: TransactionOrKnex,
     ): QueryBuilderType<RM>;
 
-    static fromJson<M extends Model>(this: Constructor<M>, json: object, opt?: ModelOptions): M;
-    static fromDatabaseJson<M extends Model>(this: Constructor<M>, json: object): M;
+    static fromJson<M extends Model>(this: ConstructorType<M>, json: object, opt?: ModelOptions): M;
+    static fromDatabaseJson<M extends Model>(this: ConstructorType<M>, json: object): M;
 
     static columnNameToPropertyName(columnName: string): string;
     static propertyNameToColumnName(propertyName: string): string;
@@ -1622,19 +1893,19 @@ declare namespace Objection {
     static bindKnex<M>(this: M, trxOrKnex: TransactionOrKnex): M;
     static bindTransaction<M>(this: M, trxOrKnex: TransactionOrKnex): M;
 
-    static fetchGraph<M extends Model>(
-      this: Constructor<M>,
+    static fetchGraph<M extends Model, const E extends RelationExpression<M>>(
+      this: ConstructorType<M>,
       modelOrObject: PartialModelObject<M>,
-      expression: RelationExpression<M>,
+      expression: E,
       options?: FetchGraphOptions,
-    ): SingleQueryBuilder<QueryBuilderType<M>>;
+    ): SingleQueryBuilder<WithGraphModelQueryBuilder<M, E>>;
 
-    static fetchGraph<M extends Model>(
-      this: Constructor<M>,
+    static fetchGraph<M extends Model, const E extends RelationExpression<M>>(
+      this: ConstructorType<M>,
       modelOrObject: PartialModelObject<M>[],
-      expression: RelationExpression<M>,
+      expression: E,
       options?: FetchGraphOptions,
-    ): QueryBuilderType<M>;
+    ): WithGraphModelQueryBuilder<M, E>;
 
     static getRelations(): Relations;
     static getRelation(name: string): Relation;
@@ -1678,15 +1949,15 @@ declare namespace Objection {
     $id(id: any): void;
     $id(): any;
 
-    $fetchGraph(
-      expression: RelationExpression<this>,
+    $fetchGraph<const E extends RelationExpression<this>>(
+      expression: E,
       options?: FetchGraphOptions,
-    ): SingleQueryBuilder<QueryBuilderType<this>>;
+    ): SingleQueryBuilder<WithGraphModelQueryBuilder<this, E>>;
 
     $formatDatabaseJson(json: Pojo): Pojo;
     $parseDatabaseJson(json: Pojo): Pojo;
 
-    $formatJson(json: Pojo): Pojo;
+    $formatJson(json: Pojo, opt?: Pojo): Pojo;
     $parseJson(json: Pojo, opt?: ModelOptions): Pojo;
 
     $beforeValidate(jsonSchema: JSONSchema, json: Pojo, opt: ModelOptions): JSONSchema;
@@ -1739,7 +2010,7 @@ declare namespace Objection {
    * - https://github.com/microsoft/TypeScript/issues/1360
    * - https://github.com/Microsoft/TypeScript/issues/5453
    *
-   * @tutorial https://vincit.github.io/objection.js/guide/transactions.html#creating-a-transaction
+   * @tutorial https://ditojs.github.io/objection/guide/transactions.html#creating-a-transaction
    */
   export interface transaction {
     start(knexOrModel: Knex | AnyModelConstructor): Promise<Transaction>;
@@ -1850,14 +2121,7 @@ declare namespace Objection {
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
    */
   export type JSONSchemaTypeName =
-    | 'string'
-    | 'number'
-    | 'integer'
-    | 'boolean'
-    | 'object'
-    | 'array'
-    | 'null'
-    | string;
+    'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null' | string;
 
   export type JSONSchemaType = JSONSchemaArray[] | boolean | number | null | object | string;
 
@@ -1889,6 +2153,13 @@ declare namespace Objection {
     $schema?: JSONSchemaVersion;
     $comment?: string;
 
+    /**
+     * @see https://json-schema.org/draft/2019-09/release-notes
+     */
+    $defs?: {
+      [key: string]: JSONSchemaDefinition;
+    };
+
     /**
      * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
      */