objection 3.2.0 → 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>
@@ -35,13 +35,15 @@ declare namespace Objection {
   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 {}
 
@@ -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.
    */
@@ -209,6 +421,16 @@ declare namespace Objection {
         : 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.
    */
@@ -343,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;
 
@@ -442,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.
@@ -710,10 +932,15 @@ declare namespace Objection {
     (): ModelClass<M>;
   }
 
+  interface ReturningOptions {
+    includeTriggerModifications?: boolean;
+  }
+
   interface ReturningMethod {
     <QB extends AnyQueryBuilder>(
       this: QB,
       column: string | Raw | (string | Raw)[] | readonly (string | Raw)[],
+      options?: ReturningOptions,
     ): QB extends NumberQueryBuilder<QB> ? ArrayQueryBuilder<QB> : QB;
   }
 
@@ -824,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>>,
@@ -1057,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,
@@ -1065,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,
@@ -1094,8 +1327,20 @@ 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>;
@@ -1169,6 +1414,7 @@ declare namespace Objection {
     isRelate: BooleanReturningMethod;
     isUnrelate: BooleanReturningMethod;
     isInternal: BooleanReturningMethod;
+    isJoinChildQuery: BooleanReturningMethod;
     hasWheres: BooleanReturningMethod;
     hasSelects: BooleanReturningMethod;
     hasWithGraph: BooleanReturningMethod;
@@ -1346,6 +1592,12 @@ declare namespace Objection {
     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 {
@@ -1526,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;
@@ -1641,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>(
+    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>(
+    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;
@@ -1697,10 +1949,10 @@ 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;
@@ -1758,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>;