https://github.com/nash403/expecto
Manage your loading states (with first-class integration with Vue.js)
https://github.com/nash403/expecto
expecto loaders loading-state state-management vue vuex wait
Last synced: 3 months ago
JSON representation
Manage your loading states (with first-class integration with Vue.js)
- Host: GitHub
- URL: https://github.com/nash403/expecto
- Owner: nash403
- License: mit
- Created: 2019-06-19T21:08:01.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-09T06:59:12.000Z (almost 3 years ago)
- Last Synced: 2025-06-25T00:49:47.412Z (4 months ago)
- Topics: expecto, loaders, loading-state, state-management, vue, vuex, wait
- Language: JavaScript
- Size: 1.73 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Expecto
> Manage your loading states (with first-class integration with Vue.js)
## Install
Wit NPM:
```
$ npm install @nashlabs/expecto
```
With Yarn:
```
$ yarn add @nashlabs/expecto
```
## Usage
With pure JS:
```js
import { expecto } from '@nashlabs/expecto'
// Start a loader (when no argument is passed, '' will be used as the default loader ID)
expecto.startLoading('someLoaderID') // now `expecto.isLoading('someLoaderID')` & `expecto.anyLoading` return `true`
// Stop a loader
expecto.stopLoading('someLoaderID')
// With a callback Expecto will automatically stop the loader
const processedResponse = await expecto.startLoading('someLoaderID', () => { // The cb must return a Promise-like object or it will throw a `TypeError`
return fetchData().then(response => processData(response))
})
```
With pure Vue.js:
```js
import Vue from 'vue'
import Vuex from 'vuex'
import { createVuexPlugin, createVuePlugin } from '@nashlabs/expecto'
const store = new Vuex.Store({
// ...
plugins: [createVuexPlugin()] // this will register a new namespaced module to manage your loading states. You can pass a different namespace as first argument (default: 'loaders')
})
Vue.use(createVuePlugin({ // This needs vuex plugin to be installed
namespace, // default: 'loaders'
componentName, // default: 'VWait'
className // an array of CSS classes to apply on component (default: ['expecto'])
}))
// This will add `$isLoading`, `$anyLoading`, `$startLoading` & `$stopLoading` to `Vue.prototype`. Use `createComponent` instead if you don't want `Vue.prototype` to be poluted
```
Then in your components:
```html
// VWait Component (needs vuex plugin to be installed)
{ slot content }
This will be displayed in place of the default slot only if you pass `true` to the `:empty` prop.
It can be helpful to display a 'No data' component after loading.
```
This is what you need to know about the module that is registered in the store when you call `createVuexPlugin`
```js
store.registerModule(namespace, {
// ...
getters: {
isLoading : state => ..., // same thing as calling expecto.isLoading(...)
anyLoading: state => ..., // same thing as calling expecto.anyLoading
},
actions: {
startLoading: ({commit}, { loaderId, callback }) => ..., // same thing as calling expecto.startLoading(loaderId, callback)
stopLoading: ({commit}, { loaderId }) => ..., // same thing as calling expecto.stopLoading(loaderId)
},
// ...
})
```
## Tips
### **Tip 1:** `isLoading` can take a function as an argument instead of a loaderId.
In that case, it will behave exactly like the function argument passed to `Array.prototype.findIndex`. Each currently loading loaderId is be passed to the function until it returns true and the loop stops. `isLoading` will return true only if the function returned true for at least one id.
```js
expecto.isLoading(id => /^UID-.*/.test) // returns `true` if one id starts with 'UID-'
```
### **Tip 2:** Need to call vuex manually ?
```js
$store.dispatch(`/startLoading`, { loaderId, callback }, { root: true })
```
### **Tip 3:** The class used under the hood (`ExpectoWrapper`) is also exposed.
By creating new instances of it, you can have different and isolated loading state managers.
```js
$store.dispatch(`/startLoading`, { loaderId, callback }, { root: true })
```
## License
MIT © [Honoré Nintunze](https://nintu.me)