feat: add lazy relationship loading feature (#44)

Author: kiaking

docs/guide/relationships/getting-started.md

@@ -120,6 +120,59 @@ const users = store.$repo(User).with('posts', (query) => {
 }).get()
 ```
 
+### Lazy Relatinship Loading
+
+Sometimes you may need to load a relationship after the model has already been retrieved. For example, this may be useful if you need to dynamically decide whether to load related models. You may use `load` method on a repository to load relationships on the fly in such a case.
+
+```js
+const userRepo = store.$repo(User)
+
+// Retrieve models without relationships.
+const users = userRepo.get()
+
+// Load relationships on the fly.
+userRepo.with('posts').load(users)
+```
+
+You may set any additional query constraints as usual to the `with` method.
+
+```js
+userRepo.with('posts', (query) => {
+  query.orderBy('createdAt', 'desc')
+}).load(users)
+```
+
+Note that the `load` method will mutate the given models. It would be safer to use the method within a single `computed` method.
+
+```js
+import { mapRepos } from '@vuex-orm/core'
+import User from '@/models/User'
+
+export default {
+  data () {
+    return {
+      condition: false
+    }
+  },
+
+  computed: {
+    ...mapRepos({
+      userRepo: User
+    }),
+
+    users () {
+      const users = this.userRepo.get()
+
+      if (this.condition) {
+        this.userRepo.with('posts').load(users)
+      }
+
+      return users
+    }
+  }
+}
+```
+
 ## 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:

docs/guide/repository/getting-started.md

@@ -51,12 +51,12 @@ export default {
 
 ### Map Repositories Helper
 
-In addition to use `this.$store.$repo` to retrieve repositories, Vuex ORM provides a convenience helper function called `mapRepositories` to retrieve multiple repositories at once.
+In addition to use `this.$store.$repo` to retrieve repositories, Vuex ORM provides a convenience helper function called `mapRepos` to retrieve multiple repositories at once.
 
 The `mapRepos` helper will receive a list of models with its name as a key. The repositories is going to be injected to the `this` context within Vue Component.
 
 ```js
-import { mapRepositories } from '@vuex-orm/core'
+import { mapRepos } from '@vuex-orm/core'
 import User from '@/models/User'
 import Post from '@/models/Post'
 

src/model/Model.ts

@@ -584,6 +584,10 @@ export class Model {
   protected serializeRelation(relation: Item): Element | null
   protected serializeRelation(relation: Collection): Element[]
   protected serializeRelation(relation: any): any {
+    if (relation === undefined) {
+      return undefined
+    }
+
     if (relation === null) {
       return null
     }

src/query/Query.ts

@@ -328,6 +328,13 @@ export class Query<M extends Model = Model> {
       : models.slice(this.skip)
   }
 
+  /**
+   * Eager load relations on the model.
+   */
+  load(models: Collection<M>): void {
+    this.eagerLoadRelations(models)
+  }
+
   /**
    * Eager load the relationships for the models.
    */

test/feature/relations/lazy_loads/lazy_eager_load.spec.ts

@@ -0,0 +1,55 @@
+import { createStore, fillState, assertModels } from 'test/Helpers'
+import { Model, Attr, Str, HasMany } from '@/index'
+
+describe('feature/relations/lazy_loads/lazy_eager_load', () => {
+  class User extends Model {
+    static entity = 'users'
+
+    @Attr() id!: number
+    @Str('') name!: string
+
+    @HasMany(() => Post, 'userId')
+    posts!: Post[]
+  }
+
+  class Post extends Model {
+    static entity = 'posts'
+
+    @Attr() id!: number
+    @Attr() userId!: number
+    @Str('') title!: string
+  }
+
+  it('can lazy eager load relations', async () => {
+    const store = createStore()
+
+    fillState(store, {
+      users: {
+        1: { id: 1, name: 'John Doe' }
+      },
+      posts: {
+        1: { id: 1, userId: 1, title: 'Title 01' },
+        2: { id: 2, userId: 1, title: 'Title 02' }
+      }
+    })
+
+    const userRepo = store.$repo(User)
+
+    const users = userRepo.all()
+
+    assertModels(users, [{ id: 1, name: 'John Doe' }])
+
+    userRepo.with('posts').load(users)
+
+    assertModels(users, [
+      {
+        id: 1,
+        name: 'John Doe',
+        posts: [
+          { id: 1, userId: 1, title: 'Title 01' },
+          { id: 2, userId: 1, title: 'Title 02' }
+        ]
+      }
+    ])
+  })
+})