wip: working on

Author: kiaking

docs/guide/repository/deleting-data.md

@@ -37,14 +37,14 @@ The `destroy` method will return deleted models. When you pass a single primary
 ```js
 const user = await store.$repo(User).destroy(2)
 
-// { id: 2, name: 'Jane Doe', age: 30 }
+// User { id: 2, name: 'Jane Doe', age: 30 }
 
 const user = await store.$repo(User).destroy([1, 2])
 
 /*
   [
-    { id: 1, name: 'John Doe', age: 40 },
-    { id: 2, name: 'Jane Doe', age: 30 }
+    User { id: 1, name: 'John Doe', age: 40 },
+    User { id: 2, name: 'Jane Doe', age: 30 }
   ]
 */
 ```
@@ -55,7 +55,7 @@ If you wish to delete the entire records, you may use the `flush` method.
 store.$repo(User).flush()
 ```
 
-## Deleting data by query
+## Deleting Data By Query
 
 You can also run a delete statement on a set of records. In this example, we will delete all flights that are marked as inactive.
 

docs/guide/repository/getting-started.md

@@ -43,7 +43,7 @@ export default {
 
   methods: {
     saveUser (user) {
-      this.userRepo.insert(user)
+      this.userRepo.save(user)
     }
   }
 }

docs/guide/repository/inserting-data.md

@@ -23,106 +23,90 @@ store.$repo(User).save([
 
 The `save` method will "normalize" the given data. That means if you pass an object that contains any nested relationships, those relationships are also inserted. Please see [Relationships: Getting Started](../relationships/getting-started.md#inserting-relationships) for more details about data normalization.
 
-### Return Value From The `save` method
-
-The `save` method returns the original data which was passed in, with primary key fields getting populated. You may think of this object as a "schema" of the saved data. Let's go through examples to see how it works.
-
-When passing in data with a correct primary key, it returns the exact same object you passed.
+The `save` method returns new model instances.
 
 ```js
-const schema = store.$repo(User).save({ id: 1, name: 'John Doe' })
+const user = store.$repo(User).save({ id: 1, name: 'John Doe' })
 
 /*
-  { id: 1, name: 'John Doe' }
+  User { id: 1, name: 'John Doe' }
 */
+```
+
+When passing in an array of data, it returns an array of new model instances.
 
-// If you pass an array, it returns an array.
-const schema = store.$repo(User).save([
+```js
+const users = store.$repo(User).save([
   { id: 1, name: 'John Doe' },
   { id: 2, name: 'Jane Doe' }
 ])
 
 /*
   [
-    { id: 1, name: 'John Doe' },
-    { id: 2, name: 'Jane Doe' }
+    User { id: 1, name: 'John Doe' },
+    User { id: 2, name: 'Jane Doe' }
   ]
 */
 ```
 
-
-
-
-
-
-
-
-
-The repository provides an `insert` method for inserting records into the store. The `insert` method accepts an object of field and value pairs.
+If you insert data containing relationships, all of them would be instantiated as a new model istances and gets returned. Here is an example where a user "has many" posts.
 
 ```js
-store.$repo(User).insert({ id: 1, name: 'John Doe' })
-```
-
-You may also pass an array of objects to update multiple records at once.
-
-```js
-store.$repo(User).insert([
-  { id: 1, name: 'John Doe' },
-  { id: 2, name: 'Jane Doe' }
-])
-```
-
-The `insert` method will "normalize" the given data. That means if you pass an object that contains any nested relationships, those relationships are also updated. Please see [Relationships: Getting Started](../relationships/getting-started.md#inserting-relationships) for more details about data normalization.
-
-Because the `insert` method might insert records of multiple models, it will always return a collection of entities that have been updated.
-
-```js
-const entities = await store.$repo(User).insert({ id: 1, name: 'John Doe' })
+const user = store.$repo(User).save({
+  id: 1,
+  name: 'John Doe',
+  posts: [
+    { id: 1, userId: 1, title: 'Title A' },
+    { id: 2, userId: 2, title: 'Title B' }
+  ]
+})
 
 /*
-  {
-    users: [
-      { id:1, name: 'Jane Doe' }
+  User {
+    id: 1,
+    name: 'John Doe',
+    posts: [
+      Post { id: 1, userId: 1, title: 'Title A' },
+      Post { id: 2, userId: 2, title: 'Title B' }
     ]
   }
 */
 ```
 
 ## Inserting Data Without Normalization
 
-If you don't need the data to be normalized, you may use `add` method to insert data as well. The Biggest difference between `insert` method is that `add` method will always return the corresponding model instances rather than returning the whole `entities` object.
+If you don't need the data to be normalized, you may use `insert` method to insert data. The insert method will ignore any relationships, and returns a new model instance.
 
 ```js
-const user = store.$repo(User).add({ id: 1, name: 'John Doe' })
+const user = store.$repo(User).insert({ id: 1, name: 'John Doe' })
 
-// { id: 1, name: 'John Doe' }
+// User { id: 1, name: 'John Doe' }
 ```
 
-You may also pass an array of records to the `add` method. In that case, the returned value will be an array of models.
+You may also pass an array of records to the `insert` method. In that case, the returned value will be an array of models.
 
 ```js
-const users = store.$repo(User).add([
+const users = store.$repo(User).insert([
   { id: 1, name: 'John Doe' },
   { id: 2, name: 'Jane Doe' }
 ])
 
 /*
   [
-    { id: 1, name: 'John Doe' },
-    { id: 2, name: 'Jane Doe' }
+    User { id: 1, name: 'John Doe' },
+    User { id: 2, name: 'Jane Doe' }
   ]
 */
 ```
 
 ## Inserting Data With Default Values
 
-When you pass an empty object or array to the `insert` or `add` method, it will do nothing. If you want to insert fresh data with all fields being default values, you may use `new` method. The `new` method will create a record with all fields filled with default values defined in the model.
+When you pass an empty object or array to the `save` or `insert` method, it will do nothing. If you want to insert fresh data with all fields being default values, you may use `new` method. The `new` method will create a record with all fields filled with default values defined in the model.
 
 ```js
 const user = store.$repo(User).new()
 
-// { id: '$uid1', name: '' }
+// User { id: '$uid1', name: '' }
 ```
 
 ::: warning
@@ -131,22 +115,22 @@ Note that to be able to use `new` method, you must define the model's primary ke
 
 ## Replacing Whole Data
 
-When inserting data, you may use `fresh` method to replace whole existing records with the newly passed in data. It's pretty much equivalent to first delete all records, then inserting new data.
+When inserting data, you may use `fresh` method to replace whole existing records with the newly passed in data. It's pretty much equivalent to first delete all records, then inserting new data. The `fresh` method will ignore any relationships.
 
 ```js
-// Existing records.
-[
-  { id: 1, name: 'John Doe' },
-  { id: 2, name: 'Jane Doe' }
-]
+// Existing data.
+{
+  1: { id: 1, name: 'John Doe' },
+  2: { id: 2, name: 'Jane Doe' }
+}
 
-// Replace whole records with the new data.
+// Replace whole data with the new data.
 store.$repo(User).fresh({ id: 3, name: 'Johnny Doe' })
 
 // The result.
-[
-  { id: 3, name: 'Johnny Doe' }
-]
+{
+  3: { id: 3, name: 'Johnny Doe' }
+}
 ```
 
 And of course, you may pass an array of records as well.
@@ -158,44 +142,6 @@ store.$repo(User).fresh([
 ])
 ```
 
-Note that the `fresh` method will also normalize the given data. That means the returned value will always be an object on entities.
-
-```js
-const entities = await store.$repo(User).fresh({ id: 1, name: 'John Doe' })
-
-/*
-  {
-    users: [
-      { id:1, name: 'Jane Doe' }
-    ]
-  }
-*/
-```
-
-If you don't want the data to be normalized, you may use `replace` method, like `add` method for `insert` method.
-
-```js
-const user = store.$repo(User).replace({ id: 1, name: 'John Doe' })
-
-// { id: 1, name: 'John Doe' }
-```
-
-The `replace` method will also accept an array of records.
-
-```js
-const users = store.$repo(User).replace([
-  { id: 1, name: 'John Doe' },
-  { id: 2, name: 'Jane Doe' }
-])
-
-/*
-  [
-    { id: 1, name: 'John Doe' },
-    { id: 2, name: 'Jane Doe' }
-  ]
-*/
-```
-
 ## Creating a model instance
 
 Sometimes, you may want to create a new model instance without actually storing the model to the store. In such a case, you may use `make` method to create a fresh model instance.

docs/guide/repository/updating-data.md

@@ -6,9 +6,7 @@ In this section, it assumes you're familiar with the usage of repository. If not
 
 ## Updating Data
 
-You may update existing records using the `update` method. The `update` method, similar to the `insert` method, accepts an object of field and value pairs containing the fields to be updated.
-
-The `update` method will first attempt to locate a matching record using its primary key in the field and value pairs. If the record exists, it will be updated with the values in the other pairs.
+The `save` method may also be used to update models that already exist in the store. The `save` method will first attempt to locate a matching record using its primary key in the field and value pairs. If the record exists, it will be updated with the values in the other pairs.
 
 ```js
 // Existing records.
@@ -19,7 +17,7 @@ The `update` method will first attempt to locate a matching record using its pri
 ]
 
 // Update the "age" of the record with id of 2.
-store.$repo(User).update({ id: 2, age: 50 })
+store.$repo(User).save({ id: 2, age: 50 })
 
 // The result.
 [
@@ -29,63 +27,23 @@ store.$repo(User).update({ id: 2, age: 50 })
 ]
 ```
 
-Similarly as the `insert` method, you may pass an array of objects to update multiple records at once.
+You may pass an array of objects to update multiple records at once.
 
 ```js
-store.$repo(User).update([
+store.$repo(User).save([
   { id: 2, age: 50 },
   { id: 3, age: 80 }
 ])
 ```
 
-The `update` method will also "normalize" the given data. That means if you pass an object that contains any nested relationships, those relationships are also updated. Please see <normalization doc link?> for more details about data normalization.
-
-Because the `update` method might update records of multiple models, it will always return a collection of entities that have been updated.
-
-```js
-const entities = await store.$repo(User).update({ id: 1, age: 50 })
-
-/*
-  {
-    users: [
-      { id:1, name: 'Jane Doe', age: 50 }
-    ]
-  }
-*/
-```
-
-## Updating Data Without Normalization
-
-If you don't need the data to be normalized, you may use `merge` method to update data as well. The difference between `update` method is that `merge` method will always return the corresponding model instances rather than returning the whole entities object.
-
-```js
-const user = store.$repo(User).merge({ id: 2, age: 50 })
-
-// { id: 2, name: 'Jane Doe', age: 50 }
-```
-
-You may also pass an array of records to the `merge` method. In that case, the returned value will be an array of models.
-
-```js
-const user = await store.$repo(User).merge([
-  { id: 1, age: 50 },
-  { id: 2, name: 'Jane Doe', age: 30 }
-])
-
-/*
-  [
-    { id:1, name: 'John Doe', age: 50 },
-    { id:2, name: 'Jane Doe', age: 30 }
-  ]
-*/
-```
+The `save` method will also "normalize" the given data. That means if you pass an object that contains any nested relationships, those relationships are also updated. Please see [Relationships: Getting Started](../relationships/getting-started.md#inserting-relationships) for more details about data normalization.
 
 ## Constraints By Query
 
-In addition to updating records by passing in the object that contains the primary key, you may constrain the query to control what records are to be updated by the `revise` method and using a `where` clause.
+In addition to updating records by passing in the object that contains the primary key to the `save` method, you may constrain the query to control what records are to be updated by the `update` method and using a `where` clause.
 
 ```js
-store.$repo(User).where('id', 1).revise({ age: 50 })
+store.$repo(User).where('id', 1).update({ age: 50 })
 ```
 
 When constraining the query by the `where` clause, all updates will be performed against any number of records that match a given query.
@@ -94,25 +52,9 @@ In the following example, all flights that are `active` and have a destination o
 
 ```js
 store.$repo(Flight)
-  .where('active', true)
-  .where('destination', 'Tokyo')
-  .revise({ delayed: true })
-```
-
-As opposed to updating records by `update` method, it only accepts an object as the argument (not an array). Also, it will not normalize the data, and any nested relationships will be ignored.
-
-Because it will only update the records of the caller model, it will always return a collection of models that have been updated.
-
-```js
-const flights = await store.$repo(Flight)
   .where('active', true)
   .where('destination', 'Tokyo')
   .update({ delayed: true })
-
-/*
-  [
-    { id: 12, active: true, destination: 'Tokyo', delayed: true },
-    { id: 24, active: true, destination: 'Tokyo', delayed: true }
-  ]
-*/
 ```
+
+As opposed to updating records by the `save` method, it only accepts an object as the argument (not an array). Also, it will not normalize the data, and any nested relationships will be ignored.