feat: instance hydration control

docs: added examples to reflect this feat
test: added coverage test

Author: cuebit

docs/api/model.md

@@ -31,10 +31,12 @@ sidebarDepth: 2
 
 ### `$softDelete`
 
-- **Type**: `() => Promise`
+- **Type**: `(hydrate?: boolean) => Promise`
 
-  Soft delete the model instance. Updates the `key` and `flagName` attribute values accordingly.
+  Soft delete the model instance. By default, this updates only the `key` and `flagName` attribute values on the instance after they are persisted to the store.
 
+  Passing `hydrate` as `true` will also hydrate the given instance. This is useful where there may be `beforeUpdate`/`afterUpdate` hooks on the model that may mutate other values or to simply update instance with the latest data from the store. However, if the instance has any relation attributes loaded through `with`, they will be reset during hydration.
+  
   Returns a Promise that resolves with the soft deleted model.
 
 ### `$trashed`

docs/guide/usage.md

@@ -19,18 +19,24 @@ if (user.$trashed()) {
 Models can be soft deleted by calling `softDelete` directly:
 
 ```js
-User.softDelete(1)
+await User.softDelete(1)
 ```
 
-Model instances can be soft deleted by calling `$softDelete` on the model instance:
+Model instances can be soft deleted by calling `$softDelete` on the instance itself:
 
 ```js
 const user = User.find(1)
 
-user.$softDelete()
+await user.$softDelete()
+```
+
+The `$softDelete` instance method also accepts a `boolean` argument which can force hydration:
+
+```js
+await user.$softDelete(true)
 ```
 
-Both methods are asynchronous and return a Promise.
+**See also**: [API Reference](/api/model.md#softdelete-2)
 
 ### Primary Key
 

src/mixins/Model.ts

@@ -47,36 +47,42 @@ export default function Model(
   /**
    * Trash the record on a model instance.
    */
-  model.prototype.$softDelete = async function() {
-    const record = await this.$dispatch(
+  model.prototype.$softDelete = async function(hydrate?) {
+    const model = await this.$dispatch(
       'softDelete',
       this.$self().getIdFromRecord(this)
     )
 
+    if (hydrate) {
+      this.$fill(model.$getAttributes())
+
+      return this
+    }
+
     const { key, flagName } = context.createConfig(
       this.$self().softDeleteConfig
     )
 
-    this[key] = record[key]
-    this[flagName] = record[flagName]
+    this[key] = model[key]
+    this[flagName] = model[flagName]
 
-    return record
+    return model
   }
 
   /**
    * Trash the record on a model instance.
    * This method is deprecated and will warn users until retired.
    * @deprecated since v1.2.0
    */
-  model.prototype.softDelete = function() {
+  model.prototype.softDelete = function(hydrate?) {
     /* istanbul ignore next */
     if (process.env.NODE_ENV !== 'production') {
       console.warn(
         'The `softDelete` instance method has been deprecated. Please use `$softDelete`.'
       )
     }
 
-    return this.$softDelete()
+    return this.$softDelete(hydrate)
   }
 
   /**

src/types/vuex-orm.ts

@@ -32,13 +32,13 @@ declare module '@vuex-orm/core' {
     /**
      * Trash the record on a model instance.
      */
-    $softDelete(): Promise<Data.Item<this>>
+    $softDelete(hydrate?: boolean): Promise<Data.Item<this>>
 
     /**
      * Trash the record on a model instance.
      * @deprecated since v1.2.0
      */
-    softDelete(): Promise<Data.Item<this>>
+    softDelete(hydrate?: boolean): Promise<Data.Item<this>>
 
     /**
      * Determine if the instance has been trashed.

test/feature/model/Delete.spec.ts

@@ -294,4 +294,56 @@ describe('Feature - Model - Delete', () => {
     expect(user.$isDeleted).toBe(true)
     expect(user.deleted_at).toBe(mockDate)
   })
+
+  it('should hydrate instance after deleting', async () => {
+    class User extends Model {
+      static entity = 'users'
+
+      name!: string
+      post!: Post
+      deleted_at!: number
+      $isDeleted!: boolean
+
+      static fields() {
+        return {
+          id: this.attr(null),
+          name: this.attr(''),
+          post: this.hasOne(Post, 'user_id')
+        }
+      }
+
+      static beforeUpdate(model: User) {
+        model.name = 'Jane Doe'
+      }
+    }
+
+    class Post extends Model {
+      static entity = 'posts'
+
+      static fields() {
+        return {
+          id: this.attr(null),
+          user_id: this.attr(null)
+        }
+      }
+    }
+
+    createStore([User, Post])
+
+    await User.insert({
+      data: { id: 1, name: 'John Doe', post: [{ id: 2 }, { id: 3 }] }
+    })
+
+    const user = User.query().with('post').find(1) as User
+
+    expect(user.name).toBe('John Doe')
+    expect(user.post).toBeInstanceOf(Post)
+
+    await user.$softDelete(true)
+
+    expect(user.$isDeleted).toBe(true)
+    expect(user.deleted_at).toBe(mockDate)
+    expect(user.name).toBe('Jane Doe')
+    expect(user.post).toBeNull()
+  })
 })