feat: add eager load constraints feature

Author: kiaking

docs/guide/relationships/getting-started.md

@@ -90,6 +90,36 @@ Of course, you may chain more than one `with(...)` method to retrieve multiple r
 const user = store.$repo(User).with('posts').with('phone').first()
 ```
 
+### Loading Nested Relationships
+
+To load nested relationships, you may pass constraints to the 2nd argument. For example, let's load all of the book's authors and all of the author's personal contacts:
+
+```js
+const books = store.$repo(Book).with('author', (query) => {
+  query.with('contacts')
+}).get()
+```
+
+Learn more about the constraining query in the next section.
+
+### Constraining a Relationship Query
+
+Sometimes you may wish to load a relationship, but also specify additional query conditions for the loading query. Here's an example:
+
+```js
+const users = store.$repo(User).with('posts', (query) => {
+  query.where('published', true)
+}).get()
+```
+
+In this example, it will only load posts where the post's `published` filed matches the `true` first. You may call other query builder methods to further customize the loading operation:
+
+```js
+const users = store.$repo(User).with('posts', (query) => {
+  query.orderBy('createdAt', 'desc')
+}).get()
+```
+
 ## Inserting Relationships
 
 When inserting new records into the store, Vuex ORM automatically normalizes and stores data that contains any nested relationships in it's data structure. For example, let's say you have the `User` model that has a relationship to the `Post` model:

src/query/Options.ts

@@ -1,21 +1,19 @@
 import { Model } from '../model/Model'
 import { Query } from './Query'
 
-export interface Where<M extends Model, K extends keyof M> {
-  field: WherePrimaryClosure<M> | K
-  value: WhereSecondaryClosure<M, K> | M[K] | M[K][]
+export interface Where {
+  field: WherePrimaryClosure | string
+  value: WhereSecondaryClosure | any
   boolean: 'and' | 'or'
 }
 
-export type WherePrimaryClosure<M extends Model> = (model: M) => boolean
+export type WherePrimaryClosure = (model: any) => boolean
 
-export type WhereSecondaryClosure<M extends Model, K extends keyof M> = (
-  value: M[K]
-) => boolean
+export type WhereSecondaryClosure = (value: any) => boolean
 
-export interface WhereGroup<M extends Model, K extends keyof M> {
-  and?: Where<M, K>[]
-  or?: Where<M, K>[]
+export interface WhereGroup {
+  and?: Where[]
+  or?: Where[]
 }
 
 export interface Order<M extends Model> {

src/query/Query.ts

@@ -60,7 +60,7 @@ export class Query<M extends Model = Model> {
   /**
    * The where constraints for the query.
    */
-  protected wheres: Where<M, any>[] = []
+  protected wheres: Where[] = []
 
   /**
    * The orderings for the query.
@@ -110,9 +110,9 @@ export class Query<M extends Model = Model> {
   /**
    * Add a basic where clause to the query.
    */
-  where<T extends keyof M>(
-    field: WherePrimaryClosure<M> | T,
-    value?: WhereSecondaryClosure<M, T> | M[T] | M[T][]
+  where(
+    field: WherePrimaryClosure | string,
+    value?: WhereSecondaryClosure | any
   ): this {
     this.wheres.push({ field, value, boolean: 'and' })
 
@@ -122,7 +122,7 @@ export class Query<M extends Model = Model> {
   /**
    * Add a "where in" clause to the query.
    */
-  whereIn<T extends keyof M>(field: T, values: M[T][]): this {
+  whereIn(field: string, values: any[]): this {
     this.wheres.push({ field, value: values, boolean: 'and' })
 
     return this
@@ -138,9 +138,9 @@ export class Query<M extends Model = Model> {
   /**
    * Add an "or where" clause to the query.
    */
-  orWhere<T extends keyof M>(
-    field: WherePrimaryClosure<M> | T,
-    value?: WhereSecondaryClosure<M, T> | M[T] | M[T][]
+  orWhere(
+    field: WherePrimaryClosure | string,
+    value?: WhereSecondaryClosure | any
   ): this {
     this.wheres.push({ field, value, boolean: 'or' })
 
@@ -177,8 +177,8 @@ export class Query<M extends Model = Model> {
   /**
    * Set the relationships that should be eager loaded.
    */
-  with(name: string): Query<M> {
-    this.eagerLoad[name] = () => {}
+  with(name: string, callback: EagerLoadConstraint = () => {}): Query<M> {
+    this.eagerLoad[name] = callback
 
     return this
   }
@@ -302,7 +302,7 @@ export class Query<M extends Model = Model> {
   /**
    * The function to compare where clause to the given model.
    */
-  protected whereComparator(model: M, where: Where<M, any>): boolean {
+  protected whereComparator(model: M, where: Where): boolean {
     if (isFunction(where.field)) {
       return where.field(model)
     }

src/repository/Repository.ts

@@ -9,7 +9,8 @@ import {
   WherePrimaryClosure,
   WhereSecondaryClosure,
   OrderDirection,
-  OrderBy
+  OrderBy,
+  EagerLoadConstraint
 } from '../query/Options'
 
 export class Repository<M extends Model = Model> {
@@ -101,19 +102,19 @@ export class Repository<M extends Model = Model> {
   /**
    * Add a basic where clause to the query.
    */
-  where<T extends keyof M>(
-    field: WherePrimaryClosure<M> | T,
-    value?: WhereSecondaryClosure<M, T> | M[T] | M[T][]
+  where(
+    field: WherePrimaryClosure | string,
+    value?: WhereSecondaryClosure | any
   ): Query<M> {
     return this.query().where(field, value)
   }
 
   /**
    * Add an "or where" clause to the query.
    */
-  orWhere<T extends keyof M>(
-    field: WherePrimaryClosure<M> | T,
-    value?: WhereSecondaryClosure<M, T> | M[T] | M[T][]
+  orWhere(
+    field: WherePrimaryClosure | string,
+    value?: WhereSecondaryClosure | any
   ): Query<M> {
     return this.query().orWhere(field, value)
   }
@@ -142,8 +143,8 @@ export class Repository<M extends Model = Model> {
   /**
    * Set the relationships that should be eager loaded.
    */
-  with(name: string): Query<M> {
-    return this.query().with(name)
+  with(name: string, callback?: EagerLoadConstraint): Query<M> {
+    return this.query().with(name, callback)
   }
 
   /**

test/feature/relations/constraints/constraints.spec.ts

@@ -0,0 +1,93 @@
+import { createStore, fillState } from 'test/Helpers'
+import { Model, Attr, Str, HasOne } from '@/index'
+
+describe('feature/relations/constraints/constraints', () => {
+  class User extends Model {
+    static entity = 'users'
+
+    @Attr() id!: number
+    @Str('') name!: string
+
+    @HasOne(() => Phone, 'userId')
+    phone!: Phone | null
+  }
+
+  class Phone extends Model {
+    static entity = 'phones'
+
+    @Attr() id!: number
+    @Attr() userId!: number
+    @Str('') number!: string
+
+    @HasOne(() => Type, 'phoneId')
+    type!: Type | null
+  }
+
+  class Type extends Model {
+    static entity = 'types'
+
+    @Attr() id!: number
+    @Attr() phoneId!: number
+    @Str('') name!: string
+  }
+
+  it('can add constraints to the relationship query', async () => {
+    const store = createStore()
+
+    fillState(store, {
+      users: {
+        1: { id: 1, name: 'John Doe' },
+        2: { id: 2, name: 'Jane Doe' },
+        3: { id: 3, name: 'Johnny Doe' }
+      },
+      phones: {
+        1: { id: 1, userId: 1, number: '123' },
+        2: { id: 2, userId: 2, number: '345' },
+        3: { id: 3, userId: 3, number: '789' }
+      }
+    })
+
+    const users = store
+      .$repo(User)
+      .with('phone', (query) => {
+        query.where('number', '345')
+      })
+      .get()
+
+    expect(users[0].phone).toBe(null)
+    expect(users[1].phone!.number).toBe('345')
+    expect(users[2].phone).toBe(null)
+  })
+
+  it('can load nested relationships', async () => {
+    const store = createStore()
+
+    fillState(store, {
+      users: {
+        1: { id: 1, name: 'John Doe' },
+        2: { id: 2, name: 'Jane Doe' },
+        3: { id: 3, name: 'Johnny Doe' }
+      },
+      phones: {
+        1: { id: 1, userId: 1, number: '123' },
+        2: { id: 2, userId: 2, number: '345' },
+        3: { id: 3, userId: 3, number: '789' }
+      },
+      types: {
+        1: { id: 1, phoneId: 1, name: 'iPhone' },
+        2: { id: 2, phoneId: 2, name: 'Android' }
+      }
+    })
+
+    const users = store
+      .$repo(User)
+      .with('phone', (query) => {
+        query.with('type')
+      })
+      .get()
+
+    expect(users[0].phone!.type!.id).toBe(1)
+    expect(users[1].phone!.type!.id).toBe(2)
+    expect(users[2].phone!.type).toBe(null)
+  })
+})