Backwards Compatible Refactor of PeriodicActions

see: #23

async.auto -> run-auto!

Changes in this release

• [#22] - switch from async.auto/async.series to run-auto/run-series. Should result in smaller webpack/browserify builds
• [#20] - bump eslint version

Update Dependencies

see #19

Be Compatible with React@0.13.x

PRs

• [https://github.com//pull/12] React 0.13 support
• [https://github.com//pull/13] update devDeps

Modularized Builds + PeriodicActionMixin

PRs

• [breaking] #9 - Modularized Builds
• [feature] #8 - PeriodicActionsMixin (thanks @ZeikJT)

Docs

Modularized Builds/Requires

The utility library provides modularized methods, and method categories to aid in providing smaller browserify and webpack builds.

var actionUtils = require('fluxible-action-utils');

Will require the entire library, including all available methods grouped under their respective method categories.

For example, the following are equivalent (but will result in varying sized webpack builds)

Full Library (results in largest build)

var executeMultiple = require('fluxible-action-utils').async.executeMultiple;

Category

var executeMultiple = require('fluxible-action-utils/async').executeMultiple;

Method (results in smallest build)

var executeMultiple = require('fluxible-action-utils/async/executeMultiple');

🚨 WARNING 🚨

Methods inside the internals directory/category are not explicitely exported and are considered unstable.

require externally at your own risk as breaking changes inside internals will not be considered breaking for the library.

API

• async
  • executeMultiple
  • exectueCritical
• mixins
  • PeriodicActions

async

available as of v0.2.0

var asyncActionUtils = require('fluxible-action-utils/async');

Methods grouped under the async category are concerned with providing methods that aid in managing the asynchronous control flow of fluxible actions.

async.auto is used under the hood to do the actual heavy lifting (thanks to @caolan)

executeMultiple (context, actions, [done])

available as of v0.2.0

var executeMultiple = require('fluxible-action-utils/async/executeMultiple');

Utility method used to execute multiple actions in parallel where possible. Each key in actions represents a task to be executed (and should be unique).

actions[task] can be one of the following

1. {FluxAction} an action to be executed, cannot be critical nor require params
2. {Object} an action "object" with the follwing properties
   1. action {FluxAction} the action to execute
   2. [isCritical=false] {Boolean} whether the action is critical
   3. [params] {Any} parameters to pass to the action when executing it
3. {Array} {String, String, ..., FluxAction|Object} array which defines the tasks/actions that need to be executed before executing the action of type 1. or 2. found at the end of the array.

The done {Function} parameter is optional, but if provided, will be called when all tasks complete (either with success or failure).
Signature function (err, results)

For each task that fails, the error returned will be aggregated under err[task].

Example

// initHome.js

var executeMultiple = require('fluxible-action-utils/async/executeMultiple');
var UserStore = require('app/stores/UserStore');

module.exports = function initHome(context, params, done) {
    executeMultiple(context, {
        loadUH: require('UH').actions.load,
        loadUser: {
            action: require('app/actions/loadUser'),
            isCritical: true
        },
        loadStuffForUser: [
            'loadUser',
            {
                // will be executed after 'loadUser' task completes successfully
                action: require('../../actions/loadStuffForUser'),
                params: context.getStore(UserStore).getGUID()
            }
        ],
        populateUserNotifications: [
            'loadUH',
            'loadStuffForUser',

            // will be executed after the 'loadUH' and 'loadStuffForUser' tasks complete successfully
            require('../../actions/populateUserNotifications')
        ]
    }, function (err, results) {
        // there was at least one error, handle them
        if (err) {
            if (err.loadUser) {
                context.dispatch('CATASTROPHE', err.loadUser);
            }

            if(err.loadStuffForUser) {
                context.dispatch('RECOVERABLE', err.loadStuffForUser);
            }

            return;
        }
        // Yay! no errors
    });
};

executeCritical (context, actions, [done])

available as of v0.2.0

var executeCritical = require('fluxible-action-utils/async/executeCritical');

executeCritical allows you to execute a group of actions that are ALL deemed critical. This is a simple shorthand for executeMultiple when a group of actions are all critical.

mixins

available as of v0.2.0

var mixins = require('fluxible-action-utils/mixins');

Mixins grouped under the mixins category are concerned with providing React component mixins that simplify using fluxible actions.

PeriodicActions

available as of v0.2.0

var PeriodicActionsMixin = require('fluxible-action-utils/mixins/PeriodicActions');

Utility mixin used to make running an action repeatedly (polling an API for example) easier to do.

You can either write code using the methods exposed by the mixin directly, or you can use the statics support.

uuid must be a unique identifier, attempting to add another action with the same uuid as a currently running periodic action will fail to add.

Statics Example

// MyReactComponent.jsx

var PeriodicActionsMixin = require('fluxible-action-utils/mixins/PeriodicActions');
var myPollingAction = require('./myPollingAction');

module.exports = React.createClass({
    displayName: 'MyReactComponent',
    mixins: [PeriodicActionsMixin],
    statics: {
        periodicActions: [
            {
                uuid: 'MY_UNIQUE_POLLING_ACTION_UUID_STATICS',
                action: myPollingAction,
                // Optional params
                params: {
                    customPayload: 'payload'
                },
                // Optional timeout (Defaults to 100 ms)
                timeout: 1000
            }
        ]
    },
    render: function () {
        return <span>My React Component</span>;
    }
});

Code Example

// MyReactComponent.jsx

var PeriodicActionsMixin = require('fluxible-action-utils/mixins/PeriodicActions');
var myPollingAction = require('./myPollingAction');

module.exports = React.createClass({
    displayName: 'MyReactComponent',
    mixins: [PeriodicActionsMixin],
    componentDidMount: function () {
        this.startPeriodicAction(
            'MY_UNIQUE_POLLING_ACTION_UUID_CODE',
            myPollingAction,
            // Optional params
            {customPayload: 'payload'},
            // Optional timeout (Defaults to 100 ms)
            1000
        );
    },
    /* Don't need this, all periodic actions will be stopped automatically on unmount
    componentWillUnmount: function () {
        this.stopPeriodicAction('MY_UNIQUE_POLLING_ACTION_UUID_CODE');
    },
    */
    render: function () {
        return null;
    }
});

Initial Release

fluxible-action-utils

utility methods to aid in writing actions for fluxible based applications.

Links

• async.auto
  • used under the hood to actually handle task/action depedency management. (thanks to @caolan)

Usage

executeMultiple(context, actions, [done])

available as of v0.1.0

Utility method used to execute multiple actions in parallel where possible. Each key in actions represents a task to be executed (and should be unique).

actions[task] can be one of the following

1. {FluxAction} an action to be executed, cannot be critical nor require params
2. {Object} an action "object" with the follwing properties
   1. action {FluxAction} the action to execute
   2. [isCritical=false] {Boolean} whether the action is critical
   3. [params] {Any} parameters to pass to the action when executing it
3. {Array} {String, String, ..., FluxAction|Object} array which defines the tasks/actions that need to be executed before executing the action of type 1. or 2. found at the end of the array.

The done {Function} parameter is optional, but if provided, will be called when all tasks complete (either with success or failure).
Signature function (err, results)

For each task that fails, the error returned will be aggregated under err[task].

Example

// initHome.js

var actionUtils = require('fluxible-action-utils');
var UserStore = require('app/stores/UserStore');

module.exports = function initHome(context, params, done) {
    actionUtils.executeMultiple(context, {
        loadUH: require('UH').actions.load,
        loadUser: {
            action: require('app/actions/loadUser'),
            isCritical: true
        },
        loadStuffForUser: [
            'loadUser', 
            {
                // will be executed after 'loadUser' task completes successfully
                action: require('../../actions/loadStuffForUser'),
                params: context.getStore(UserStore).getGUID()
            }
        ],
        populateUserNotifications: [
            'loadUH', 
            'loadStuffForUser', 

            // will be executed after the 'loadUH' and 'loadStuffForUser' tasks complete successfully
            require('../../actions/populateUserNotifications')
        ]
    }, function (err, results) {
        // there was at least one error, handle them
        if (err) {
            if (err.loadUser) {
                context.dispatch('CATASTROPHE', err.loadUser);
            }

            if(err.loadStuffForUser) {
                context.dispatch('RECOVERABLE', err.loadStuffForUser);
            }

            return;
        }
        // Yay! no errors
    });
};

executeCritical(context, actions, [done])

available as of v0.1.0

executeCritical allows you to execute a group of actions that are ALL deemed critical. This is a simple shorthand for executeMultiple when a group of actions are all critical.

Thanks

• @mridgway
• @akshayp
• @redonkulus