Vue-banque NPM

Vue Banque

Vue Banque is a mini state storage system for vue-next(vue3) which only with 2KB tiny size.

Features

2KB tiny size.
Banque Module is ES6 destructurable, default auto implemented toRef when destructuring.
State Modify Protect for states accessing from Banque Module by default.
Cross Module Access for access states between modules.
Functional Banque Module can be reusable for creating multiple times of the same module.

Install

$ npm install vue-banque

Usage

Create Module

Create your first banque module, and easliy export with export default.

// store/Game.js
import { ref } from 'vue';

const count = ref(0);

export default {
  count,
}

Create Banque

Create Vue Banque with your modules

// store/index.js
import { createBanque } from 'vue-banque';
import Game from './Game';

const banque = createBanque({
  strict: true,
  autoToRef: true,
  modules: { Game },
});

export default banque;

// expose your custom hook by calling `banque.inject()`
export function useBanque() {
  // you can do something cool...
  // this will expose `banque.rootState`
  return banque.inject();
}

Use Banque

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import banque from './store';

createApp(App).use(banque).mount('#app');

Use in setup

<script setup>
import { useBanque } from '@/store';

const { Game } = useBanque();

// by default, destructured items will auto implemented with `toRef`
const { count } = Game; // Ref
console.log(count.value);
</script>

this feature is opened by default, you can change settings in options by setting autoToRef with boolean type value.
be aware that if you turn the autoToRef with false, there might cause some typescript types warning on Ref type.

Access for states

each module accessed from rootState will be protected with readonly by default. All property will be wrapped with toRef output, only function in module will be wrapped without toRef.

import { useBanque } from '@/store';

const { Game } = useBanque();
const { count } = Game;

count.value += 1;
// warn: Set operation on key "value" failed: target is readonly.

this feature is opened by default, you can change settings in options by setting strict with boolean type value.

Define Action

functions in module will be wrapped with rootState as global context in first param, so we can access every modules by using it.

Since the rootState context acts same behavior as in component setup function, we cant modify states directly, states will only be allowed to be modified in the module define scope.

// store/Game.js
import { ref } from 'vue';

const count = ref(0);

// first param context will be auto generated by `Vue Banque`
function add(context, mystep = 1) {
  console.log(context); // { Game }
  count.value += mystep;
}

export default {
  count,
  add,
}

Cross Module Demo

define a new module

// store/index.js
import { createBanque } from 'vue-banque';
import Api from './Api';
import Game from './Game';

const banque = createBanque({
  modules: { Api, Game },
});

// ...

api module

// store/Api.js
import { ref } from 'vue';

const APILoading = ref(false);

function updateAPILoading(context, bool) {
  APILoading.value = bool;
}

export default {
  APILoading,
  updateAPILoading,
}

game module

// store/Game.js
import { ref } from 'vue';

const count = ref(0);

// first param context will be auto generated by `Vue Banque`
function add({ Api }, mystep = 1) {
  Api.updateAPILoading(true);
  count.value += mystep;
  Api.updateAPILoading(false);
}

export default {
  count,
  add,
}

use action in components

<template>
  <p>Count: {{ count }}</p>
  <div @click="add(3)">ADD</div>
</template>

<script setup>
import { useBanque } from '@/store';

const { Game } = useBanque();

const { count, add } = Game;
</script>

Reusable Module

if we want to reuse a module, easily export a module factory function, then import the function to options.modules, function type module will be auto generate by Vue Banque.

// store/Game.js
import { ref } from 'vue';

function GameModule() {
  const count = ref(0);

  function add(context, mystep = 1) {
    count.value += mystep;
  }

  return {
    count,
  }
}

export default GameModule;

then we can reuse it for creating multiple modules. Each states of modules will be seperated.

// store/index.js
import { createBanque } from 'vue-banque';
import Api from './Api';
import Game from './Game';

const banque = createBanque({
  modules: {
    Game1: Game,
    Game2: Game,
    Game3: Game,
  },
});

// ...

Use with optional API

by default, the $banque key in this stands for the global context. we can change the globalName by setting options.globalName to whatever we like.

export default {
  mounted() {
    const { Game } = this.$banque;
    const { count, add } = Game;

    add();
    console.log(count.value);
  },
};

Typescript Support

Since Vue Banque is writen by Typescript, so you can easily used with Typescript as following:

Create Banque

import BanqueContext type from vue-banque, and create you banque root type by it, so that vue-banque can auto generate all your module types.

// store/index.ts
import { createBanque, BanqueContext } from 'vue-banque';
import Game from './Game';

export type BanqueRoot = BanqueContext<{
  Game: typeof Game,
}>;

const banque = createBanque<BanqueRoot>({
  strict: true,
  autoToRef: true,
  globalName: '$banque',
  modules: { Game },
});

export default banque;

export function useBanque() {
  return banque.inject();
}

Create Module

// store/Game.ts
import { ref } from 'vue';
import { BanqueRoot } from './index';

const count = ref<number>(0);

function add(context: BanqueRoot, mystep: number = 1): void {
  const { Game } = context;
  /* typeof Game
    const Game: BanqueModule<{
      count: Ref<number>;
      add: (context: BanqueRoot, mystep?: number) => void;
    }>
  */
  Game.add();
  /* typeof add
    (property) add: (mystep?: number | undefined) => void
  */
  count.value += mystep;
}

export default {
  count,
  add,
}