small change to addedHook 🦅 [merge]

mesqueeb · Nov 30, 2018 · 76874f8 · 76874f8
2 parents c82a0a8 + a82a288
commit 76874f8
Show file tree

Hide file tree

Showing 10 changed files with 123 additions and 65 deletions.
diff --git a/dist/index.cjs.js b/dist/index.cjs.js
@@ -957,15 +957,15 @@ function pluginActions (Firebase$$1) {
                 }
             }
             // define handleDoc()
-            function handleDoc(_changeType, id, doc, source) {
+            function handleDoc(_changeType, id, doc) {
                 // define storeUpdateFn()
                 function storeUpdateFn(_doc) {
                     return dispatch('serverUpdate', { change: _changeType, id: id, doc: _doc });
                 }
                 // get user set sync hook function
                 var syncHookFn = state._conf.serverChange[_changeType + 'Hook'];
                 if (syncHookFn) {
-                    syncHookFn(storeUpdateFn, doc, id, store, source, _changeType);
+                    syncHookFn(storeUpdateFn, doc, id, store, 'server', _changeType);
                 }
                 else {
                     storeUpdateFn(doc);
@@ -992,21 +992,19 @@ function pluginActions (Firebase$$1) {
                         var doc = setDefaultValues(querySnapshot.data(), state._conf.serverChange.defaultValues);
                         var id = getters.firestorePathComplete.split('/').pop();
                         doc.id = id;
-                        handleDoc('modified', id, doc, source);
+                        handleDoc('modified', id, doc);
                         return resolve();
                     }
                     querySnapshot.docChanges().forEach(function (change) {
                         var changeType = change.type;
                         // Don't do anything for local modifications & removals
-                        if (source === 'local' &&
-                            (changeType === 'modified' || changeType === 'removed')) {
+                        if (source === 'local')
                             return resolve();
-                        }
                         var id = change.doc.id;
                         var doc = (changeType === 'added')
                             ? setDefaultValues(change.doc.data(), state._conf.serverChange.defaultValues)
                             : change.doc.data();
-                        handleDoc(changeType, id, doc, source);
+                        handleDoc(changeType, id, doc);
                     });
                     return resolve();
                 }, function (error$$1) {

diff --git a/dist/index.esm.js b/dist/index.esm.js
@@ -951,15 +951,15 @@ function pluginActions (Firebase) {
                 }
             }
             // define handleDoc()
-            function handleDoc(_changeType, id, doc, source) {
+            function handleDoc(_changeType, id, doc) {
                 // define storeUpdateFn()
                 function storeUpdateFn(_doc) {
                     return dispatch('serverUpdate', { change: _changeType, id: id, doc: _doc });
                 }
                 // get user set sync hook function
                 var syncHookFn = state._conf.serverChange[_changeType + 'Hook'];
                 if (syncHookFn) {
-                    syncHookFn(storeUpdateFn, doc, id, store, source, _changeType);
+                    syncHookFn(storeUpdateFn, doc, id, store, 'server', _changeType);
                 }
                 else {
                     storeUpdateFn(doc);
@@ -986,21 +986,19 @@ function pluginActions (Firebase) {
                         var doc = setDefaultValues(querySnapshot.data(), state._conf.serverChange.defaultValues);
                         var id = getters.firestorePathComplete.split('/').pop();
                         doc.id = id;
-                        handleDoc('modified', id, doc, source);
+                        handleDoc('modified', id, doc);
                         return resolve();
                     }
                     querySnapshot.docChanges().forEach(function (change) {
                         var changeType = change.type;
                         // Don't do anything for local modifications & removals
-                        if (source === 'local' &&
-                            (changeType === 'modified' || changeType === 'removed')) {
+                        if (source === 'local')
                             return resolve();
-                        }
                         var id = change.doc.id;
                         var doc = (changeType === 'added')
                             ? setDefaultValues(change.doc.data(), state._conf.serverChange.defaultValues)
                             : change.doc.data();
-                        handleDoc(changeType, id, doc, source);
+                        handleDoc(changeType, id, doc);
                     });
                     return resolve();
                 }, function (error$$1) {

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -11,6 +11,7 @@ module.exports = {
       ['/setup', 'Installation & setup'],
       '/guide',
       '/extra-features',
+      '/firestore-fields-and-functions',
       '/config-example',
       '/feedback',
     ],

diff --git a/docs/README.md b/docs/README.md
@@ -18,14 +18,14 @@ footer: MIT Licensed | Copyright © 2018-present Luca Ban - Mesqueeb
 In just 4 lines of code, get your vuex module in complete 2-way sync with firestore:
 
 ```js
-const userModule = {
+const userDataModule = {
   firestorePath: 'users/{userId}/data',
   firestoreRefType: 'collection', // or 'doc'
   moduleName: 'userData',
   statePropName: 'docs',
   // the rest of your module here
 }
-// add userModule as vuex plugin wrapped in vuex-easy-firestore
+// add userDataModule as vuex plugin wrapped in vuex-easy-firestore
 ```
 
 and Alakazam! Now you have a vuex module called `userData` with `state: {docs: {}}`.
@@ -35,9 +35,9 @@ Now you just update and add docs with `dispatch('userData/set', newItem)` and fo
 
 # Features
 
-- Complete 2-way sync between your Vuex module & Firestore
-- [Automatic Firestore Timestamp conversion](extra-features.html#defaultvalues-set-after-server-retrieval)
-- [Fillables](extra-features.html#fillables-and-guard) (limit props able to sync)
+- Automatic 2-way sync between your Vuex module & Firestore
+- [Timestamp conversion to Date()](extra-features.html#defaultvalues-set-after-server-retrieval)
+- [Fillables / guard](extra-features.html#fillables-and-guard) (limit fields which will sync)
 - [Hooks](extra-features.html#hooks-before-insert-patch-delete) (before / after sync)
 - [Where / orderBy filters](extra-features.html#filters)
 

diff --git a/docs/config-example.md b/docs/config-example.md
@@ -1,6 +1,6 @@
 # Config example
 
-Here is a list with all possible config options:
+Here is a list with all possible config options. **Only the top 3 properties are required**, the rest may be left out if not used!
 
 ```js
 const firestoreModule = {

diff --git a/docs/extra-features.md b/docs/extra-features.md
@@ -1,21 +1,5 @@
 # Extra features
 
-## arrayUnion and arrayRemove
-
-Just like [Firestore](https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array), Vuex Easy Firestore supports the usage of *arrayUnion* and *arrayRemove*.
-
-```js
-import { arrayUnion, arrayRemove } from 'vuex-easy-firestore'
-
-store.patch('myModule/patch', {
-  id: '001',
-  array1: arrayUnion('a new val'),
-  array2: arrayRemove('some val'),
-})
-```
-
-And as always, your vuex module & firestore will stay in sync!
-
 ## Filters
 
 > Only for 'collection' mode.
@@ -145,6 +129,8 @@ guard: ['email']
 
 A function where you can check something or even change the doc (the doc object) before the store mutation occurs. The `doc` passed in these hooks will also have an `id` field which is the id with which it will be added to the store and to Firestore.
 
+Please make sure to check the overview of [execution timings of hooks](#execution-timings-of-hooks).
+
 ```js
 {
   // your other vuex-easy-fire config...
@@ -183,34 +169,67 @@ Exactly the same as above, but for changes that have occured on the server. You
 }
 ```
 
+Please make sure to check the overview of execution timings of hooks, in the next chapter:
+
 ## Execution timings of hooks
 
+Notice that the `created_at` and `updated_at` fields mentioned below is used by default, but can be disabled. To disable just add them to your [guard config](#fillables-and-guard).
+
 **Collection mode hooks**
 
 <table>
   <tr>
     <th>change type</th>
-    <th>local</th>
+    <th colspan="2">local</th>
     <th>server</th>
   </tr>
   <tr>
     <td>insertion</td>
-    <td><code>sync.insertHook</code> & <code>serverChange.addedHook</code></td>
+    <td>
+      <b>without <code>created_at</code></b>
+      <ol>
+        <li><code>sync.insertHook</code></li>
+      </ol>
+    </td>
+    <td>
+      <b>with <code>created_at</code></b>
+      <ol>
+        <li><code>sync.insertHook</code></li>
+        <li><code>serverChange.modifiedHook</code></li>
+      </ol>
+    </td>
     <td><code>serverChange.addedHook</code></td>
   </tr>
   <tr>
     <td>modification</td>
-    <td><code>sync.patchHook</code> & <code>serverChange.modifiedHook</code></td>
+    <td>
+      <b>without <code>updated_at</code></b>
+      <ol>
+        <li><code>sync.patchHook</code></li>
+      </ol>
+    </td>
+    <td>
+      <b>with <code>updated_at</code></b>
+      <ol>
+        <li><code>sync.patchHook</code></li>
+        <li><code>serverChange.modifiedHook</code></li>
+      </ol>
+    </td>
     <td><code>serverChange.modifiedHook</code></td>
   </tr>
   <tr>
     <td>deletion</td>
-    <td><code>sync.deleteHook</code> & <code>serverChange.removedHook</code></td>
+    <td colspan="2">
+      <ol>
+        <li><code>sync.deleteHook</code></li>
+        <li><code>serverChange.removedHook</code></li>
+      </ol>
+    </td>
     <td><code>serverChange.removedHook</code></td>
   </tr>
   <tr>
     <td>after <code>openDBChannel</code></td>
-    <td colspan="2"><code>serverChange.addedHook</code> is executed once for each doc</td>
+    <td colspan="3"><code>serverChange.addedHook</code> is executed once for each doc</td>
   </tr>
 </table>
 
@@ -219,27 +238,37 @@ Exactly the same as above, but for changes that have occured on the server. You
 <table>
   <tr>
     <th>change type</th>
-    <th>local</th>
+    <th colspan="2">local</th>
     <th>server</th>
   </tr>
   <tr>
     <td>modification</td>
-    <td><code>sync.patchHook</code> & <code>serverChange.modifiedHook</code></td>
+    <td>
+      <b>without <code>updated_at</code></b>
+      <ol>
+        <li><code>sync.patchHook</code></li>
+      </ol>
+    </td>
+    <td>
+      <b>with <code>updated_at</code></b>
+      <ol>
+        <li><code>sync.patchHook</code></li>
+        <li><code>serverChange.modifiedHook</code></li>
+      </ol>
+    </td>
     <td><code>serverChange.modifiedHook</code></td>
   </tr>
   <tr>
     <td>after <code>openDBChannel</code></td>
-    <td colspan="2"><code>serverChange.modifiedHook</code> is executed once</td>
+    <td colspan="3"><code>serverChange.modifiedHook</code> is executed once</td>
   </tr>
 </table>
 
 ### Note about the serverChange hooks executing on local changes
 
-I have done my best to limit the hooks to only be executed on the proper events, but I cannot prevent the serverChange hook on being executed after each local change. The reason is because of how Firestore's [onSnapshot events](https://firebase.google.com/docs/firestore/query-data/listen) work. The reason being their explanation here:
+I have done my best to limit the hooks to only be executed on the proper events. The server hooks are executed during Firestore's [onSnapshot events](https://firebase.google.com/docs/firestore/query-data/listen).
 
-> **Events for metadata changes**
->
-> 3. The backend notifies the client of the successful write. There is no change to the document data, but there is a metadata change because the "pending writes" flag is now `false`.
+The reason for `updated_at` to trigger `serverChange.modifiedHook` even on just a local change, is because `updated_at` uses Firestore's `firebase.firestore.FieldValue.serverTimestamp()` which is replaced by a timestamp on the server and therefor there is a "server change".
 
 ## defaultValues set after server retrieval
 

diff --git a/docs/firestore-fields-and-functions.md b/docs/firestore-fields-and-functions.md
@@ -0,0 +1,38 @@
+# Firestore fields and functions
+
+## arrayUnion and arrayRemove
+
+Just like Firestore, Vuex Easy Firestore supports the usage of *arrayUnion* and *arrayRemove*. ([Firestore documentation](https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array))
+
+```js
+import { arrayUnion, arrayRemove } from 'vuex-easy-firestore'
+
+store.patch('myModule/patch', {
+  id: '001',
+  array1: arrayUnion('a new val'),
+  array2: arrayRemove('some val'),
+})
+```
+
+And as always, your vuex module & firestore will stay in sync!
+
+## Delete fields
+
+Since document modifications are merged with the data on the server, you have to be specific if you want to delete a field entirely. In Firestore you can use `firebase.firestore.FieldValue.delete()` for this purpose. ([Firestore documentation](https://firebase.google.com/docs/firestore/manage-data/delete-data#fields))
+
+In vuex-easy-firestore it will automatically delete fields when you use the `delete` action. However, there's a small difference between 'doc' mode and 'collection' mode:
+
+```js
+// in 'doc' mode:
+store.dispatch('myModule/delete', 'field')
+// is the same as
+store.dispatch('myModule/patch', {field: firebase.firestore.FieldValue.delete()})
+
+// in 'collection' mode:
+const id = '001'
+store.dispatch('myModule/delete', `${id}.field`)
+// is the same as
+store.dispatch('myModule/patch', {id, field: firebase.firestore.FieldValue.delete()})
+```
+
+Please note that you can also delete nested properties by using `.` in between the field names. Eg. `field.nestedField.veryDeepField`.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vuex-easy-firestore",
-  "version": "1.20.1",
+  "version": "1.20.2",
   "description": "Easy coupling of firestore and a vuex module. 2-way sync with 0 boilerplate!",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

diff --git a/src/module/actions.ts b/src/module/actions.ts
@@ -286,15 +286,15 @@ export default function (Firebase: any): AnyObject {
         }
       }
       // define handleDoc()
-      function handleDoc (_changeType, id, doc, source) {
+      function handleDoc (_changeType, id, doc) {
         // define storeUpdateFn()
         function storeUpdateFn (_doc) {
           return dispatch('serverUpdate', {change: _changeType, id, doc: _doc})
         }
         // get user set sync hook function
         const syncHookFn = state._conf.serverChange[_changeType + 'Hook']
         if (syncHookFn) {
-          syncHookFn(storeUpdateFn, doc, id, store, source, _changeType)
+          syncHookFn(storeUpdateFn, doc, id, store, 'server', _changeType)
         } else {
           storeUpdateFn(doc)
         }
@@ -318,22 +318,18 @@ export default function (Firebase: any): AnyObject {
             const doc = setDefaultValues(querySnapshot.data(), state._conf.serverChange.defaultValues)
             const id = getters.firestorePathComplete.split('/').pop()
             doc.id = id
-            handleDoc('modified', id, doc, source)
+            handleDoc('modified', id, doc)
             return resolve()
           }
           querySnapshot.docChanges().forEach(change => {
             const changeType = change.type
             // Don't do anything for local modifications & removals
-            if (source === 'local' &&
-              (changeType === 'modified' || changeType === 'removed')
-            ) {
-              return resolve()
-            }
+            if (source === 'local') return resolve()
             const id = change.doc.id
             const doc = (changeType === 'added')
               ? setDefaultValues(change.doc.data(), state._conf.serverChange.defaultValues)
               : change.doc.data()
-            handleDoc(changeType, id, doc, source)
+            handleDoc(changeType, id, doc)
           })
           return resolve()
         }, error => {