Typings: allow $relatedQuery to be strongly typed without a cast (#709)

* Use keyof to infer relation types

Author: mceachen

tests/ts/examples.ts

@@ -13,15 +13,22 @@ const {lit, raw, ref} = objection;
 class Person extends objection.Model {
   firstName: string;
   lastName: string;
+  mom: Person;
+  comments: Comment[]
 
   static columnNameMappers = objection.snakeCaseMappers();
 
   examplePersonMethod = (arg: string) => 1;
 
-  async petsWithId(petId: number): Promise<Animal[]> {
-    // Types can't look at strings and give strong types, so <Animal> needs
-    // to be provided to $relatedQuery
-    return await this.$relatedQuery<Animal>('pets').where('id', petId);
+  // $relatedQuery can either take a cast, if you don't want to add the field
+  // to your model:
+  petsWithId(petId: number): Promise<Animal[]> {
+    return this.$relatedQuery<Animal>('pets').where('id', petId);
+  }
+
+  // Or, if you add the field, this.$relatedQuery just works:
+  fetchMom(): Promise<Person> {
+    return this.$relatedQuery('mom')
   }
 
   async $beforeInsert(queryContext: objection.QueryContext) {
@@ -109,6 +116,8 @@ async () => {
 
 class Movie extends objection.Model {
   title: string;
+  actors: Person[];
+
   /**
    * This static field instructs Objection how to hydrate and persist
    * relations. By making relationMappings a thunk, we avoid require loops
@@ -130,6 +139,11 @@ class Movie extends objection.Model {
   });
 }
 
+async () => {
+  // Another example of strongly-typed $relatedQuery without a cast:
+  takesPeople(await new Movie().$relatedQuery("actors"));
+}
+
 class Animal extends objection.Model {
   species: string;
 

typings/objection/index.d.ts

@@ -106,7 +106,7 @@ declare namespace Objection {
     json: Pojo;
     options: ModelOptions;
   }
-  
+
   export class Validator {
     beforeValidate(args: ValidatorArgs): void;
     validate(args: ValidatorArgs): Pojo;
@@ -128,7 +128,7 @@ declare namespace Objection {
     data: any;
     message: string;
   }
-  
+
   export interface ErrorHash {
     [columnName: string]: ValidationError[];
   }
@@ -446,17 +446,28 @@ declare namespace Objection {
     $query(trxOrKnex?: Transaction | knex): QueryBuilderSingle<this>;
 
     /**
-     * Users need to explicitly type these calls, as the relationName doesn't
-     * indicate the type (and if it returned Model directly, Partial<Model>
-     * guards are worthless)
+     * If you add model relations as fields, $relatedQuery works
+     * automatically:
+     */
+    $relatedQuery<K extends keyof this>(
+      relationName: K,
+      trxOrKnex?: Transaction | knex
+    ): QueryBuilderSingle<this[K]>;
+
+    // PLEASE NOTE: `$relatedQuery<K extends keyof this>` MUST BE DEFINED
+    // BEFORE `$relatedQuery<M extends Model>`!
+
+    /**
+     * If you don't want to add the fields to your model, you can cast the
+     * call to the expected Model subclass (`$relatedQuery<Animal>('pets')`).
      */
     $relatedQuery<M extends Model>(
       relationName: string,
       trxOrKnex?: Transaction | knex
     ): QueryBuilder<M>;
 
     $loadRelated<T>(
-      expression: RelationExpression,
+      expression: keyof this | RelationExpression,
       filters?: Filters<T>,
       trxOrKnex?: Transaction | knex
     ): QueryBuilderSingle<this>;