# v-bucket [](https://codecov.io/gh/mediv0/v-bucket) [](https://www.code-inspector.com/project/13923/status/svg) [](https://codeclimate.com/github/mediv0/v-bucket/maintainability) [](https://img.shields.io/github/license/mediv0/v-bucket) [](https://img.shields.io/github/release-date/mediv0/v-bucket)
**NPM STATUS:** [](https://img.shields.io/npm/v/@mediv0/v-bucket?style=plastic) [](https://img.shields.io/bundlephobia/minzip/@mediv0/v-bucket) [](https://img.shields.io/npm/dt/@mediv0/v-bucket)
> 📦 Fast, Simple, and Lightweight State Management for Vue 3.0 built with composition API, inspired by Vuex.
## Table of Contents
### Main features
- [installation](#installation)
- [usage](#usage)
- [using with composition api]("#using-with-composition-api")
- [using with option api]("#using-with-option-api")
- [states](#states)
- [mutations](#mutations)
- [getters](#getters)
- [actions](#actions)
- [modules](#modules)
### Access modules
- [how to access module states](#how-to-access-module-states)
- [how to access module getters](#how-to-access-module-getters)
- [how to access module mutations](#how-to-access-module-mutations)
- [how to access module actions](#how-to-access-module-actions)
### Advanced
- [plugins](#plugins)
- [plugin hooks](#plugin-hooks)
## Examples
- [CodeSandbox](https://codesandbox.io/s/dank-waterfall-mrfzq)
- [Counter](https://github.com/mediv0/v-bucket/blob/master/examples/components/counter.vue)
- [Shopping Cart](https://github.com/mediv0/v-bucket/blob/master/examples/components/shop.vue)
Running the examples:
```bash
$ npm run dev
$ yarn dev
```
## Running tests
```bash
$ npm run test
$ yarn test
```
## installation
install this package from NPM:
```bash
$ npm install @mediv0/v-bucket
```
or yarn:
```bash
$ yarn add @mediv0/v-bucket
```
## usage
first you need to create your bucket.
create an index.js file, then import createBucket from v-bucket to start creating your store, like this:
```javascript
import { createBucket } from "@mediv0/v-bucket";
const bucket = createBucket({
states: {
// your states here
},
mutations: {
// your mutations here
},
getters: {
// your getters here
},
modules: {
// your modules here
}
});
export default bucket;
```
then import it in your app entry point, main.js like this:
```javascript
import { createApp } from "vue";
import App from "./dev.vue";
// importing your bucket
import bucket from "./bucket/index";
createApp(App)
.use(bucket)
.mount("#app");
```
## using with composition api
for using v-bucket inside the setup() function you need to import useBucket first. like this:
```javascript
```
## using with option api
like vue 2.X apps you can access v-bucket on the vue instance outside of the setup() function. like this:
```javascript
```
_you only import useBucket when you want to use it inside setup() function_
# Note
in case of error
` Named export 'createBucket' not found. The requested module '@mediv0+v-bucket@1.1.2_vue@3.4.35/node_modules/@mediv0/v-bucket/dist/v-bucket.cjs.js' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, `
You can import createBucket from esm module provided in the build `@mediv0/v-bucket/dist/v-bucket.esm-browser.prod` or just import it with default name then destruct `createBucket` function
```js
import vBucket from "@mediv0/v-bucket";
vBucket.createBucket({ ... })
```
## states
this is a single object contains all your application states.
accessing states:
```javascript
mounted() {
// accessing id state in the root level
this.$bucket.state.id
// ...
// accessing name state in the nested tree
this.$bucket.state.module1.name
},
```
declare states inside your bucket (index.js):
```javascript
import { createBucket } from "@mediv0/v-bucket";
const bucket = createBucket({
states: {
id: 1,
name: "mahdi",
phone: 120304
},
mutations: {
// your mutations here
},
getters: {
// your getters here
},
modules: {
// your modules here
}
});
export default bucket;
```
**NOTE:** states object will be reactive by default. that means they will react to changes and update based on it.
**NOTE:** it's better to use mutations or getters to access states.
## mutations
use mutations when you need to change a state value, all mutations will take 2 parameter:
- state
- payload
```javascript
const bucket = createBucket({
mutations: {
SET_ID(state, payload)
},
});
```
with **state**, you can have access to states object and change its value by passing **payload**.
**NOTE:** payload is optional.
```javascript
const bucket = createBucket({
states: {
id: 0,
count: 0
}
mutations: {
SET_ID(state, payload) {
// changing id value
state.id = payload
}
COUNT_UP(state) {
// without payload
state.count++;
}
},
});
```
you can't access mutations directly. you have to call them with commit method. like this:
```javascript
methods: {
click() {
this.$bucket.commit("SET_ID", 5);
this.$bucket.state.id // must be 5 now!
// ...
this.$bucket.commit("SET_ID"); // calling without a payload
}
}
```
## getters
you can use getters to access states and their values. getters are like Vue computed methods, they will cache the state and return it only when the state value change.
```javascript
const bucket = createBucket({
states: {
id: 0,
name: "mahdi",
phone: 893729837
}
getters: {
GET_ID(state) {
return state.id
}
},
});
```
all getters will take 1 parameter:
- state (using to access states object)
using it in your vue app:
```javascript
methods: {
click() {
this.$bucket.getters["GET_ID"] // will return id state
// ...
}
}
```
## actions
Actions are like mutations. the difference is:
- They can handle asynchronous operations
- Instead of mutating the state, actions commit mutations.
```javascript
const bucket = createBucket({
states: {
count: 0
}
mutations: {
increment(state) {
state.count++
}
},
actions: {
increment(context) {
context.commit("increment");
}
// or using argument destructuring to simplify the code.
anotherAction({ commit }) {
// do some action!
commit("someMutation");
}
}
});
```
also you can call other actions with context.dispatch. like this:
```javascript
const bucket = createBucket({
actions: {
actionOne(context) {
context.commit("someMutation");
}
actionTwo(context) {
context.dispatch("actionOne"); // dispatching actionOne from another action!
}
}
});
```
also you can't access actions directly. you have to call them with dispatch method. like this:
```javascript
methods: {
click() {
this.$bucket.dispatch("increment") // will call increment action
// ...
}
}
```
**_the context parameter will return root instance of our bucket. this is useful when working with modules._**
## modules
from vuex docs:
- _Due to using a single state tree, all states of our application are contained inside one big object. However, as our application grows in scale, the store can get really bloated. To help with that, Vuex allows us to divide our store into **modules**._
```javascript
const moduleA = {
states: { ... },
mutations: { ... },
actions: { ... },
modules: { ... }
}
const moduleB = {
states: { ... },
mutations: { ... },
actions: { ... },
modules: { ... }
}
const bucket = createBucket({
modules: {
// register modules
moduleA,
moduleB
}
});
bucket.state.moduleA // `moduleA`'s state
bucket.state.moduleB // `moduleB`'s state
```
**every modules also can have their own states, mutations, actions or even modules**
## how to access module states
all modules will be installed under the root module. so by accessing the root state you can also have access to its children. like this:
```javascript
methods: {
click() {
this.$bucket.state.moduleA.name // `moduleA`'s name state
this.$bucket.state.moduleB.id // `moduleB`'s id state
// ...
}
}
```
## how to access module getters
if you remember we used bracket notation to access getters, you can access your module's getter by defining its path. like this:
```javascript
methods: {
click() {
this.$bucket.getters["moduleA/get_id"]; // `moduleA`'s getter
this.$bucket.getters["moduleB/get_name"]; // `moduleB`'s name state
// you can go deep as many levels as you want
this.$bucket.getters["moduleA/moduleB/moduleC/moduleH/...];
// ...
}
}
```
they above code represent something like this:
-root
-----moduleA
-----moduleB
## how to access module mutations
mutations are like getters, you can access your module's mutation by defining its path. like this:
```javascript
methods: {
click() {
this.$bucket.commit("moduleA/set_id"); // we can access mutations by commit()
this.$bucket.commit("moduleB/set_name"); // we can access mutations by commit()
// ...
}
}
```
## how to access module actions
actions are like getters, you can access your module's actions by defining its path. like this:
```javascript
methods: {
click() {
this.$bucket.dispatch("moduleA/set_id"); // we can access mutations by dispatch()
this.$bucket.dispatch("moduleB/set_name"); // we can access mutations by dispatch()
// ...
}
}
```
sometimes you need to access another module's mutation or action within the current module
since the context parameter refer to the root module, you can access all of your modules by defining their path. like this:
```javascript
// inside module a
const moduleA = {
actions: {
commitModuleB(context) {
context.commit("moduleB/set_name"); // commiting in module b from module a
}
dispatchModuleB(context) {
context.dispatch("moduleB/request"); // dispatching in module b from module a
}
dispatchRoot(context) {
context.dispatch("rootMutation") // dispatching in root from module a
}
}
};
```
**NOTE:** if you want to access a module from another module like example, you need to define your paths from root
## plugins
v-bucket store accept the plugins option that exposes hooks for each mutation and actions. plugins will allow you to extend the functionality of v-bucket
a hello world plugin
```javascript
const helloWorld = () => {
// called when the store is initialized
console.log("hello world");
return bucket => {
// access bucket store
};
};
export const bucket = createBucket({
// other options
// ...
plugins: [helloWorld()]
});
```
the function that has the responsibility to be a plugin, need to return another function.
v-bucket will use that function to expose the root module and its hooks
## plugin hooks
there are two hooks available:
#### bucket.onMutation(callback(mutation))
this function will be called after every mutation.
also, it will return information about the mutation that has been fired.
this information contains: name, module and full path of that mutation.
#### bucket.onAction(callback(action))
this function will be called after every action.
also, it will return information about the action that has been fired.
this information contains: name, module and full path of that action.
**usage:**
```javascript
const myPlugin = socket => {
return bucket => {
socket.on("data", data => {
store.commit("receiveData", data);
});
store.onMutation(mutation => {
if ((mutation.name = "UPDATE_DATA")) {
socket.emit("update", mutation.payload);
}
});
};
};
```
if you want use Class syntaxt, no worries! do something like this:
```javascript
Class Snapshot {
// other methods and options
// ...
constructor() {
this.snapshots = [];
}
plugin() {
return bucket => {
bucket.onMutation(mutation => {
if (mutation.name = "UPDATE_SNAPSHOT") {
this.snapshots.push(mutation.payload);
}
})
}
}
}
```
easy right?
and use it like this in your store:
```javascript
export const bucket = createBucket({
// other options
// ...
plugins: [new Snapshot().plugin()]
});
```
Since you have access to the bucket root module in the plugins, you also able to commit, dispatch and use getters.
## Contribution
Please make sure to read the [Contributing Guide](https://github.com/mediv0/v-bucket/blob/master/.github/contributing.md) before making a pull request.
**feel free to request new features!**
## License
[MIT](http://opensource.org/licenses/MIT)
## Todo
- [ ] mapGetters
- [ ] mapActions
- [ ] optimization and refactoring
- and more....