README.md

vuex-coolstory

Use redux-saga with Vuex.

Overview

redux-saga is an awesome library that aims to make side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) easier and better.

While originally targetting Redux, redux-saga is actually not strictly tied to redux and do not rely on any internals of it's implementation. Actually redux-saga could be used with Vuex with put effect commiting mutations

This library wraps redux-saga so it can be used as Vuex plugin. It's external interface is similar to middleware provided by redux-saga.

Differences from vuex-redux-saga

vuex-redux-saga not work with latest redux-saga, uses subcribe to commits hook as redux-saga action channel, and looks like abandoned. This package support latest version of redux-saga, plus also have mapSagaActions() function for your components. To send actions to saga directly, you can use store.sagaDispatch function. store.sagaDispatch is similar to vuex store.dispacth function.

Installation

$ npm install --save vuex-coolstory redux-saga

Usage

Simple

import Vue from 'vue';
import Vuex from 'vuex';
import { VuexSaga } from 'vuex-coolstory';
import { take, put, race, delay } from 'redux-saga/effects';

Vue.use(Vuex);

// simple saga
function* saga() {
    while (true) {
        const { newItem, timer } = yield race({
            newItem: take('addItem'),
            timer: delay(3000)
        });
        if (timer) {
            yield put({
                type: 'appendItem',
                item: 'TIMER'
            });
        } else if (newItem) {
            yield put({
                type: 'appendItem',
                item: newItem.payload.item
            });
        }
    }
}

export default new Vuex.Store({
    state: {
        items: []
    },
    plugins: [
        VuexSaga({
            sagas: [saga] // pass your sagas to plugin
        })
    ],
    mutations: {
        appendItem(state, { item }) {
            state.items = [...state.items, item];
        }
    }
});

Modules

import Vue from 'vue';
import Vuex from 'vuex';
import { VuexSaga } from 'vuex-coolstory';
import { take, put, race, delay } from 'redux-saga/effects';

function* saga() {
    while (true) {
        const { newItem, timer } = yield race({
            newItem: take('addItem'),
            timer: delay(3000)
        });
        if (timer) {
            yield put({
                type: 'appendItem',
                item: 'TIMER_A'
            });
            // if module is namespaced you must define namespace 
            yield put({
                type: 'moduleB/appendItem',
                item: 'TIMER_B'
            });
        } else if (newItem) {
            yield put({
                type: 'appendItem',
                item: newItem.payload.item
            });
            yield put({
                type: 'moduleB/appendItem',
                item: [...newItem.payload.item].reverse().join('')
            });
        }
    }
}

export default new Vuex.Store({
    modules: {
        moduleA: {
            namespaced: false,
            state: {
                items: []
            },
            mutations: {
                appendItem(state, { item }) {
                    state.items = [...state.items, item];
                }
            }
        },
        moduleB: {
            namespaced: true,
            state: {
                items: []
            },
            mutations: {
                appendItem(state, { item }) {
                    state.items = [...state.items, item];
                }
            }
        }
    },
    plugins: [
        VuexSaga({
            sagas: [saga]
        })
    ]
});

API

VuexSaga(options)

Creates a Vuex plugin and connects the Sagas to the Vuex Store

• options: Object - A list of options to pass to the plugin. Currently supported options are:

  • sagas : Array of saga generator functions.

  • isProxingFromVuex : Boolean - Flag of proxing mutation from vuex to saga.

  • sagaMonitor : SagaMonitor - see docs for createSagaMiddleware(options)

  • onError : Function - see docs for createSagaMiddleware(options)

  • context : Object - see docs for createSagaMiddleware(options)

  • effectMiddlewares : Function[] - see docs for createSagaMiddleware(options)

mapSagaActions(args)

Similar to mapActions or mapMutations. See usage in examples/simple/src/app.vue

sagaDispatch(args)

Dispatch action to saga in sync mode.

/**
 * @param {string} type 
 * @param {any} payload 
 */
sagaDispatch({ type, payload });

sagaDispatchResolve(args)

Dispatch action to saga in async mode.

/**
 * @param {string} type action
 * @param {any} payload action
 * @param {(action: Action) => boolean | string} resolver resolver for finish action
 * @returns {Promise}
 */
sagaDispatchResolve({type, payload, resolver});

addSaga(saga, store, args)

Add saga after creating root store

/**
 * @param {Generator} saga function
 * @param {Store} store Vuex store
 * @param args other parameters acceptable by rudux-saga runSaga function
 */
addSaga(saga, store, args);

Run example

npm i
cd examples/simple
webpack
# check dist/index.html 

Contribution

Pull request are welcome!