Huge documentation overhaul 🗺 [merge]

Huge documentation overhaul 🗺

.babelrc

@@ -1,8 +1,10 @@
 {
   "presets": [
-    ["env", {
+    ["@babel/preset-env", {
       "modules": false
     }]
   ],
-  "plugins": ["external-helpers", "babel-plugin-transform-object-rest-spread"]
+  "plugins": [
+    "@babel/plugin-proposal-object-rest-spread"
+  ]
 }

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
+docs/.vuepress/dist
 .vscode
 .cache

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Luca Ban - Mesqueeb Productions
+Copyright (c) 2018 Luca Ban - Mesqueeb
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

build/rollup.js

@@ -1,4 +1,31 @@
-// npm i -D babel-core babel-plugin-external-helpers babel-plugin-transform-object-rest-spread babel-preset-env rollup rollup-plugin-babel rollup-plugin-commonjs rollup-plugin-node-resolve rollup-plugin-terser
+/* eslint-disable */
+
+/* Required packages: */
+// npm i -D \
+// @babel/core \
+// @babel/plugin-external-helpers \
+// @babel/plugin-proposal-object-rest-spread \
+// @babel/preset-env \
+// rollup \
+// rollup-plugin-babel@latest \
+// rollup-plugin-commonjs \
+// rollup-plugin-node-resolve \
+// rollup-plugin-terser \
+// is-what
+
+/* Required .babelrc setup: */
+// {
+//   "presets": [
+//     ["@babel/preset-env", {
+//       "modules": false
+//     }]
+//   ],
+//   "plugins": [
+//     "@babel/plugin-external-helpers",
+//     "@babel/plugin-proposal-object-rest-spread"
+//   ]
+// }
+
 import babel from 'rollup-plugin-babel'
 import commonjs from 'rollup-plugin-commonjs'
 import { terser } from 'rollup-plugin-terser'

docs/.vuepress/config.js

@@ -0,0 +1,27 @@
+
+module.exports = {
+  title: 'Vuex Easy Access',
+  description: 'Unified syntax for accessing your Vuex store through simple set() and get() functions + auto generate mutations.',
+  base: '/vuex-easy-access/',
+  ga: 'UA-92965499-4',
+  themeConfig: {
+    displayAllHeaders: true,
+    sidebar: [
+      ['/', 'What is Vuex Easy Access?'],
+      '/setup',
+      '/guide',
+      '/advanced',
+      '/hooks',
+      '/reference',
+      '/feedback',
+    ],
+    nav: [
+      { text: 'Changelog', link: 'https://github.com/mesqueeb/vuex-easy-access/releases' },
+    ],
+    repo: 'mesqueeb/vuex-easy-access',
+    repoLabel: 'Github',
+    docsDir: 'docs',
+    docsBranch: 'dev',
+    editLinks: true,
+  }
+}

docs/.vuepress/deploy.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+
+# abort on errors
+set -e
+
+# build
+npm run docs:build
+
+# navigate into the build output directory
+cd docs/.vuepress/dist
+
+# if you are deploying to a custom domain
+# echo 'www.example.com' > CNAME
+
+git init
+git add -A
+git commit -m 'deploy'
+
+# if you are deploying to https://<USERNAME>.github.io
+# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
+
+# if you are deploying to https://<USERNAME>.github.io/<REPO>
+git push -f git@github.com:mesqueeb/vuex-easy-access.git master:gh-pages
+
+cd -

docs/README.md

@@ -0,0 +1,60 @@
+# What is Vuex Easy Access?
+
+1. Zero boilerplate Vuex → auto generated actions & mutations!
+2. Unified syntax for accessing your store through simple `set()` and `get()`
+
+## Motivation
+
+[Vuex](https://vuex.vuejs.org/) is great for state management in a VueJS app, however **it requires a lot of boilerplating** setting up your store and all actions and mutations.
+
+#### The Vuex philosophy
+
+The philosophy of Vuex is to do everything through mutations that will record a history of the changes you make to the store. This makes it possible to easily track changes when things go wrong as your app grows.
+
+#### The Vuex Easy Access philosophy
+Instead of having to write all actions and mutations for each change you make to the store, wouldn't it be great if an action and mutation is generated for you from the start? That's exactly what Vuex Easy Access does!
+
+> Vuex Easy Access automatically generates actions and mutations for each state property!
+
+JavaScript | Vuex Easy Access
+-- | --
+In vanilla JavaScript you can simply do:<br>`object.prop.nestedProp = newVal`<br>why shouldn't you be able to do this with Vuex? | With Vuex Easy Access you can!<br>`set('object.prop.nestedProp', newVal)`
+
+And the best part is, all state changes go through a mutation under the hood!
+
+## Features
+
+- Automatically generated actions & mutations to:
+  - Set state values
+  - Set nested state values
+  - Delete values
+  - **Arrays:** Push/shift/pop/splice values
+  - **Objects:** use ID wildcards
+- Shorthand `store.set()` for all the above
+- Streamlined `store.get()` to get state valuess
+
+## Short overview
+
+### 1. auto-generated Vuex actions
+
+_ | actions generated from state
+--|--
+**State props** | eg. ```state: {someProp: {nestedProp: ''}}```
+Set values<br>Set nested values<br><br>Delete values | `dispatch('module/set/someProp', newVal)`<br>`dispatch('module/set/someProp.nestedProp', newVal)`<br>`dispatch('module/delete/someProp')`<br>`dispatch('module/delete/someProp.nestedProp')`
+**Array props** | eg. ```state: {someArray: []}```
+Push/shift/pop/splice values | `dispatch('module/set/someArray.push', newVal)`<br>`dispatch('module/set/someArray.shift', newVal)`<br>`dispatch('module/set/someArray.pop', newVal)`<br>`dispatch('module/set/someArray.splice', newVal)`
+**Objects with id wildcard** | eg. ```state: {someObject: {'*': ''}}```
+Set and delete | `dispatch('module/set/someObject.*', {[id]: newVal})`<br>`dispatch('module/delete/someObject.*', id)`
+
+### 2. Easy Access shorthand
+
+_ | available setters
+--|--
+**State props** | eg. ```state: {someProp: {nestedProp: ''}}```
+Set values<br>Set nested values<br><br>Delete values | `set('module/someProp', newVal)`*<br>`set('module/someProp.nestedProp', newVal)`<br>`delete('module/someProp')`<br>`delete('module/someProp.nestedProp')`
+**Array props** | eg. ```state: {someArray: []}```
+Push/shift/pop/splice values | `set('module/someArray.push', newVal)`<br>`set('module/someArray.shift', newVal)`<br>`set('module/someArray.pop', newVal)`<br>`set('module/someArray.splice', newVal)`
+**Objects with id wildcard** | eg. ```state: {someObject: {'*': ''}}```
+Set and delete | `set('module/someObject.*', {[id]: newVal})`<br>`delete('module/someObject.*', id)`
+
+\* `set()` and `delete()` are attached to the Vuex `store` object: `store.set()`

docs/advanced.md

@@ -0,0 +1,114 @@
+# Advanced configuration
+
+When you create your easyAccess plugin, you can make some configuration through an object:
+
+```js
+import createEasyAccess from 'vuex-easy-access'
+const easyAccess = createEasyAccess({/* your configuration */})
+```
+
+All possible values for the configuration are explained here:
+
+## Firestore integration (for Google Firebase)
+
+You can add compatibility for the amazing sister plugin: [Vuex Easy Firestore](https://github.com/mesqueeb/VuexEasyFirestore). To do so just pass a variable in the configuration object like so:
+
+```js
+const easyAccess = createEasyAccess({vuexEasyFirestore: true})
+```
+
+This will make sure that whenever you set a value in a module where you enabled 'Vuex Easy Firestore', it will **auto-sync to your firestore**! Please see the [Vuex Easy Firestore documentation](https://github.com/mesqueeb/VuexEasyFirestore) for more information on how to set up auto-sync with firestore.
+
+Please note when using both plugins, it is important to pass the 'vuex-easy-firestore' plugin first, and the 'easyAccess' second for it to work properly.
+
+## Change get() set() function names
+
+If for some reason you want to change the default function names for `get()` and `set()` (or `delete()`) to something else (eg. capitalising to `GET()` and `SET()`), you can do so by passing an object to `createEasyAccess()` like so:
+
+```js
+const easyAccess = createEasyAccess({
+  getter: 'GET',
+  setter: 'SET',
+  deletor: 'DELETE', // See 'Use case: set with ID wildcard'
+})
+```
+
+Now instead of the `get` `set` keywords, you will only be able to use `store.GET()` and `store.SET()` and for dispatches `dispatch('SET/prop', val)`.
+
+## Ignore private state props
+
+Vuex Easy Access will ignore (and not make mutations/setters) any props that:
+
+- start with an underscore (*default*)
+- are added to the `ignoreProps: []` config
+
+```js
+// in the config
+const easyAccess = createEasyAccess({
+  ignoreProps: ['normalProp.secretProp'] // true is the default
+})
+const state = {
+  _privateProp: null, // this prop is not touched at all!
+  normalProp: {
+    secretProp: null // this prop is not touched at all!
+  }
+}
+const store = {
+  state,
+  mutations: {
+    // and in the defaultMutations
+    ...defaultMutations(state, {
+      ignoreProps: ['normalProp.secretProp']
+    })
+  },
+}
+```
+
+This will create only the mutation and dispatch setter for 'normalProp':
+
+- `mutate('normalProp', newVal)`
+- `dispatch('set/normalProp', newVal)`
+
+And none will be set for '_privateProp' and 'secretProp'!
+
+To disable ignoring the ones with an underscore (`_privateProp`) you need to do:
+
+```js
+// in the config
+const easyAccess = createEasyAccess({
+  ignorePrivateProps: false, // true is the default
+})
+// and in your modules:
+mutations: {
+  ...defaultMutations(state, {ignorePrivateProps: false})
+}
+```
+
+Please note that when passing a prop to `ignoreProps` it will be ignored in all modules regardless of the module namespace. This is because 'defaultMutations' doesn't know the exact namespace of the module when it's initiated. You can be specific about the prop to ignore in just the namespace you want by passing the 'moduleNamespace' as third prop to the 'defaultMutations'. See the example below:
+
+```js
+// We will use the prop ignoreMeInUser in both the store root and the user module
+// But we will only ignore it in user
+const config = { ignoreProps: ['user/ignoreMeInUser'] }
+const easyAccess = createEasyAccess(config) // add config
+const rootAndUserState = { ignoreMeInUser: null }
+const userModule = {
+  state: rootAndUserState,
+  mutations: defaultMutations(rootAndUserState, config, {moduleNamespace: 'user/'}) // add config and moduleNamespace
+}
+const store = {
+  modules: { user: userModule },
+  state: rootAndUserState,
+  mutations: defaultMutations(rootAndUserState, config, {moduleNamespace: ''}) // add config and moduleNamespace
+}
+```
+
+## Use traditional `SET_PROP` syntax
+
+Mutations are used under the hood. These mutations have a simple syntax which is just the name of the prop. Check the [Reference](reference.html) for a quick overview of the mutations used by Vuex Easy Firestore.
+
+You can also opt in for mutations to be in **the traditional syntax** (as per the vuex documentation). For this please read [Syntax for overwriting setters](hooks.html#hook-into-set) in the Hooks chapter.
+
+### Missing any features?
+
+If you have any requests for more customisation of this functionality, please let me know in an [issue](https://github.com/mesqueeb/vuex-easy-access/issues)!

docs/feedback.md

@@ -0,0 +1,19 @@
+# Feedback
+
+Do you have questions, comments, suggestions or feedback? Or any feature that's missing that you'd love to have? Feel free to open an [issue](https://github.com/mesqueeb/vuex-easy-access/issues)! ♥
+
+Planned future features:
+
+- Make a blog post
+- Improve error handling
+  - Explain to dev possible path mistakes ` / vs . ` when no mutation is found
+  - Warn about ignoredProps appearing in two modules
+  - Warn when there is a module called 'set'
+  - Warn when there already is a 'set' prop on the store
+
+Also be sure to check out the sister vuex-plugin for Firebase: [Vuex Easy Firestore](https://mesqueeb.github.io/vuex-easy-firestore)!
+
+--
+
+Happy Vuexing!<br>
+-Luca Ban