ganglion-impulse

Ganglion Impulse ================ > In anatomy, a [ganglion](https://en.wikipedia.org/wiki/Ganglion) (/ˈɡæŋɡliən/ > gang-glee-ən; plural ganglia) is a nerve cell cluster. A JavaScript library for registering fibers that transmit impulses from a central ganglion, triggering a chain of actions. Ganglion is heavily inspired by [Cerebral](https://github.com/christianalfoni/cerebral) but does not include a data store or any [React](http://facebook.github.io/react/) component integration as Cerebral does. Ganglion is small (~1k minimised and gzipped) and it does not have any dependencies. Why Use Ganglion ---------------- Ganglion can be used as the central nervous system of an application. It facilitates a clean and understandable definition of one way data flows through an application. It can utilise reusable action functions and manage asynchronous actions in series or parallel. If your async server operation is taking longer than expected it can let your app know it needs to give feedback to the user via a spinner or asking the user if they wish to cancel. Ganglion is best when paired with an [immutable data store](https://github.com/rtfeldman/seamless-immutable), which it can pass to all actions via context provided to its constructor. For user interface rendering [React](http://facebook.github.io/react/) works well, but other libraries could also be used. Hooks on the ganglion allow operations to be executed before or after every impulse. These can be used to setup automatic re-rendering after mutative impulses have completed. Installation ------------ ``` npm install ganglion-impulse ``` Include ganglion in your app with: ```JavaScript var Ganglion = require('ganglion-impulse'); ``` For a client-side project you can use [Browserify](http://browserify.org/) or [webpack](http://webpack.github.io/). Usage ----- ### Example ```JavaScript // es6 example, but will also work with es5. import Ganglion from 'ganglion-impulse'; import { sendCredentialsToServer, setUserInfo } from './custom-application-actions'; // create a new ganglion let ganglion = new Ganglion(); // define some fibers ganglion.fiber('loginClicked', sendCredentialsToServer, setUserInfo); // send impulses ganglion.impulse.loginClicked({ userName, password }).then(function () { console.log('impulse completed'); }); ``` If actions return a Promise then ganglion will wait for them to resolve before calling the next action in the chain. ### Parallel actions Actions can run in parallel if passed as an array: ```JavaScript ganglion.fiber('buttonClicked', prepareAction, [parallelAction1, parallelAction2], finalAction); ``` ### Sending Data The first action receives the parameter passed when the impulse is initiated, subsequent actions receive the response from the previous action. The response from the final action is returned via a promise to the caller. When parallel actions are used, the response of both will be passed as an array to the next in the same order as the actions are defined on the fiber. ### Context Data Context information can be passed to the ganglion constructor which will then be made available to all actions called when an impulse is initiated: ```JavaScript // create a new ganglion with some context data let ganglion = new Ganglion({ context: { dataStore: {} } }); ganglion.fiber('userChangedName', function updateUserName(userName) { this.dataStore.userName = userName; }); ``` The name of the current fiber is also available via the impulse's context: ```JavaScript ganglion.fiber('eventReceived', function logTheFiberName() { console.log(this.fiberName); }); ``` Context is initialised per impulse. Any mutations will be available to subsequent actions but will be discarded after the final action. The properties defined with original context passed to the ganglion constructor are retained across all impulses. To make changes to the context after the ganglion is initialised you can use the `addToContext` method: ```JavaScript // create a new ganglion with some context data let ganglion = new Ganglion({ context: { dataStore: {} } }); // add log method to the ganglion ganglion.addToContext({ log: logMethod }); ganglion.fiber('userChangedName', function updateUserName(userName) { this.log(`The user changed their name to ${userName}`); }); ``` Any existing values with the same key will be overwritten. ### Events #### beforeImpulse and afterImpulse `beforeImpulse` and `afterImpulse` events are fired by the ganglion before and after every impulse emitted. Handlers have the same signature as actions, but the return value is discarded. ```JavaScript let ganglion = new Ganglion(); // add beforeImpulse and afterImpulse event handlers ganglion.on('beforeImpulse', function (data) { // data will be also be passed to the first action console.log(`${this.fiberName} impulse started`); }); ganglion.on('afterImpulse', function (data) { // data is the value that was returned by the last action console.log(`${this.fiberName} impulse ended`); }); ``` #### slowAsyncActionStart and slowAsyncActionEnd `slowAsyncActionStart` and `slowAsyncActionEnd` events are fired by the ganglion when async actions take a while to complete. ```JavaScript let slowActionHandler = function (isStart) { let status = isStart ? 'is running slow' : 'completed'; console.log(`${this.fiberName} async action ${status}`); }; let ganglion = new Ganglion({ callSlowAsyncActionAfter: 500, // ms after which the // onSlowAsyncActionStart will be called }); // add slowAsyncActionStart and slowAsyncActionEnd event handlers ganglion.on('slowAsyncActionStart', slowActionHandler); ganglion.on('slowAsyncActionEnd', slowActionHandler); ``` To ensure that the slow async action events are not triggered unnecessarily, `callSlowAsyncActionAfter` can be used to define after how many milliseconds should be hooks be called. By default this is set to 500ms. #### error `error` events are fired when async actions reject their promise. ```JavaScript let ganglion = new Ganglion(); // add error event handlers ganglion.on('error', function (error) { console.error(`${this.fiberName} returned an error`, error); }); ``` ### Canceling an Impulse Any action or event handler can cancel an impulse by setting `cancelImpulse = true` on the context: ```JavaScript ganglion.fiber('buttonClicked', firstAction, function secondAction(data) { this.cancelImpulse = true; }, finalActionWontBeCalled); ``` Contributing ------------ Checkout the git repository and install the build and test dependencies ``` npm install ``` ### Testing The automated tests can be run via ``` npm test ``` ### Building Ganglion uses es6 and should be transpiled prior to publishing ``` npm run build ``` Change Log ---------- 0.4.2 * Added addToContext method 0.4.1 * Emit error events * Removed debug code which can now be acheived with events * Added more tests 0.4.0 * Allow alternative spelling of fiber/fibre * [Breaking Change] Changed hooks to events 0.3.1 * Improved the documentation * Added the ability for any action or hook to cancel an impulse 0.3.0 * Added onSlowAsyncActionStart and onSlowAsyncActionEnd hooks 0.2.0 * Added onBeforeImpulse and onAfterImpulse hooks 0.1.1 * Fixed dist build 0.1.0 * Initial release License ------- The MIT License (MIT) Copyright (c) 2015 Garth Williams Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.