39 |
39 | "+n.content+"
\n\n"}),i.classList.add("show"),r.classList.add("show"),i.innerHTML=s||''+a+"
"}function r(n,e){var t=e.router.parse().query.s;Docsify.dom.style("\n.sidebar {\n padding-top: 0;\n}\n\n.search {\n margin-bottom: 20px;\n padding: 6px;\n border-bottom: 1px solid #eee;\n}\n\n.search .input-wrap {\n display: flex;\n align-items: center;\n}\n\n.search .results-panel {\n display: none;\n}\n\n.search .results-panel.show {\n display: block;\n}\n\n.search input {\n outline: none;\n border: none;\n width: 100%;\n padding: 0 7px;\n line-height: 36px;\n font-size: 14px;\n}\n\n.search input::-webkit-search-decoration,\n.search input::-webkit-search-cancel-button,\n.search input {\n -webkit-appearance: none;\n -moz-appearance: none;\n appearance: none;\n}\n.search .clear-button {\n width: 36px;\n text-align: right;\n display: none;\n}\n\n.search .clear-button.show {\n display: block;\n}\n\n.search .clear-button svg {\n transform: scale(.5);\n}\n\n.search h2 {\n font-size: 17px;\n margin: 10px 0;\n}\n\n.search a {\n text-decoration: none;\n color: inherit;\n}\n\n.search .matching-post {\n border-bottom: 1px solid #eee;\n}\n\n.search .matching-post:last-child {\n border-bottom: 0;\n}\n\n.search p {\n font-size: 14px;\n overflow: hidden;\n text-overflow: ellipsis;\n display: -webkit-box;\n -webkit-line-clamp: 2;\n -webkit-box-orient: vertical;\n}\n\n.search p.empty {\n text-align: center;\n}"),function(n,e){void 0===e&&(e="");var t='4 |7 | 8 | [GitHub](https://github.com/davestewart/vuex-pathify) 9 | [Get Started](#home) 10 | 11 | 12 |  -------------------------------------------------------------------------------- /docs/pages/discussion/faq.md: -------------------------------------------------------------------------------- 1 | # FAQs 2 | 3 | > Pathify and Vuex tips and tricks to ramp up your productivity 4 | 5 | 6 | 7 | ## When to use Pathify 8 | 9 | #### What is Pathify best-suited for? 10 | 11 | Getting, setting and syncing properties 1:1 with the store. 12 | 13 | In the vast majority of cases, you'll just need to set and get data, or sync components, and this is where Pathify shines. 14 | 15 | #### What is Pathify less-suited for? 16 | 17 | Because Pathify's configuration is tuned to map state names to Vuex members in a `get/set` manner, calling non `get/set` named `actions` or `mutations` such as `updateItems` or `loadItems` via Pathify may not feel intuitive. 18 | 19 | You can use [direct syntax](/guide/paths#direct-syntax) to target non-`get/set` members, for example `set('products/updateItem!', value)` or, if you feel more comfortable in these situations commit or dispatch [directly](#do-i-still-need-commit-and-dispatch). 20 | 21 | #### Make sure you understand Vuex properly before using Pathify 22 | 23 | Pathify wires up Vuex "behind the scenes", so if you don't properly understand Vuex, you'll doubtless find it confusing if something doesn't work as expected. 24 | 25 | Pathify isn't designed to replace Vuex, or designed "let you off" understanding Vuex, it's designed to take the drudgery out of wiring up Vuex stores once you understand them. 26 | 27 | #### Don't use Pathify sub-property access as a crutch 28 | 29 | Pathify's sub-property access is extremely useful, but don't be tempted to put everything in one property, then use pathify to access sub properties, as your application logic will become unclear. 30 | 31 | 32 | 33 | ## Store setup 34 | 35 | #### Should I always go through getters and actions? 36 | 37 | There's really no need! 38 | 39 | The consistency that **in theory** was provided by always going through actions or always going through getters, is mitigated by **only going through a path**. 40 | 41 | Creating additional getters and actions will only clog up your store and provide more code for Vue to run when getting or setting values. Creating ONLY the getters and actions you need keeps your store lean and codebase tight! 42 | 43 | The [store helpers](/guide/store) include `make.getters()` and `make.actions()` mainly for developers who [prefer this approach](https://forum.vuejs.org/t/actions-for-actions-sake/16413). 44 | 45 | 46 | #### Which naming scheme should I use; default or simple? 47 | 48 | If you can, name your store members using the [simple](/setup/mapping) scheme. 49 | 50 | It makes no difference to Pathify when correctly configured, but in the author's opinion, it's much easier to scan a file and see relate a single `foo` in state, getters and mutations, than it is to see 2 or even 3 variations on prefixing, naming and casing. 51 | 52 | Additionally, if you do need to use `commit` or `action` syntax either directly or in Pathify, it feels more consistent to use and type `lowercase` or `camelCase` in components, rather than have to keep swapping between `foo` and `SET_FOO`. 53 | 54 | 55 | Finally, in the Vuex Devtools mutations panel it's arguably easier on the eyes to scan a list of consistent `foo/bar` type mutations than it is to read a mixed list of `foo/SET_BAR` type mutations! 56 | 57 | 58 | ## Component wiring 59 | 60 | #### Do I still need commit and dispatch? 61 | 62 | With `sync()`, `set()` and [direct syntax](/guide/paths#direct-syntax) being the preferred way to get and set values on the store, you won't need `commit()` as much, but `dispatch()` is still useful in the fact it's explicit. 63 | 64 | As such, Pathify includes aliases to `commit()` and `dispatch()` within its helpers; it's up to you which method you feel most comfortable with. 65 | 66 | See the [Vuex aliases](api/properties#vuex-aliases) section for more info. 67 | 68 | 69 | #### Should I use Vuex Helpers? 70 | 71 | No. 72 | 73 | Vuex helpers, though saving over manual coding, add a lot of structural and syntactic cruft; up to 16 different entities to think about vs only 7 for Pathify. See the [code comparison](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=code/large) section of the demo to view this for yourself. 74 | 75 | In Pathify 1.1 the addition of the `call()` helper allows you to [map actions](api/component?id=call) without needing Vuex Helpers, with the additional flexibility of using wildcards. 76 | 77 | 78 | #### Do I ever need to access the store directly? 79 | 80 | Note that although Pathify removes the burden of setup and wiring, there will still be times when you want to access the store explicitly. 81 | 82 | Some rules of thumb:: 83 | 84 | - use Pathify `get()`, `set()` and `sync()` for global access and component/store sync 85 | - use Pathify [direct syntax](/guide/paths#direct-syntax) for non `set*`/`SET_*` mutations or actions 86 | - use Vuex `dispatch()` or `commit()` if you really want to be explicit, or **within** the store 87 | - call `state` directly if a same-named getter is taking priority 88 | 89 | 90 | 91 | 92 | 93 | ## Debugging 94 | 95 | #### How much complication is generated by, or in, helper functions? 96 | 97 | None, really. 98 | 99 | After the members have been found, returned functions are lightweight, and references are concrete. 100 | 101 | #### Does Pathify make it harder to debug? 102 | 103 | Pathify actually has a bunch of built-in warnings for when you don't wire things correctly! If you make a mistake, Pathify will attempt to help you out. 104 | 105 | Once set-up in the store, or wired in components, the functions are literally the same functions as you would have written yourself. 106 | 107 | If you come across a situation where you think Pathify has made something harder, [raise an issue](https://github.com/davestewart/vuex-pathify/issues) on Github. 108 | -------------------------------------------------------------------------------- /docs/pages/discussion/rationale.md: -------------------------------------------------------------------------------- 1 | # Rationale 2 | 3 | > “If something can be easy, why make it hard?” - Evan You 4 | 5 | ## Overview 6 | 7 | Why was Pathify created? 8 | 9 | The rationale behind creating Pathify is that **Vuex is great** but the coding experience is **way too complex** for something as simple as **setting and getting values** on what is essentially a global object. 10 | 11 | Managing state should not feel like an episode of [American Ninja Warrior](https://www.youtube.com/watch?v=gZkObiYVdN4). We should not need to be constantly checking the manual for syntax or caveats, writing reams of redundant code, or fretting over which "best practice" will protect us from ourselves long enough to make an app that functions in the real world. 12 | 13 | With that being said, Vuex is the Vue **state management standard**, has great tooling and online support, so we want to work with it rather than coming up with a new solution that no-one knows or cares about. 14 | 15 | ## The brief 16 | 17 | ### Pain points 18 | 19 | The first thing to look at was, where are the pain points with setting and getting data in Vuex? 20 | 21 | Which ones can be solved, which ones seem to be mantra over practicality, and which ones do we just have to live with? 22 | 23 | - Lots of store boilerplate 24 | 25 | - every property needing to be explicitly created 26 | - every property needs at least a state and mutation, and potentially a getter and action 27 | - unsure whether to create getters for all states, or not 28 | - when should actions be created and when to use only mutations ? 29 | 30 | - Component wiring 31 | 32 | - many competing and cumbersome component wiring choices 33 | - 4 Vuex helpers to choose from 34 | - why do we have to map state AND getters ? 35 | - when and where to use "mapMutations" vs "mapActions" ? 36 | - helpers needed in computed and methods 37 | 38 | - Things that are hard but feel like they shouldn't be 39 | 40 | - overall setup 41 | - working with object sub-properties 42 | - choosing between similar store members (i.e. state & getters) 43 | 44 | - Inconsistency 45 | 46 | - In stores, why `items`, `setItems` and `SET_ITEMS` ? 47 | - In components, why: 48 | - `store.state.module.value` and `store.getters['module/value']` 49 | - `commit('module/SET_VALUE')` and `dispatch('module/setValue')` 50 | 51 | - Varying advice on "best" practices 52 | 53 | - it's "bad practice" to use mutations in components 54 | - you should use "getters and actions" not "state and mutations" 55 | - should you write commits as `CONST_CASE` or `camelCase` ? 56 | 57 | - Verbose setup 58 | - storing different accessor types in separate files 59 | - creating static consts for all store member references 60 | - using dynamic object keys e.g. `[mutations.SET_ITEMS]: function () { ... }` to create properties 61 | 62 | - Esoteric terms and concepts 63 | 64 | - why "mutation", "commit", "dispatch" ? 65 | - why "getters" but then "mutations" 66 | - when to use actions and when mutations ? 67 | - when to use getters and when state ? 68 | 69 | The above points seem to fall into the following categories: 70 | 71 | - **experience** - some of these points become clearer as you get to know Vuex 72 | - **architecture** - some points are concerned simply with Vuex's architectural choices (good or bad) 73 | - **best practice** - seemingly "best" practices seem to exist to protect the developer against the code itself 74 | - **personal preference** - some of these points will depend on yours or your team's developmental preferences 75 | 76 | In the next section we'll discuss which of these can be mitigated against, but for now, let's see what we both need and want to do with Vuex... 77 | 78 | ### Everyday Vuex 79 | 80 | The second thing to look at is, what are the general tasks we do with Vuex on a day to day basis? 81 | 82 | What do we need a proposed solution to actively support, or at least not get in the way of? 83 | 84 | - Writing boilerplate: 85 | 86 | - setting up mutations for all states 87 | - potentially, setting up getters and actions 88 | - wiring one-way getters for component properties, either: 89 | - manually, by writing functions and accessing state and/or getters 90 | - automatically, using mapState and mapGetters 91 | - setting up two way wiring for component controls, either: 92 | - manually, by writing compound computed properties 93 | - semi-automatically, using 94 | - a combination of @event handlers 95 | - mapState / mapGetters 96 | - mapMutations / mapActions 97 | 98 | - General access 99 | 100 | - getting values from state or getters 101 | - setting values using commits or dispatches 102 | - calling actions using dispatches 103 | 104 | - State management 105 | 106 | - managing copies and part copies, for forms, or other compound components 107 | - managing grouped options, such as sorting, search, etc 108 | 109 | 110 | ### Ideal solution 111 | 112 | What would the ideal Vuex experience look like ? 113 | 114 | - Baseline happy: 115 | 116 | - not have to juggle JavaScript syntax or Vuex naming formats 117 | - not have to think about which store member data comes from or has to go to 118 | - set and get data without constant hand-holding from the documentation or forums 119 | - set up wiring quickly, easily and consistently 120 | - reduce or eliminate store boilerplate 121 | 122 | - Ideal scenario: 123 | 124 | - works in any project 125 | - works with, not against, Vuex 126 | - doesn't require hacks to get working 127 | - doesn't require compromises in Vuex or JavaScript 128 | - can be integrated a little or a lot 129 | - significant reduction in lines of code 130 | - removes need for defensive programming 131 | - adds additional useful functionality 132 | - approved by advanced users 133 | - easy for beginners 134 | 135 | 136 | ## Result 137 | 138 | Pathify is the result of around 6 months of incremental development, on one large project and a couple of smaller ones. It morphed from being a kitchen-sink of tools and plugins (including state persistence, store lifecycle, and transmitting state by the URL) to being only concerned with getting and setting state via paths. 139 | 140 | Looking at the list above, we can see that Pathify solves the following: 141 | 142 | 1. **Syntax juggling** 143 | 144 | [Path syntax](/guide/paths.md) unifies differing varied state, getters, commit and dispatch syntax. 145 | 146 | [Accessor priority](/guide/properties.md#accessor-priority) decouples store access from store architecture and makes it simple to get or set. 147 | 148 | 2. **Boilerplate** 149 | 150 | [Store helpers](/guide/store.md) eliminate store boilerplate. 151 | 152 | 3. **Wiring** 153 | 154 | [Component helpers](/guide/component.md) eliminate wiring boilerplate. 155 | 156 | [Sub-property access](/guide/properties.md#sub-property-access) enables transparent read and write for complex properties. 157 | 158 | 4. **Works in any project** 159 | 160 | [Mapping configuration](/setup/mapping.md) enables property mapping in any project. 161 | 162 | [Direct-property access](/guide/properties.md#direct-property-access) handles unmappable properties. 163 | 164 | 5. **Simplicity** 165 | 166 | 4 Vuex operations simplified to 2 Pathify operations. 167 | 168 | Path format does away with 3 different syntax types. 169 | 170 | Setting up and wiring properties takes 1 line per-file for multiple properties, not 3 - 8 lines per-property, per-file. 171 | 172 | Depending on your developmental / team requirements, no need for redundant or complex "best practices". 173 | 174 | Easy for beginners. 175 | -------------------------------------------------------------------------------- /docs/pages/guide/accessors.md: -------------------------------------------------------------------------------- 1 | # Store accessors 2 | 3 | > Store accessors provide simple read / write access directly on the store 4 | 5 | ## Overview 6 | 7 | The plugin adds accessor methods directly to the Vuex store instance. 8 | 9 | The methods: 10 | 11 | - use Pathify's [path syntax](/guide/paths.md) to reference modules, properties and sub-properties 12 | - implement [accessor priority](/guide/properties.md#accessor-priority), simplifying the overall set/get interface 13 | - couple with [store helpers](/guide/store.md) to provide full sub-property read/write 14 | 15 | 16 | ## Usage 17 | 18 | Once [configured](/setup/config.md), getting and setting values on the store is simple: 19 | 20 | ```js 21 | store.set('filters@sort.order', 'asc') 22 | ``` 23 | 24 | You can get and set values from anywhere, even the console (which is great for debugging!): 25 | 26 | ```js 27 | import store from 'store' 28 | window.store = store 29 | ``` 30 | ```console 31 | store.set('filters@search', 'widgets') 32 | ``` 33 | 34 | See the store accessors [demo](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=api/accessors) for an editable, live example. 35 | 36 | ## API 37 | 38 | ### Methods 39 | 40 | Remember that store accessors use Pathify's core [property access](/guide/properties.md) so have exactly the same functionality. 41 | 42 | #### `get(path: string): *` 43 | 44 | The `get()` method reads values from the getters or state: 45 | 46 | ```js 47 | // 'loading' 48 | store.get('status') 49 | ``` 50 | ```js 51 | // 'asc' 52 | store.get('filters@sort.order') 53 | ``` 54 | 55 | If the path references a store [getter function](https://vuex.vuejs.org/en/getters.html#method-style-access), pass additional arguments as required: 56 | 57 | ```js 58 | const bags = store.get('filterBy', 'category', 'bag') 59 | ``` 60 | 61 | #### `set(path: string, value: *): *` 62 | 63 | The `set()` method writes values via actions or mutations: 64 | 65 | ```js 66 | store.set('status', 'error') 67 | ``` 68 | ```js 69 | store.set('filters@sort.order', 'desc') 70 | ``` 71 | 72 | Note that `set()` returns the result of the operation so if you're expecting a Promise, you can continue when it resolves: 73 | 74 | ```js 75 | store 76 | .set('items', data) 77 | .then(console.log) 78 | ``` 79 | 80 | 81 | 82 | #### `copy(path: string): *` 83 | 84 | The `copy()` method clones and returns a non-reactive copy of the values in the store. 85 | 86 | ```js 87 | // { key: "id", order: "asc" } 88 | copy('sort') 89 | ``` 90 | ```js 91 | // rather than {__ob__: Observer} 92 | ``` 93 | 94 | -------------------------------------------------------------------------------- /docs/pages/guide/component.md: -------------------------------------------------------------------------------- 1 | # Component helpers 2 | 3 | > Component helpers take the pain out of wiring 4 | 5 | ## Overview 6 | 7 | Pathify component helpers are designed to **easily wire components** to the store. 8 | 9 | They are **direct replacements** for Vuex `map*()` helpers, which wire: 10 | 11 | - computed properties to state / getters 12 | - methods to actions 13 | - single or multiple members 14 | - 1-way and 2-way data-bindings 15 | 16 | Additionally, they support Pathify's rich [path syntax](api/paths) including: 17 | 18 | - sub-property access 19 | - wildcards 20 | 21 | Each helper generates and returns the appropriate `Function` handler or `Object` hash of handlers, which can be directly assigned or spread in as needed. 22 | 23 | Note that although the **generation** is more expensive than writing a manual function, once helper has finished, only lightweight functions are returned and run. 24 | 25 | 26 | ## Usage 27 | 28 | The following gives an example of some of the main features: 29 | 30 | ```js 31 | import { get, sync, call } from 'vuex-pathify' 32 | 33 | // component 34 | export default { 35 | computed: { 36 | // read-only, single property 37 | items: get('products/items'), 38 | 39 | // read/write, single property 40 | search: sync('products/filters@search'), 41 | 42 | // read/write, rename, multiple (sub) properties 43 | ...sync('products/filters@sort', { 44 | sortOrder: 'order', 45 | sortKey: 'key', 46 | }), 47 | 48 | // read/write, multiple automatic properties 49 | ...sync('products/*') 50 | }, 51 | 52 | methods: { 53 | // wire multiple actions 54 | ...call('products/*') 55 | } 56 | } 57 | ``` 58 | 59 | See the component helpers [demo](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=api/component) for an editable, live example. 60 | 61 | 62 | ## API 63 | 64 | !> Remember that component helpers use Pathify's core [property access](/guide/properties.md) thus have exactly the same functionality. 65 | 66 | ### Single property access 67 | 68 | #### `get(path: string): *` 69 | 70 | Use `get()` to read properties from the store: 71 | 72 | ```js 73 | computed: { 74 | items: get('products/items') 75 | } 76 | ``` 77 | 78 | The helper generates the following computed property: 79 | 80 | ```js 81 | computed: { 82 | items () { 83 | return this.$store.getters['products/items'] 84 | } 85 | } 86 | ``` 87 | 88 | The function is analogous to a combination of `mapState()` and `mapGetters()`. 89 | 90 | #### `sync(path: string): *` 91 | 92 | Use `sync()` to set up two-way data binding: 93 | 94 | ```js 95 | computed: { 96 | items: sync('products/status') 97 | } 98 | ``` 99 | 100 | The helper generates the following **compound** computed property: 101 | 102 | ```js 103 | computed: { 104 | status: { 105 | get () { 106 | return this.$store.state.products.status 107 | }, 108 | set (value) { 109 | return this.$store.commit('products/SET_STATUS', value) 110 | }, 111 | } 112 | } 113 | ``` 114 | 115 | The function is analogous to a combination of `mapState()` and `mapMutations()`. 116 | 117 | Note that `sync()` reads **only from state** to prevent a situation where a same-named [transformational getter](api/properties?id=accessor-priority) could end up recursively modifying the true value of state. 118 | 119 | If you want to specify an alternate mutation or action, `sync()` takes an additional path syntax `|` with which you can specify direct access: 120 | 121 | ```js 122 | computed: { 123 | // get with `items` accessor but set with `update()` action 124 | items: sync('items|update') 125 | } 126 | ``` 127 | 128 | #### `call(path: string): *` 129 | 130 | Use `call()` to create functions that dispatch actions to the store: 131 | 132 | ```js 133 | methods: { 134 | load: call('products/load') 135 | } 136 | ``` 137 | 138 | The helper generates the following method: 139 | 140 | ```js 141 | methods: { 142 | load (payload) { 143 | return this.$store.dispatch('products/load', payload) 144 | } 145 | } 146 | ``` 147 | 148 | The function is analogous to `mapActions()`. 149 | 150 | 151 | ### Multi-property access 152 | 153 | Each of the component helpers can generate **multiple** members. 154 | 155 | You can use: 156 | 157 | - [array syntax](#array-syntax) - to map properties 1:1 with the store 158 | - [object syntax](#object-syntax) - to map properties with different names on the component 159 | - [wildcard expansion](#wildcard-expansion) - to grab sets of properties automatically 160 | 161 | Each syntax generates an **Object** of **named properties** which must be mixed in to the associated block (`computed` or `methods`) or set as the block itself: 162 | 163 | ```js 164 | computed: { 165 | ...sync(map), 166 | ...sync(path, map) 167 | }, 168 | methods: { 169 | ...call(map), 170 | ...call(path, map) 171 | } 172 | ``` 173 | ```js 174 | computed: sync(path, map), 175 | methods: call(path, map) 176 | ``` 177 | 178 | #### `Array syntax` 179 | 180 | Array syntax maps property names **identically** to the store. 181 | 182 | It takes an **optional** `path` prefix, and an array of store `member` names: 183 | 184 | ```js 185 | computed: { 186 | ...get('products', [ 187 | 'search', 188 | 'items', 189 | ]) 190 | }, 191 | methods: { 192 | ...get('products', [ 193 | 'load', 194 | 'update', 195 | ]) 196 | } 197 | ``` 198 | ```paths 199 | items : products/items 200 | filter : products/filter 201 | load : products/load() 202 | update : products/update() 203 | ``` 204 | 205 | #### `Object syntax` 206 | 207 | Object syntax maps property names **differently** to the store. 208 | 209 | It takes an **optional** `path` prefix, and hash of `key:member` names: 210 | 211 | ```js 212 | computed: { 213 | ...sync('products/filters@sort', { 214 | sortOrder: 'order', 215 | sortKey: 'key', 216 | }) 217 | }, 218 | methods: { 219 | ...call('products', { 220 | loadItems: 'load', 221 | updateItems: 'update', 222 | }) 223 | } 224 | ``` 225 | ```paths 226 | sortOrder : products/filters@sort.order 227 | sortKey : products/filters@sort.key 228 | loadItems : products/load() 229 | updateItems : products/update() 230 | ``` 231 | 232 | 233 | #### `Wildcard syntax` 234 | 235 | Wildcard syntax maps **groups** of property names **identically** to the store. 236 | 237 | ```js 238 | computed: { 239 | ...get('products/*') 240 | }, 241 | methods: { 242 | ...call('products/*') 243 | } 244 | ``` 245 | ```paths 246 | items : products/items 247 | search : products/search 248 | filters : products/filters 249 | load : products/load() 250 | update : products/update() 251 | ``` 252 | 253 | Additionally, computed properties can target **any** set of state properties or sub-properties, so the following are all valid: 254 | 255 | ```wildcards 256 | products/* 257 | products/filters@* 258 | products/filters@sort.* 259 | ``` 260 | 261 | Note that the path engine supports partial matches: 262 | 263 | ```js 264 | methods: { 265 | ...call('products/*Items') 266 | }, 267 | ``` 268 | 269 | However, overuse of partial matching would indicate an over-complex design and the need for refactoring! 270 | 271 | ### Troubleshooting wildcards 272 | 273 | Before you get all trigger-happy with wildcards and use them everywhere, there are a few things you should know. 274 | 275 | The wildcard `*` symbol tells Pathify that it should grab object keys **below** the targeted path segment and generate handler functions for them. 276 | 277 | Because the results of a wildcard path are determined **programmatically** the targeted store member **must exist** when the helper is run! 278 | 279 | For example, at the point of calling `get('user/*')` a module called `user` must exist in the store: 280 | 281 | 282 | ```js 283 | // components/User.js 284 | export default { 285 | computed: { 286 | ...get('user/*') // `store.state.user` module MUST exist at this point 287 | } 288 | } 289 | ``` 290 | 291 | There are two main situations where this may not be the case: 292 | 293 | 1. when routes have been imported before the store 294 | 2. when using dynamically registered modules 295 | 296 | Read below to find out more and how to mitigate these issues. 297 | 298 | #### `Correct router setup` 299 | 300 | It's easy to forget that components are imported when the routes are set up: 301 | 302 | ```js 303 | import User from 'components/User' 304 | export default [ 305 | { path: 'user/:id', component: User } 306 | ] 307 | ``` 308 | 309 | This results in the component definition being loaded **and the code within being run**. If any component helpers have been called with wildcard paths, they'll query the requested state object, and if it **hasn't yet** been added to the store - Pathify will log an error: 310 | 311 | ```console 312 | [Vuex Pathify] Unable to expand wildcard path 'user/*': 313 | - The usual reason for this is that the router was set up before the store 314 | - Make sure the store is imported before the router, then reload 315 | ``` 316 | 317 | To solve this, simply import your store before your router so that properties are set up before being asked for: 318 | 319 | ```js 320 | import store from './store' 321 | import router from './router' 322 | ``` 323 | 324 | If you're using Nuxt and are still getting errors, make sure you haven't loaded any components that use Pathify and wildcards in any files in `/plugins` as these will load before Nuxt has a chance to load Vuex. 325 | 326 | 327 | #### `Dynamic module registration` 328 | 329 | Vuex has the ability to register modules [dynamically](https://vuex.vuejs.org/en/modules.html#dynamic-module-registration) rather than import them all when your project loads. Use cases for this might include: 330 | 331 | - a module that is used only in a subset of routes 332 | - one component and potentially child-components need access to the same store 333 | - a set of components might use copies of the same store 334 | 335 | Let's take the first example, that a `user/` route requires a `user` store module to be loaded: 336 | 337 | ```js 338 | // components/User.js 339 | import user from 'store/user' 340 | 341 | export default { 342 | beforeCreate () { 343 | this.$store.registerModule('user', user) 344 | }, 345 | 346 | computed: get('user/*') // ERROR! `store.state.user` does not exist at this point! 347 | } 348 | ``` 349 | 350 | The problem is that at the time of executing `get()` the `created()` lifecycle hook hasn't run. 351 | 352 | To get round this, there are a few options: 353 | 354 | 1. **don't use wildcards** with dynamic modules 355 | 2. register the module in a **composing** component 356 | 3. register the module in a **global router** `beforeRouteEnter` hook 357 | 4. assign computed properties **programmatically** in the component `beforeCreate` hook 358 | 359 | The first option is workable as it's self-contained and only a little more code. The next two options require additional architecture, so might not be workable. The forth option whilst straightforward, requires a not trivial amount of code to set up, as you need to account for a few edge cases. 360 | 361 | As such, Pathify ships with a `registerModule` helper which you can read about below. 362 | 363 | #### `registerModule()` 364 | 365 | Pathify's `registerModule()` helper is designed to: 366 | 367 | - register a store module via component `beforeCreate` 368 | - add or extend the component's computed properties with new ones 369 | - add or extend the component's methods with new ones 370 | - unregister a store module via component `destroyed` 371 | 372 | Its signature is similar to `Vuex.registerModule()` with the addition of a callback that should return new component blocks. It is implemented as a function which returns an object which can used as a base class or mixin. 373 | 374 | Below is an example using the helper as a base class: 375 | 376 | ```js 377 | // imports 378 | import { get, call, registerModule } from 'vuex-pathify' 379 | import module from './store/user' 380 | 381 | // callback to return lazily-executed Pathify helpers 382 | const members = function () { 383 | return { 384 | computed: get('user/*'), 385 | methods: call('user/*') 386 | } 387 | } 388 | 389 | /** 390 | * User component definition 391 | */ 392 | export default { 393 | // extend from generated base class 394 | extend: registerModule('user', module, members), 395 | 396 | // additional computed properties 397 | computed: { 398 | foo () { ... } 399 | }, 400 | 401 | // additional methods 402 | methods: { 403 | bar () { ... } 404 | } 405 | } 406 | ``` 407 | 408 | If you're interested to see what happens behind the scenes [check out the code](https://github.com/davestewart/vuex-pathify/blob/master/src/helpers/modules.js) on GitHub. 409 | -------------------------------------------------------------------------------- /docs/pages/guide/decorators.md: -------------------------------------------------------------------------------- 1 | # Class component decorators 2 | 3 | > **Optional** component property decorators for **single property access** to be used with class based components 4 | 5 | ## Overview 6 | 7 | For developers who prefer class-based component development, Pathify allows you to generate computed properties using the `@decorator` syntax. 8 | 9 | They are [single-property-access](api/component?id=single-property-access) equivalents of their [component helpers](api/component) counterpart. 10 | 11 | Note that Pathify imports [`vue-class-component`](https://github.com/vuejs/vue-class-component) internally, but this may change in the future. 12 | 13 | ## Usage 14 | 15 | !> **Important syntax difference!** Decorators use Sentence-case, i.e. `Get` and not `get`! 16 | 17 | The following gives an example of some of the main features: 18 | 19 | **ES** 20 | 21 | ```js 22 | import { Get, Sync, Call } from 'vuex-pathify' 23 | 24 | // component 25 | @Component 26 | export default class Basket extends Vue { 27 | @Get('products/items') items 28 | @Sync('products/tax') tax 29 | @Call('products/setDiscount') setDiscount 30 | } 31 | ``` 32 | 33 | **TS** 34 | 35 | ```ts 36 | import { Get, Sync, Call } from 'vuex-pathify' 37 | 38 | // component 39 | @Component 40 | export default class Basket extends Vue { 41 | @Get('products/items') items!: Item[] 42 | @Sync('products/tax') tax!: number 43 | @Call('products/setDiscount') setDiscount!: (rate: number) => any 44 | } 45 | ``` 46 | 47 | Which is equivalent of: 48 | 49 | ```js 50 | import { get, sync, call } from 'vuex-pathify' 51 | 52 | export default { 53 | computed: { 54 | items: get('products/items'), 55 | tax: sync('products/tax'), 56 | }, 57 | 58 | methods: { 59 | setDiscount: call('products/setDiscount') 60 | } 61 | } 62 | ``` 63 | 64 | ## API 65 | 66 | Please see [component helpers' single-property-access API](api/component?id=single-property-access). 67 | -------------------------------------------------------------------------------- /docs/pages/guide/paths.md: -------------------------------------------------------------------------------- 1 | # Path syntax 2 | 3 | > Access the store and its properties with a powerful, declarative path syntax 4 | 5 | ## Overview 6 | 7 | Pathify provides a rich [path syntax](#core-syntax) to access Vuex stores, including: 8 | 9 | - module, property and sub-property access 10 | - variable expansion 11 | - wildcard expansion 12 | 13 | There are some additional [direct syntaxes](#direct-syntax) as well, which are designed to handle customisation around non `get/set` naming: 14 | 15 | - direct access 16 | - direct sync 17 | 18 | 19 | ## Usage 20 | 21 | Paths are used throughout Pathify: 22 | 23 | ```js 24 | // global 25 | store.get('items') 26 | store.set('products/items', items) 27 | 28 | // components 29 | computed: { 30 | search: sync('products/filters@search') 31 | } 32 | ``` 33 | 34 | See the path syntax [demo](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=api/paths) for an editable, live example. 35 | 36 | 37 | 38 | ## Syntax 39 | 40 | ### Core syntax 41 | 42 | #### `Property access` 43 | 44 | Properties are accessed by simply referencing the state name: 45 | 46 | ```js 47 | // [ ... ] 48 | get('items') 49 | ``` 50 | 51 | #### `Module access` 52 | 53 | Modules are accessed by providing the full path to to the module: 54 | 55 | If the example above was in a module called `products`, it would be accessed like so: 56 | 57 | ```js 58 | // [ ... ] 59 | get('products/items') 60 | ``` 61 | 62 | 63 | #### `Sub-property access` 64 | 65 | Sub-property access requires the `@` character, and allows you to read sub-properties to any depth: 66 | 67 | ```js 68 | // first-level properties 69 | get('filters@search') 70 | ``` 71 | ```js 72 | // nested properties using dot notation 73 | get('filters@sort.key') 74 | ``` 75 | ```js 76 | // array access using dot or bracket notation 77 | get('items@0') 78 | get('items@[0].name') 79 | ``` 80 | 81 | To transparently **write** sub-properties, use the [make.mutations()](/guide/store.md#make-mutations) helper or the [Payload](/guide/properties.md#payload-class) class. 82 | 83 | ```js 84 | set('filters@search', 'blue') 85 | ``` 86 | 87 | See the [sub-property access](/guide/properties.md#sub-property-access) section for more information. 88 | 89 | 90 | ### Variable expansion 91 | 92 | Variable `:notation` allows you to use component properties to dynamically build references to store properties. 93 | 94 | They may only be used in [component helpers](/guide/component.md) but can reference store properties or sub-properties: 95 | 96 | ```js 97 | // dynamically reference a property or sub-property 98 | get('projects/:slug') 99 | get('projects@:slug') 100 | 101 | // dynamically sync a deeply-nested property using object and array notation using multiple variables 102 | sync('clients/:name@project[:index].name') 103 | ``` 104 | 105 | Note the following caveats: 106 | 107 | - only top-level properties may be used as variable names, i.e. `:index` but not `:options.index` 108 | - when getting, only `state` will be referenced; `getters` will be ignored 109 | - when setting, only `mutations` will be referenced; `actions` will be ignored 110 | - you can use array `[:index]` or dot `.index` notation for arrays 111 | 112 | ### Wildcard expansion 113 | 114 | Wildcards `*` allow you to reference multiple properties at once, and are used only in components: 115 | 116 | They don't **return** values like other path references, rather they **generate** a hash of named functions for all properties that they expand to: 117 | 118 | ```js 119 | // generate getters for `items`, `search` and `filters` 120 | computed: { 121 | ...get('products/*') 122 | }, 123 | 124 | // generate methods that dispatch `load` and `update` 125 | methods: { 126 | ...call('products/*') 127 | } 128 | ``` 129 | 130 | 131 | See the [component helpers](/guide/component.md#wildcard-property-access) page for more info. 132 | 133 | 134 | 135 | ### Direct syntax 136 | 137 | Pathify has two syntax types which are used to handle customisation around non get/set naming. 138 | 139 | #### `Direct access` 140 | 141 | Direct access syntax uses a bang `!` to skip mapping and access Vuex members directly: 142 | 143 | ```js 144 | set('update!', items) 145 | ``` 146 | 147 | See the [properties](/guide/properties.md#direct-property-access) page for more info. 148 | 149 | #### `Direct sync` 150 | 151 | Direct sync syntax uses a pipe `|` to specify alternate get and set members in component helpers: 152 | 153 | ```js 154 | computed: { 155 | items: sync('items|update!') 156 | } 157 | ``` 158 | 159 | See the [component helpers](/guide/component.md#sync) page for more info. 160 | -------------------------------------------------------------------------------- /docs/pages/guide/properties.md: -------------------------------------------------------------------------------- 1 | # Advanced property access 2 | 3 | > Detailed information on store property access 4 | 5 | ## Overview 6 | 7 | Pathify's unified path syntax and mapping simplifies property access to Vuex, at the expense of some minor flexibility. 8 | 9 | This section covers: 10 | 11 | - [accessor priority](#accessor-priority) - how Pathify simplifies get / set operations 12 | - [direct property access](#direct-property-access) - how to override mapping and target properties manually 13 | - [sub-property access](#sub-property-access) - how Pathify writes to state sub-properties 14 | - [errors](#errors) - what happens if Pathify fails to map a path to a store member 15 | 16 | 17 | ## Usage 18 | 19 | See the advanced property access [demo](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=api/properties) for an editable, live example. 20 | 21 | ## Details 22 | 23 | ### Accessor priority 24 | 25 | As outlined in the [intro](/intro/pathify.md) Pathify **automatically** determines whether to get via **state or getters**, or set via **actions or mutations**. This feature is called **Accessor Priority** and results in a significant simplification of Vuex's API. 26 | 27 | The basic premise is this: 28 | 29 | - Vuex has 2 ways to: 30 | - get data; **state** and **getters** 31 | - set data; **mutations** and **actions** 32 | - when accessing a property, say `items`, if found: 33 | - a mapped **getter** will be prioritised over a mapped **state** (as the getter will reference it) 34 | - a mapped **action** will be prioritised over a mapped **mutation** (as the action will call it) 35 | 36 | 37 | This logic and implementation serves several purposes: 38 | 39 | 1. Reduces the decision making process outside of the store; if you want a value, you just **ask for it** 40 | 41 | ```js 42 | // don't care about the implementation, just get/set the value 43 | store.get('items') 44 | store.set('items', data) 45 | ``` 46 | 47 | 2. Reduces awkward syntax juggling in modules: 48 | 49 | ```js 50 | // single, unified format 51 | store.get('products/items') 52 | ``` 53 | ```js 54 | // rather than... 55 | store.state.products.items 56 | store.getters['products/items'] 57 | ``` 58 | 59 | 3. Supports a pattern where the `state` can be the "single source of truth" and the `getter` works as a "transformer" function: 60 | 61 | ```js 62 | state: { 63 | // store item objects... 64 | items: [ {}, {}, ... ], 65 | }, 66 | getters: { 67 | // ...return Item models 68 | items (state) => state.items.map(item => new Item(item)) 69 | } 70 | ``` 71 | 72 | Overall the prioritised approach covers the majority of get/set wiring cases, and enables Pathify's APIs to remain simple. 73 | 74 | 75 | 76 | ### Direct property access 77 | 78 | Pathify's [mapping](/setup/mapping.md) algorithm is designed to **map paths to store members** in a predictable 1:1 manner, for example: 79 | 80 | ```js 81 | get('items') // state.items 82 | set('items', data) // actions.setItems 83 | ``` 84 | 85 | This is great for everyday **get/set** usage, but can't account for more nuanced access like `mutations.INCREMENT_VALUE` or `actions.update()`. To work round this, you can reference store members directly. 86 | 87 | #### `Direct access syntax` 88 | 89 | To **skip** mapping and reference a member directly, append a bang `!` to the property name: 90 | 91 | ```js 92 | // call the `INCREMENT_VALUE` mutation directly 93 | set('INCREMENT_VALUE!') 94 | ``` 95 | ```js 96 | // call the `update()` action, rather than `setItems()` 97 | set('update!', data) 98 | ``` 99 | 100 | Note that even though direct access syntax skips the mapping function, it still respects [accessor priority](/guide/properties.md#accessor-priority). 101 | 102 | 103 | #### `Vuex aliases` 104 | 105 | To skip Pathify entirely when setting data, you can use **Vuex aliases**. 106 | 107 | These are Vuex's own methods, but bound to your project's store, and for convenience, available as imports from Pathify: 108 | 109 | ```js 110 | // import 111 | import { commit, dispatch } from 'vuex-pathify' 112 | 113 | // mutations 114 | commit('INCREMENT_VALUE') 115 | 116 | // actions 117 | dispatch('update', data) 118 | ``` 119 | 120 | #### `Access Vuex directly` 121 | 122 | Finally, you can simply access your store **directly**: 123 | 124 | ```js 125 | // get value 126 | const items = this.$store.state.items 127 | 128 | // set value 129 | this.$store.dispatch('update', data) 130 | ``` 131 | 132 | 133 | ### Sub-property access 134 | 135 | Sub-property **reads** are handled transparently by Pathify's store accessors, whilst sub-property **writes** are handled by the store helper's [make.mutations()](/guide/store.md#make-mutations) method. If your mutations are created using the helper, then sub-property writes will be handled automatically. 136 | 137 | If you've written your own mutations and you're using store accessors or component helpers then you'll need to manually handle the Payload class. 138 | 139 | #### `Payload class` 140 | 141 | The `Payload` class is passed to mutations from Pathify's accessor helpers when a path expression includes sub-property access. The class communicates the sub-property `path` and `value`, as well as encapsulating `update()` functionality, and checking for permission to write or even create sub-properties. 142 | 143 | As mentioned, `make.mutations()` takes care of all sub-property writes automatically, but if you need to do it yourself, here's an example of manually creating a mutation function and what to do with the passed Payload: 144 | 145 | ```js 146 | // store 147 | import { Payload } from 'vuex-pathify' 148 | import _ from 'lodash' 149 | 150 | const state = { 151 | sort: { 152 | key: 'id', 153 | order: 'asc' 154 | } 155 | } 156 | 157 | const mutations = { 158 | // manually-created sort mutator 159 | SET_SORT: (state, payload) => { 160 | // debug 161 | console.log('payload', payload) 162 | 163 | // if we have a Payload, do something with it 164 | if (payload instanceof Payload) { 165 | 166 | // either, update using payload... 167 | state.sort = payload.update(state.sort) 168 | 169 | // ...or, update using dot-notation `path` 170 | _.set(state.sort, payload.path, payload.value) 171 | } 172 | 173 | // otherwise, handle normally 174 | else { 175 | state.sort = payload 176 | } 177 | } 178 | } 179 | ``` 180 | ```js 181 | // global 182 | store.set('sort@order', 'desc') 183 | ``` 184 | 185 | 186 | 187 | ### Errors 188 | 189 | In the event that a supplied path does not map to a property, Pathify will let you know: 190 | 191 | ```js 192 | // would map to `mutations.SET_FOO` or `actions.setFoo` 193 | store.set('foo', false) 194 | ``` 195 | ```text 196 | [Vuex Pathify] Unable to map path 'foo': 197 | - Did not find action 'setFoo' or mutation 'SET_FOO' on store 198 | - Use path 'foo!' to target store member directly 199 | ``` 200 | 201 | As a developer you can update the path or use any of the direct access methods above. 202 | -------------------------------------------------------------------------------- /docs/pages/guide/store.md: -------------------------------------------------------------------------------- 1 | # Store helpers 2 | 3 | 4 | > Store helpers eliminate store boilerplate 5 | 6 | ## Overview 7 | 8 | Store helpers **eliminate boilerplate** by creating redundant 1:1 wiring functions from a supplied state object. 9 | 10 | They are implemented as **helper functions** which: 11 | 12 | - can include only certain store members 13 | - can be mixed in with additional declarations 14 | 15 | Each helper builds and returns the appropriate JavaScript functions. 16 | 17 | 18 | ## Usage 19 | 20 | The following example illustrates functionality and usage for all the helper functions: 21 | 22 | ```js 23 | import Api from 'services/Api' 24 | import { make } from 'vuex-pathify' 25 | 26 | const state = { 27 | items: [], 28 | status: '', 29 | filters: { 30 | search: '', 31 | sort : { ... } // object sub-properties 32 | } 33 | } 34 | 35 | // make all mutations 36 | const mutations = make.mutations(state) 37 | 38 | const actions = { 39 | // automatically create only `setItems()` action 40 | ...make.actions('items'), 41 | 42 | // manually add load items action 43 | loadItems({ dispatch }) { 44 | Api.get('items').then(data => dispatch('setItems', data)) 45 | }, 46 | } 47 | 48 | const getters = { 49 | // make all getters (optional) 50 | ...make.getters(state), 51 | 52 | // overwrite default `items` getter 53 | items: state => { 54 | return state.items.map(item => new Item(item)) 55 | }, 56 | 57 | // add new `filteredItems` getter 58 | filteredItems: (state, getters) => { 59 | return getters.items.filter(item => item.title.includes(state.filters.search)) 60 | } 61 | } 62 | 63 | export default { 64 | // namespaced: true, // add this if in module 65 | state, 66 | mutations, 67 | actions, 68 | getters, 69 | } 70 | ``` 71 | !> Note that the code specifically demonstrates a **getters/action-heavy store** approach in order to show full usage of the `make.*` helpers. However, the Pathify-recommended approach is to **eschew** redundant getters and actions (those which simply proxy work to state and mutations) and only create mutations, letting Pathify do the heavy-lifting for you. 72 | 73 | See the store helpers [demo](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=api/store) for an editable, live example. 74 | 75 | ## API 76 | 77 | ### Helpers 78 | 79 | #### `make.mutations(state: Object | Array | String | Function): Object` 80 | 81 | Use `make.mutations()` to generate default mutations for your state object: 82 | 83 | ```js 84 | const mutations = make.mutations(state) 85 | ``` 86 | 87 | The helper generates the following code: 88 | 89 | ```js 90 | // `key` is a scoped variable unique to each created function 91 | mutations = { 92 | SET_ITEMS: (state, value) => state.items = value instanceof Payload 93 | ? value.update(state[key]) 94 | : value, 95 | SET_STATUS: (state, value) => state.search = value instanceof Payload 96 | ? value.update(state[key]) 97 | : value, 98 | SET_FILTERS: (state, value) => state.filters = value instanceof Payload 99 | ? value.update(state[key]) 100 | : value, 101 | } 102 | ``` 103 | 104 | Note transparent support for [sub-property writes](/guide/properties#sub-property-access) thanks to the Payload class. 105 | 106 | 107 | #### `make.actions(state: Object | Array | String | Function): Object` 108 | 109 | You can use `make.actions()` to generate default actions for your state object: 110 | 111 | ```js 112 | const actions = make.actions(state) 113 | ``` 114 | 115 | The helper generates the following code: 116 | 117 | ```js 118 | const actions = { 119 | setItems: ({commit}, value) => commit('SET_ITEMS', value), 120 | setStatus: ({commit}, value) => commit('SET_STATUS', value), 121 | setFilters: ({commit}, value) => commit('SET_FILTERS', value), 122 | } 123 | ``` 124 | 125 | If using Pathify as your core store access mechanism, you generally don't need to create redundant actions, but if you're the kind of developer who prefers accessing the store by **actions only**, this will save you writing them all yourself. 126 | 127 | 128 | #### `make.getters(state: Object | Array | String | Function): Object` 129 | 130 | You can use `make.getters()` to generate default getters for your state object: 131 | 132 | ```js 133 | const getters = make.getters(state) 134 | ``` 135 | 136 | The helper generates the following code: 137 | 138 | ```js 139 | const getters = { 140 | items: state => state.items, 141 | status: state => state.search, 142 | filters: state => state.filters, 143 | } 144 | ``` 145 | 146 | If using Pathify as your core store access mechanism, you generally don't need to create redundant getters, but if you're the kind of developer who prefers accessing the store by **getters only**, this will save you writing them all yourself. 147 | 148 | 149 | ### Partial generation 150 | 151 | The `make.*` helpers take a variety of argument types, with the expectation to pass in an existing `state` object and create helpers for **all** properties: 152 | 153 | ```js 154 | const state = { ... } 155 | const mutations = make.mutations(state) 156 | ``` 157 | 158 | However, you can generate only **some** properties by passing alternative parameters: 159 | 160 | 161 | ```js 162 | // strings have properties parsed from them 163 | const mutations = make.mutations('items status') 164 | ``` 165 | ```js 166 | // arrays use the passed values 167 | const mutations = make.mutations(['items', 'status']) 168 | ``` 169 | ```js 170 | // objects use the passed keys 171 | const mutations = make.mutations({items: true, status: true}) 172 | ``` 173 | ```js 174 | // functions will be executed; any of the above types can be returned 175 | function state () { ... } 176 | const mutations = make.mutations(state) 177 | ``` 178 | -------------------------------------------------------------------------------- /docs/pages/home.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Vuex Pathify 4 | 5 | > Pathify provides a declarative, state-based, path interface to your Vuex store 6 | 7 | With Pathify, you access Vuex by **path**: 8 | 9 | ```pathify 10 | 'foo/bar@a.b.c' 11 | ``` 12 | 13 | Paths can reference any **module**, **property** or **sub-property**: 14 | 15 |  16 | 17 | 18 | **Get** or **set** data without **syntax juggling** or worrying about **implementation**: 19 | 20 | ```pathify 21 | store.get('loaded') 22 | ``` 23 | ```pathify 24 | store.set('loaded', true) 25 | ``` 26 | 27 | Reach into **sub-properties** and **arrays**: 28 | 29 | ```pathify 30 | store.get('products@items.0.name') 31 | store.set('products@items.1.name', 'Vuex Pathify') 32 | ``` 33 | 34 | Set up **one or two-way** data binding on **any** store value without **bloat** or **fuss**: 35 | 36 | ```pathify 37 | computed: { 38 | products: get('products'), 39 | category: sync('filters@category') 40 | } 41 | ``` 42 | 43 | Wire **multiple** properties (or sub-properties) using **array**, **object** and **wildcard** formats: 44 | 45 | ```pathify 46 | computed: { 47 | ...sync('filters@sort', [ 48 | 'order', 49 | 'key' 50 | ]), 51 | 52 | ...sync('filters@sort', { 53 | sortOrder: 'order', 54 | sortKey: 'key' 55 | }), 56 | 57 | ...sync('filters@sort.*') 58 | } 59 | ``` 60 | 61 | 62 | Use **variable expansion** to dynamically reference store properties: 63 | 64 | ```pathify 65 | computed: { 66 | product: get('products@items:index') 67 | } 68 | ``` 69 | 70 | 71 | Set up mutations – **including sub-property mutations** – in a single line: 72 | 73 | ```pathify 74 | make.mutations(state) 75 | ``` 76 | 77 | And that's it! 78 | 79 | In practical terms, Pathify results in: 80 | 81 | - less cognitive overhead 82 | - zero store boilerplate 83 | - one-liner wiring 84 | - cleaner code 85 | - lighter files 86 | 87 | ### Next steps 88 | 89 | To get started: 90 | 91 | - visit the [Installation](/setup/install.md) page to install and use Pathify now 92 | - read the [Guide](/guide/paths.md) for a deep dive into Pathify's features 93 | - read the [API](/reference/api.md) to see just the code 94 | 95 | To see Pathify in action: 96 | 97 | - check the editable CodeSandbox [demos](/intro/demos.md) 98 | 99 | For a deeper insight: 100 | 101 | - read the [Intro](/intro/pathify.md) for an overview of the Pathify mechanism 102 | - check out the [code comparison](https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main?initialpath=code) demos which illustrate reductions in Vuex code of between **2 and 14 times** 103 | -------------------------------------------------------------------------------- /docs/pages/intro/demos.md: -------------------------------------------------------------------------------- 1 | # Demos 2 | 3 | > See Pathify in action 4 | 5 | Playing with the code is often the quickest way to see how a library works, so Pathify has a bunch of editable demos. 6 | 7 | Demos can viewed and edited [online](https://codesandbox.io/s/github/davestewart/vuex-pathify/tree/master/demo) or [downloaded](https://github.com/davestewart/vuex-pathify-demos) and run locally. 8 | 9 | 10 | ## Simple demo 11 | 12 | This demo shows a basic, 2-property store setup with Pathify component wiring. 13 | 14 | [][simple] 15 | 16 | The demo is completely self-contained and is in effect a Pathify starter template. 17 | 18 | To load the simple demo, click [here][simple]. 19 | 20 | ## Main demo 21 | 22 | This set of demos contains a range of components + store setups illustrating both API and real-world usage: 23 | 24 | [][main] 25 | 26 | Use the navigation to load the demos, then click the green buttons at the top to edit the associated files: 27 | 28 |  29 | 30 | To load the main demo, click [here][main]. 31 | 32 | ## Nuxt demo 33 | 34 | Finally, there is a [Nuxt](https://nuxtjs.org/) demo, to ensure that Pathify works correctly on the server side. 35 | 36 | Rather than being viewable in a browser, the Nuxt demo must be downloaded, installed and run locally. 37 | 38 | To view the repository, click [here](https://github.com/davestewart/vuex-pathify-demos/tree/master/nuxt). 39 | 40 | [simple]: https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/simple?module=%2Fsrc%2Fcomponents%2FHelloWorld.vue 41 | [main]: https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/main 42 | -------------------------------------------------------------------------------- /docs/pages/intro/pathify.md: -------------------------------------------------------------------------------- 1 | 2 | # Pathify 101 3 | 4 | > How Pathify does what it does 5 | 6 | Pathify's aim is to **simplify** the overall Vuex development experience. 7 | 8 | Its core mechanism is a custom [path syntax](/guide/paths.md) which can reference any state property: 9 | 10 | ```js 11 | 'products/items@filters.search' 12 | ``` 13 | 14 | Paths are [mapped](/setup/mapping.md) to store members via a configurable naming scheme: 15 | 16 | ```js 17 | Operation Member Name Scheme 18 | 19 | read state foo // base name 20 | read getters foo // no prefix, no case conversion 21 | write mutations SET_FOO // "set" prefix, constant case, 22 | write actions setFoo // "set" prefix, camel case, 23 | ``` 24 | 25 | Store [access](/guide/accessors.md) and component [wiring](/guide/component.md) are unified with `get()`, `set()`, `sync()` and `call()` methods: 26 | 27 | ```js 28 | // global 29 | const items = store.get('products/items') 30 | store.set('products/items', items) 31 | 32 | // component 33 | computed: { 34 | total: get('products/total'), 35 | items: sync('products/items') 36 | }, 37 | 38 | methods: { 39 | submit: call('products/submit') 40 | } 41 | ``` 42 | 43 | Implementation details are simplified by [prioritising](/guide/properties.md) **getters over state** and **actions over mutations**: 44 | 45 | ```js 46 | Pathify Vuex 47 | 48 | store.get('products/items') <- store.getters['products/items'] 49 | store.state.products.items 50 | store.set('products/items', items) -> dispatch('products/setItems', items) 51 | commit('products/SET_ITEMS', items) 52 | ``` 53 | 54 | 55 | The overall approach results in a significant simplification of Vuex's API: 56 | 57 | - from **4** operations, **4** helpers, **3** accessor syntaxes and **3** (or sometimes **4**) naming formats 58 | - to **4** methods and **1** path format 59 | 60 | For store members that don't fit the "set/get" paradigm, there are several [direct access](/guide/properties.md#direct-property-access) mechanisms available. 61 | 62 | Finally, [store helpers](/guide/store.md) provide transparent sub-property access whilst **eliminating** store setup boilerplate: 63 | 64 | ```js 65 | const mutations = make.mutations(state) 66 | ``` 67 | 68 | 69 | The end result a **radical** reduction in store setup, component wiring, lines of code and cognitive overhead, leaving you more time and bandwidth to build your application. 70 | -------------------------------------------------------------------------------- /docs/pages/reference/api.md: -------------------------------------------------------------------------------- 1 | # API 2 | 3 | > Pathify's full API 4 | 5 | Whilst the guide deep-dives to explain how Pathify works, this section is just a high-level reference to the code: 6 | 7 | - [Store Helpers](#store-helpers)Vuex Pathify
5 |Ridiculously simple Vuex setup + wiring
6 |
28 | Important!
29 | Because of the way ES6 imports work, configuration must be saved in a standalone file and must be imported before any store files.
30 |
Remember:
Failing to import Pathify configuration before store imports will result in the default settings being used. This will result in a broken app and lots of console errors as mutation and action identifiers will be wrong.
(
146 | payloadWithType: P,
147 | options?: CommitOptions
148 | ): void;
149 |
150 | /*--------------------------------------------------------------------------
151 | dispatch
152 | ------------------------------------------------------------------------*/
153 | // Copied from vuex types.
154 | export function dispatch(
155 | type: string,
156 | payload?: any,
157 | options?: DispatchOptions
158 | ): Promise (
160 | payloadWithType: P,
161 | options?: DispatchOptions
162 | ): Promise {
13 | get: (path: string, ...args: any[]) => any;
14 | set: (path: string, value: any) => any | Promise