v-bucket

NPM STATUS:

📦 Fast, Simple, and Lightweight State Management for Vue 3.0 built with composition API, inspired by Vuex.

Table of Contents

Main features

• installation
• usage
• using with composition api
• using with option api
• states
• mutations
• getters
• actions
• modules

Access modules

• how to access module states
• how to access module getters
• how to access module mutations
• how to access module actions

Advanced

• plugins
• plugin hooks

Examples

• CodeSandbox
• Counter
• Shopping Cart

Running the examples:

$ npm run dev
$ yarn dev

Running tests

$ npm run test
$ yarn test

installation

install this package from NPM:

$ npm install @mediv0/v-bucket

or yarn:

$ 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:

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:

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:

<script>
import { useBucket } from "@mediv0/v-bucket"
export default {
    setup() {
        // get access to the v-bucket
        const bucket = useBucket();

        // ...

        return {
            // ....
        };
    }
};
</script>

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:

<script>
export default {
    mounted() {
        // accessing bucket on this
        this.$bucket

        // ...
    },
    methods: {
      click() {
        this.$bucket.commit("SET_ID", this.id);

        // ...
      }
    }
};
</script>

you only import useBucket when you want to use it inside setup() function

states

this is a single object contains all your application states.

accessing states:

 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):

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

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.

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:

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.

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:

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.

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:

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:

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.

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:

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:

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:

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:

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:

// 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

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:

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:

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:

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 before making a pull request.

feel free to request new features!

License

MIT

Todo

• mapGetters
• mapActions
• optimization and refactoring
• and more....