objection 4.0.0-rc.3 → 4.0.0

package/typings/objection/index.d.ts

@@ -80,6 +80,10 @@ export class UniqueViolationError extends ConstraintViolationError {
   schema?: string;
 }
 
+// Wraps an error of the database driver in the matching database error class,
+// or returns it as it is.
+export function wrapError<E>(err: E): DBError | E;
+
 export interface RawBuilder extends Aliasable {}
 
 export interface RawFunction extends RawInterface<RawBuilder> {}
@@ -214,6 +218,7 @@ export type RelationExpression<M extends Model> = string | object;
 
 // Type-level parsing of relation expressions, used to narrow the result
 // types of `withGraphFetched()`, `withGraphJoined()` and `fetchGraph()`.
+// The types that declarations of inferred query types refer to are exported.
 
 /**
  * Parses a relation expression, in string or object notation, into a tree
@@ -234,9 +239,9 @@ export type ParseRelationExpression<E> = [E] extends [never]
       ? ParseRelationString<E>
       : ParseRelationObject<E>;
 
-export type Whitespace = ' ' | '\n' | '\r' | '\t';
+type Whitespace = ' ' | '\n' | '\r' | '\t';
 
-export type Trim<S extends string> = S extends `${Whitespace}${infer R}`
+type Trim<S extends string> = S extends `${Whitespace}${infer R}`
   ? Trim<R>
   : S extends `${infer L}${Whitespace}`
     ? Trim<L>
@@ -245,7 +250,7 @@ export type Trim<S extends string> = S extends `${Whitespace}${infer R}`
 /**
  * Counts the occurrences of character C in S, as a tuple length.
  */
-export type CountChar<
+type CountChar<
   S extends string,
   C extends string,
   N extends 0[] = [],
@@ -254,7 +259,7 @@ export type CountChar<
 /**
  * True if S has as many opening as closing brackets and parentheses.
  */
-export type IsBalanced<S extends string> =
+type IsBalanced<S extends string> =
   CountChar<S, '['> extends CountChar<S, ']'>
     ? CountChar<S, '('> extends CountChar<S, ')'>
       ? true
@@ -265,7 +270,7 @@ export type IsBalanced<S extends string> =
  * Splits a list of expressions at the commas that aren't nested inside
  * brackets or parentheses: 'a, b.[c, d]' -> ['a', 'b.[c, d]'].
  */
-export type SplitList<
+type SplitList<
   S extends string,
   Acc extends string = '',
   Out extends string[] = [],
@@ -275,7 +280,7 @@ export type SplitList<
     : SplitList<Rest, `${Acc}${Head},`, Out>
   : [...Out, `${Acc}${S}`];
 
-export type ParseRelationList<L extends string[], Acc = {}> = L extends [
+type ParseRelationList<L extends string[], Acc = {}> = L extends [
   infer H extends string,
   ...infer T extends string[],
 ]
@@ -285,7 +290,7 @@ export type ParseRelationList<L extends string[], Acc = {}> = L extends [
 /**
  * Parses '[a, b]', 'a.b' and 'a' style expressions.
  */
-export type ParseRelationString<S extends string> =
+type ParseRelationString<S extends string> =
   Trim<S> extends `[${infer Inner}]`
     ? ParseRelationList<SplitList<Inner>>
     : Trim<S> extends `${infer Head}.${infer Rest}`
@@ -299,7 +304,7 @@ export type ParseRelationString<S extends string> =
  * 'pets(selectName)' -> 'pets'. Returns never for nodes that can't be
  * narrowed: aliases ('pets as p'), '*' and recursion ('^', '^2').
  */
-export type RelationName<S extends string> =
+type RelationName<S extends string> =
   Trim<S> extends `${infer Name}(${string})`
     ? RelationName<Name>
     : Trim<S> extends infer Name extends string
@@ -310,7 +315,7 @@ export type RelationName<S extends string> =
           : Name
       : never;
 
-export type RelationNode<Name extends string, Children> = [Name] extends [never]
+type RelationNode<Name extends string, Children> = [Name] extends [never]
   ? {}
   : { [K in Name]: Children };
 
@@ -319,26 +324,27 @@ export type RelationNode<Name extends string, Children> = [Name] extends [never]
  * `$` are options, and aliased nodes (`{ p: { $relation: 'pets' } }`) are
  * skipped.
  */
-export type ParseRelationObject<E> = string extends keyof E
-  ? {}
-  : {
-      [
-        K in keyof E as K extends `$${string}`
-          ? never
-          : false extends E[K]
+type ParseRelationObject<E> =
+  HasOnlyLiteralKeys<E> extends true
+    ? {
+        [
+          K in keyof E as K extends `$${string}`
             ? never
-            : E[K] extends { $relation: any }
+            : false extends E[K]
               ? never
-              : K
-      ]: E[K] extends object ? ParseRelationObject<E[K]> : {};
-    };
+              : 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.
  */
-export type WithGraph<M, T> = [keyof T] extends [never]
+type WithGraph<M, T> = [keyof T] extends [never]
   ? M
   : WithGraphRelations<M, T, FetchedRelations<M, T>>;
 
@@ -362,7 +368,7 @@ export type FetchedRelations<M, T> = {
   [K in keyof M & keyof T]: NonNullable<M[K]> extends Model | Model[] ? K : never;
 }[keyof M & keyof T];
 
-export type WithGraphProperty<P, T> = [keyof T] extends [never]
+type WithGraphProperty<P, T> = [keyof T] extends [never]
   ? P
   : P extends Array<infer I>
     ? WithGraph<I, T>[]
@@ -466,16 +472,11 @@ type ItemOf<R, M> = R extends readonly (infer I)[]
       ? R
       : M;
 
-/**
- * If T is an array, returns the item type, otherwise returns T.
- */
-export type ItemType<T> = T extends Array<unknown> ? T[number] : T;
-
 /**
  * Type for keys of non-function properties of T.
  */
 export type NonFunctionPropertyNames<T> = {
-  [K in keyof T]: T[K] extends Function ? never : K;
+  [K in keyof T]-?: T[K] extends Function ? never : K;
 }[keyof T];
 
 // The type-only members of models, which aren't data, also the keys of the
@@ -540,7 +541,7 @@ export type PartialModelObject<T extends Model> = {
         ? I[] | PartialModelObject<I>[]
         : Expression<T[K]>
       : NonNullable<T[K]> extends Model
-        ? Expression<T[K]> | PartialModelObject<NonNullable<T[K]>> // nullable to-one relations
+        ? Expression<T[K]> | PartialModelObject<NonNullable<T[K]>> // Nullable to-one relations
         : Expression<T[K]>;
 };
 
@@ -550,7 +551,7 @@ export type PartialModelObject<T extends Model> = {
  * builders for models with narrowed relations (see WithGraphModel) remain
  * assignable to the query builders for the plain models.
  */
-export type PartialModelProps<T extends Model> = {
+type PartialModelProps<T extends Model> = {
   [K in DataPropertyNames<T>]?: K extends RelationPropertyNames<T> ? never : Expression<T[K]>;
 };
 
@@ -591,7 +592,7 @@ export type GraphParameters = {
 export type PartialModelGraph<M, T = M & GraphParameters> = T extends any
   ? {
       [K in DataPropertyNames<T>]?: null extends T[K]
-        ? PartialModelGraphField<NonNullable<T[K]>> | null // handle nullable BelongsToOneRelations
+        ? PartialModelGraphField<NonNullable<T[K]>> | null // Strip null to recognize to-one relations
         : PartialModelGraphField<T[K]>;
     }
   : never;
@@ -622,7 +623,7 @@ export interface GeneratedBrand {
 /**
  * Insert keys are optional for optional, nullable and generated properties.
  */
-export type OptionalInsertPropertyNames<M> = {
+type OptionalInsertPropertyNames<M> = {
   [K in keyof M]-?: {} extends Pick<M, K>
     ? K
     : null extends M[K]
@@ -632,12 +633,13 @@ export type OptionalInsertPropertyNames<M> = {
         : never;
 }[keyof M];
 
-export type InsertablePropertyNames<M> = Exclude<DataPropertyNames<M>, RelationPropertyNames<M>>;
+type InsertablePropertyNames<M> = Exclude<DataPropertyNames<M>, RelationPropertyNames<M>>;
 
 /**
- * The data to insert a model M with `insert()`. Unlike `PartialModelObject`,
- * all properties are required except optional, nullable and `Generated`
- * ones. Relation properties are left out.
+ * The complete data of a new row of model M, to check what is passed to
+ * `insert()`, which itself takes any subset of the properties. Unlike
+ * `PartialModelObject`, all properties are required except optional, nullable
+ * and `Generated` ones. Relation properties are left out.
  */
 export type Insertable<M extends Model> = {
   [K in Exclude<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]: Expression<M[K]>;
@@ -646,18 +648,18 @@ export type Insertable<M extends Model> = {
 };
 
 /**
- * Like `Insertable`, but for `insertGraph()`: relation properties are
- * optional and hold the insertable graphs of the related models, or
- * references to existing ones through `#dbRef` or `#ref`.
+ * Like `Insertable`, but for graphs passed to `insertGraph()`: relation
+ * properties are optional and hold the insertable graphs of the related
+ * models, or references to existing ones through `#dbRef` or `#ref`.
  */
 export type InsertableGraph<M extends Model> = Insertable<M> &
   Omit<GraphParameters, '#dbRef' | '#ref'> & {
     [K in RelationPropertyNames<M>]?: InsertableGraphField<M[K]>;
   };
 
-export type InsertableGraphReference = { '#dbRef': MaybeCompositeId } | { '#ref': string };
+type InsertableGraphReference = { '#dbRef': MaybeCompositeId } | { '#ref': string };
 
-export type InsertableGraphField<F> =
+type InsertableGraphField<F> =
   NonNullable<F> extends (infer I extends Model)[]
     ? (InsertableGraph<I> | InsertableGraphReference)[]
     : NonNullable<F> extends infer I extends Model
@@ -667,38 +669,15 @@ export type InsertableGraphField<F> =
 /**
  * Extracts the property names (excluding relations) of a model class.
  */
-export type ModelProps<T extends Model> = Exclude<
-  {
-    [K in keyof T]?: Defined<T[K]> extends Model
-      ? never
-      : Defined<T[K]> extends Array<infer I>
-        ? I extends Model
-          ? never
-          : K
-        : T[K] extends Function
-          ? never
-          : K;
-  }[keyof T],
-  undefined | ModelTypeMembers
->;
+export type ModelProps<T extends Model> = InsertablePropertyNames<T>;
 
 /**
- * Extracts the relation names of the a model class.
+ * Extracts the relation names of a model class.
  */
-export type ModelRelations<T extends Model> = Defined<
-  {
-    [K in keyof T]?: Defined<T[K]> extends Model
-      ? K
-      : Defined<T[K]> extends Array<infer I>
-        ? I extends Model
-          ? K
-          : never
-        : never;
-  }[keyof T]
->;
+export type ModelRelations<T extends Model> = RelationPropertyNames<T>;
 
 /**
- * Given a model property type, returns a query builer type of
+ * Given a model property type, returns a query builder type of the
  * correct kind if the property is a model or a model array. Queries for
  * to-one relations resolve to `undefined` when there's no related row.
  */
@@ -760,6 +739,18 @@ type Rebind<
  */
 export type ExtraType<T extends { ExtraType: any }> = T['ExtraType'];
 
+/**
+ * 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;
+}
+
 type WithExtra<QB extends AnyQueryBuilder, X> = Rebind<QB, ModelType<QB>, ResultType<QB>, X>;
 
 // The narrowed query builders of `withGraph*()` start without the extra type
@@ -792,15 +783,16 @@ export type NumberQueryBuilder<QB extends AnyQueryBuilder> = QB['~number'];
  */
 export type PageQueryBuilder<QB extends AnyQueryBuilder> = QB['~page'];
 
-// Strict mode checks the column names and values of queries against the
-// models. Augment `TypeConfig` to opt in:
-//
-//   declare module 'objection' {
-//     interface TypeConfig {
-//       strict: true;
-//     }
-//   }
-
+/**
+ * Strict mode checks the column names and values of queries against the
+ * models. Augment `TypeConfig` to opt in:
+ *
+ *   declare module 'objection' {
+ *     interface TypeConfig {
+ *       strict: true;
+ *     }
+ *   }
+ */
 export interface TypeConfig {}
 
 type IsStrict = TypeConfig extends { strict: true } ? true : false;
@@ -919,10 +911,11 @@ type CheckedColumn<M, C extends string> =
   IsConcreteModel<M> extends true ? CheckColumn<M, C> : string;
 
 /**
- * A column argument: checked against model M in strict mode, any column in
- * loose mode, where the model's properties come first, for autocompletion.
+ * A column argument: checked against model M in strict mode, the model's
+ * properties in loose mode, for autocompletion. In loose mode, other columns
+ * go through the RefArg overloads.
  */
-type ColumnArg<M, C extends string> = IfStrict<ModelProps<M & Model>, CheckedColumn<M, C>>;
+type ColumnArg<M, C extends string> = IfStrict<InsertablePropertyNames<M>, CheckedColumn<M, C>>;
 
 /**
  * The value of a column of type T in conditions: `null` is always accepted,
@@ -1071,8 +1064,8 @@ type StrictSelectionObject<M, O> = {
 /**
  * The query builder QB with its result rows narrowed to the properties P in
  * strict mode, next to the model's methods and relations, as after `select()`
- * and the aggregates, marked with SelectedBrand. Repeated selections add up. Queries
- * that aren't checked, e.g. in generic code, aren't narrowed.
+ * and the aggregates, marked with SelectedBrand. Repeated selections add up.
+ * Queries that aren't checked, e.g. in generic code, aren't narrowed.
  */
 type NarrowRows<QB extends AnyQueryBuilder, P, All extends boolean = false> = RowsQueryBuilder<
   QB,
@@ -1127,7 +1120,7 @@ type ExtractedProperties<M, A extends string> = {
 type SelectQueryBuilder<QB extends AnyQueryBuilder, C extends readonly unknown[]> = NarrowRows<
   QB,
   SelectedRow<ModelType<QB>, C>,
-  true extends SelectsAll<C[number]> ? true : false
+  true extends IsSelectAll<C[number]> ? true : false
 >;
 
 /**
@@ -1188,18 +1181,6 @@ 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 =
@@ -1220,7 +1201,7 @@ type SelectBase<Item, M, All extends boolean> = All extends true
 // unknown types, under any aliases.
 type UnknownSelection = { [key: string]: unknown } & SelectedBrand<{ [key: string]: true }>;
 
-type SelectsAll<X> = X extends '*' | `${string}.*` ? true : false;
+type IsSelectAll<X> = X extends '*' | `${string}.*` ? true : false;
 
 /**
  * Replaces the item of the result R with the row.
@@ -1265,9 +1246,9 @@ type SelectedType<M, C extends string> = C extends `${infer Q}.${infer Col}`
   : ColumnType<M, C>;
 
 /**
- * The property of the column or alias C in the result rows: `snakeCaseMappers()`
- * converts them to camel case, with `upperCase: true` after lowering the case
- * of names in upper case.
+ * The property of the column or alias C in the result rows:
+ * `snakeCaseMappers()` converts them to camel case, with `upperCase: true`
+ * after lowering the case of names in upper case.
  */
 type ResultKey<M, C extends string> = M extends { ColumnNameMapping: 'snakeCase' }
   ? CamelCase<C>
@@ -1332,9 +1313,9 @@ type CheckRelationExpression<M, E, QB extends AnyQueryBuilder = never> = IfStric
 
 type CheckModifierExpression<E, QB extends AnyQueryBuilder> =
   HasQueryClass<QB> extends true
-    ? [CheckedModifiers<E, QB>] extends [never]
+    ? [UnknownExpressionModifiers<E, QB>] extends [never]
       ? unknown
-      : { '~unknownModifier': CheckedModifiers<E, QB> }
+      : { '~unknownModifier': UnknownExpressionModifiers<E, QB> }
     : unknown;
 
 // Queries in generic code, where the model class can't be resolved, aren't
@@ -1347,7 +1328,7 @@ type HasQueryClass<QB extends AnyQueryBuilder> =
       : true;
 
 // Only expressions with modifiers are checked for them.
-type CheckedModifiers<E, QB> = E extends `${string}(${string}` | object
+type UnknownExpressionModifiers<E, QB> = E extends `${string}(${string}` | object
   ? UnknownModifiers<
       ClassMappings<QueryClass<QB>>,
       ParseModifierExpression<E>,
@@ -1424,17 +1405,17 @@ type PropertyId<M, C extends string, F> =
 
 // Modifiers with their general type, e.g. inherited from `Model`, aren't
 // checked.
-type ChecksModifiers<QB extends AnyQueryBuilder> = IfStrict<
+type ShouldCheckModifiers<QB extends AnyQueryBuilder> = IfStrict<
   false,
-  HasQueryClass<QB> extends true ? ChecksClassModifiers<ClassModifiers<QueryClass<QB>>> : false
+  HasQueryClass<QB> extends true ? HasOnlyLiteralKeys<ClassModifiers<QueryClass<QB>>> : false
 >;
 
-type ChecksClassModifiers<O> = string extends keyof O ? false : true;
+type HasOnlyLiteralKeys<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;
+  ShouldCheckModifiers<QB> extends true ? keyof KnownModifiers<QB> & string : string;
 
 type ModifyArg<QB extends AnyQueryBuilder> =
   | ModifierName<QB>
@@ -1450,7 +1431,7 @@ type UnknownModifiers<Mappings, T, P> = T extends unknown
         ? MappedClass<Mappings, K> extends infer C
           ? [C] extends [never]
             ? never
-            : | (ChecksClassModifiers<ClassModifiers<C>> extends true
+            : | (HasOnlyLiteralKeys<ClassModifiers<C>> extends true
                   ? Exclude<N, keyof ClassModifiers<C> | P>
                   : never)
               | UnknownModifiers<ClassMappings<C>, Children, P>
@@ -1460,15 +1441,16 @@ type UnknownModifiers<Mappings, T, P> = T extends unknown
   : 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
+type MappedClass<Mappings, K> =
+  HasOnlyLiteralKeys<Mappings> extends true
+    ? 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
     : never;
 
@@ -1510,28 +1492,29 @@ type ModifierNode<S extends string, Children> = [RelationName<S>] extends [never
 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]
+type ParseModifierObject<E> =
+  HasOnlyLiteralKeys<E> extends true
+    ? {
+        [
+          K in keyof E as K extends `$${string}`
             ? never
-            : E[K] extends { $relation: any }
+            : false extends E[K]
               ? 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]> : {};
-      };
-    };
+              : 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>;
@@ -1547,22 +1530,24 @@ export type JsonObjectOrFieldExpression = object | object[] | FieldExpression;
 export type Selection<QB extends AnyQueryBuilder> = ColumnRef | AnyQueryBuilder | CallbackVoid<QB>;
 
 export interface SelectMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
-  <QBP extends QB>(...columns: IfStrict<ModelProps<ModelType<QBP>>, never>[]): QB;
+  // The column overload comes first, for autocompletion, and last in strict
+  // mode, so that errors are reported for it:
+  <QBP extends QB, const C extends readonly [unknown, ...unknown[]]>(
+    ...columns: IfStrict<ModelProps<ModelType<QBP>>[], StrictSelections<ModelType<QBP>, C>>
+  ): IfStrict<QB, SelectQueryBuilder<QBP, C>>;
   <QBP extends QB>(columns: IfStrict<ModelProps<ModelType<QBP>>, never>[]): QB;
 
   <QBP extends QB>(...columns: IfStrict<Selection<QBP>, never>[]): QB;
   <QBP extends QB>(columns: IfStrict<Selection<QBP>, never>[]): QB;
 
-  // Allows things like `select(1)`, not sure if we should be more specific here?
-  <QBP extends QB>(...args: IfStrict<any, never>[]): QB;
-
-  <QBP extends QB, const C extends readonly unknown[] = []>(
-    ...columns: StrictSelections<ModelType<QBP>, C>
-  ): SelectQueryBuilder<QBP, C>;
   <QBP extends QB, const C extends readonly unknown[] = []>(
     columns: StrictSelections<ModelType<QBP>, C>,
   ): SelectQueryBuilder<QBP, C>;
+  // Allow anything else in loose mode, like `select(1)`. The last overload
+  // is what `Parameters<>` sees, so it takes the loose arguments:
+  <QBP extends QB, const C extends readonly unknown[] = []>(
+    ...columns: IfStrict<({} | null | undefined)[], StrictSelections<ModelType<QBP>, C>>
+  ): IfStrict<QB, SelectQueryBuilder<QBP, C>>;
 }
 
 export interface AsMethod<out QB extends AnyQueryBuilder> {
@@ -1584,7 +1569,7 @@ export interface JsonExtraction {
 
 // Extractions without an alias, or with several, add any properties.
 export interface JsonExtract<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never, const A extends string = string>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1605,7 +1590,7 @@ export interface JsonExtract<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonSet<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1617,7 +1602,7 @@ export interface JsonSet<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonInsert<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1629,7 +1614,7 @@ export interface JsonInsert<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonRemove<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1640,6 +1625,17 @@ export interface JsonRemove<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereMethod<out QB extends AnyQueryBuilder> {
+  // The column overloads come first, for autocompletion:
+  <QBP extends QB, const C extends string = never, const O extends Operator = Operator>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    op: O,
+    expr: OperatorValueArg<ModelType<QBP>, C, O>,
+  ): QB;
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: ValueArg<ModelType<QBP>, C>,
+  ): QB;
+
   (condition: boolean): QB;
   (cb: CallbackVoid<QB>): QB;
   (raw: Raw): QB;
@@ -1648,7 +1644,7 @@ export interface WhereMethod<out QB extends AnyQueryBuilder> {
   (col: RefArg<QB>, op: Operator, expr: Expression<PrimitiveValue>): QB;
   (col: RefArg<QB>, expr: Expression<PrimitiveValue>): QB;
 
-  // The column overloads come last, so that errors are reported for them.
+  // The column overloads come last, so that errors are reported for them:
   <QBP extends QB, const C extends string = never, const O extends Operator = Operator>(
     col: ColumnArg<ModelType<QBP>, C>,
     op: O,
@@ -1660,14 +1656,20 @@ export interface WhereMethod<out QB extends AnyQueryBuilder> {
   ): QB;
 
   <QBP extends QB>(obj: IfStrict<PartialModelProps<ModelType<QBP>>, never>): 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.
-  (obj: IfStrict<object, never>): QB;
-  <QBP extends QB, const O extends object = {}>(obj: O & StrictWhereObject<ModelType<QBP>, O>): QB;
+  // Allow any keys in loose mode. The model's properties above only serve
+  // autocompletion. The last overload is what `Parameters<>` sees:
+  <QBP extends QB, const O extends object = {}>(
+    obj: IfStrict<object, O & StrictWhereObject<ModelType<QBP>, O>>,
+  ): QB;
 }
 
 export interface WhereLikeMethod<out QB extends AnyQueryBuilder> {
+  // The column overload comes first, for autocompletion, and last, so that
+  // errors are reported for it:
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: Expression<string>,
+  ): QB;
   (col: RefArg<QB>, expr: Expression<string>): QB;
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
@@ -1688,13 +1690,12 @@ export interface WhereExistsMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereInMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
-  <QBP extends QB>(
-    col: IfStrict<ModelProps<ModelType<QBP>>, never>,
-    expr: Expression<PrimitiveValue>,
+  // The column overload comes first, for autocompletion, and last in strict
+  // mode, so that errors are reported for it:
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: IfStrict<Expression<PrimitiveValue> | CallbackVoid<QB>, WhereInValues<QB, QBP, C>>,
   ): QB;
-  <QBP extends QB>(col: IfStrict<ModelProps<ModelType<QBP>>, never>, cb: CallbackVoid<QB>): QB;
-  <QBP extends QB>(col: IfStrict<ModelProps<ModelType<QBP>>, never>, qb: AnyQueryBuilder): QB;
 
   (col: RefArg<QB> | RefArg<QB>[], expr: readonly Expression<PrimitiveValue>[]): QB;
   (col: RefArg<QB> | RefArg<QB>[], cb: CallbackVoid<QB>): QB;
@@ -1702,14 +1703,19 @@ export interface WhereInMethod<out QB extends AnyQueryBuilder> {
 
   <QBP extends QB, const C extends string = never>(
     col: StrictColumn<ModelType<QBP>, C>,
-    expr: readonly ValueArg<ModelType<QBP>, C>[] | Raw | AnyQueryBuilder | CallbackVoid<QB>,
+    expr: WhereInValues<QB, QBP, C>,
   ): QB;
+  // The last overload is what `Parameters<>` sees, so it takes the loose
+  // columns in loose mode:
   <QBP extends QB, const C extends readonly unknown[] = []>(
-    col: StrictColumns<ModelType<QBP>, C>,
+    col: IfStrict<RefArg<QB> | RefArg<QB>[], StrictColumns<ModelType<QBP>, C>>,
     expr: readonly Expression<PrimitiveValue>[] | Raw | AnyQueryBuilder | CallbackVoid<QB>,
   ): QB;
 }
 
+type WhereInValues<QB extends AnyQueryBuilder, QBP extends QB, C extends string> =
+  readonly ValueArg<ModelType<QBP>, C>[] | Raw | AnyQueryBuilder | CallbackVoid<QB>;
+
 export interface WhereBetweenMethod<out QB extends AnyQueryBuilder> {
   (column: RefArg<QB>, range: [Expression<PrimitiveValue>, Expression<PrimitiveValue>]): QB;
   <QBP extends QB, const C extends string = never>(
@@ -1724,7 +1730,7 @@ export interface WhereNullMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereColumnMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never, const D extends string = never>(
     col1: ColumnArg<ModelType<QBP>, C>,
     op: Operator,
@@ -1747,7 +1753,7 @@ export interface WhereColumnMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereJsonObject<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
     value: any,
@@ -1757,7 +1763,7 @@ export interface WhereJsonObject<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereJsonPath<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
     jsonPath: string,
@@ -2114,7 +2120,7 @@ type WriteQueryBuilder<QB extends AnyQueryBuilder, M extends Model, R> = [R] ext
  * The writes after `returning()` on single and maybe-single query builders,
  * which resolve to one row.
  */
-interface ReturningWrites<QB extends AnyQueryBuilder, M extends Model, W> {
+export interface ReturningWrites<QB extends AnyQueryBuilder, M extends Model, W> {
   update(update: PartialModelRow<M>): Rebind<QB, M, W>;
   update(): Rebind<QB, M, W>;
   patch(update: PartialModelPatch<M>): Rebind<QB, M, W>;
@@ -2239,7 +2245,8 @@ export interface GraphOptions {
   maxBatchSize?: number;
   /**
    * Apply `limit()`, `offset()` and `first()` in graph modifiers to the related
-   * items of each parent. Defaults to `true`. Only applies to `withGraphFetched()`.
+   * items of each parent. Defaults to `true`. Only applies to
+   * `withGraphFetched()`.
    */
   limitPerParent?: boolean;
 }
@@ -2706,8 +2713,6 @@ export class QueryBuilder<
   ): Promise<R | FR>;
 }
 
-export type X<T> = Promise<T>;
-
 export interface FetchGraphOptions {
   transaction?: TransactionOrKnex;
   skipFetched?: boolean;
@@ -2807,11 +2812,11 @@ export interface BelongsToManyRelationType extends RelationType {
  * Names of the properties of M that hold related models. Properties typed
  * `any` or `any[]` are columns.
  */
-export type RelationPropertyNames<M> = {
-  [K in keyof M]-?: HoldsModels<NonNullable<M[K]>> extends true ? K : never;
+type RelationPropertyNames<M> = {
+  [K in keyof M]-?: HasModels<NonNullable<M[K]>> extends true ? K : never;
 }[keyof M];
 
-type HoldsModels<P> = [P] extends [readonly (infer I)[]] ? IsModelLike<I> : IsModelLike<P>;
+type HasModels<P> = [P] extends [readonly (infer I)[]] ? IsModelLike<I> : IsModelLike<P>;
 
 type IsModelLike<P> = 0 extends 1 & P ? false : [P] extends [ModelLike] ? true : false;
 
@@ -2820,7 +2825,7 @@ type IsModelLike<P> = 0 extends 1 & P ? false : [P] extends [ModelLike] ? true :
 // Spreads of instances and their JSON don't have it.
 type ModelLike = { $clone(opt?: CloneOptions): unknown };
 
-export type TypedModelClassSpecifier<M extends Model> =
+type TypedModelClassSpecifier<M extends Model> =
   string | ModelConstructor<M> | (() => ModelConstructor<M>);
 
 /**
@@ -2834,7 +2839,7 @@ export interface TypedRelationMapping<
   modelClass: TypedModelClassSpecifier<M>;
 }
 
-export type TypedRelationMappingFor<T> =
+type TypedRelationMappingFor<T> =
   NonNullable<T> extends (infer I extends Model)[]
     ? TypedRelationMapping<
         I,
@@ -2951,7 +2956,7 @@ export interface SnakeCaseMappersOptions extends SnakeCaseOptions {
 
 export interface KnexSnakeCaseMappersOptions extends SnakeCaseOptions {}
 
-export type JsonColumnFormat = 'auto' | 'text' | 'parsed';
+export type JsonColumnFormat = 'auto' | 'json' | 'text' | 'mixed';
 
 // Passed by queries to `fromDatabaseJson()`, `$setDatabaseJson()` and
 // `$parseDatabaseJson()`. Overrides pass them on to `super`.
@@ -3055,7 +3060,8 @@ export 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
+// Used internally to infer the generic static `this`, copied from:
+// https://github.com/microsoft/TypeScript/issues/5863#issuecomment-1483978415
 export type ConstructorType<T = unknown, Static extends Record<string, any> = PrototypeType<T>> = (
   ConstructorFunctionType<T> | PrototypeType<T>
 ) & {
@@ -3132,7 +3138,7 @@ export interface ModelClass<M extends Model> extends ModelConstructor<M> {
 
   transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<T>;
   transaction<T>(
-    trxOrKnex: TransactionOrKnex,
+    trxOrKnex: TransactionOrKnex | undefined,
     callback: (trx: Transaction) => Promise<T>,
   ): Promise<T>;
 
@@ -3630,13 +3636,14 @@ type ModelSchemaProperties<S> = ReadonlyJSONSchema extends S
 
 // 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]
-      >;
-    };
+type ModelRelationProperties<T, R = T extends () => infer M ? M : T> =
+  HasOnlyLiteralKeys<R> extends true
+    ? {
+        -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 }