README
Synopsis
axn is a small-ish (~2.2 kB minified, 758 bytes gzipped) implementation of listenable actions or signals in JavaScript for browsers (IE8+) and the server.
Install
Node.js
With NPM
npm install axn
From source
git clone https://github.com/pluma/axn.git
cd axn
npm install
npm run test && npm run dist
Browser
With component
component install pluma/axn
With bower
bower install axn
With a CommonJS module loader
Download the latest minified CommonJS release and add it to your project.
Learn more about CommonJS modules.
With an AMD module loader
Download the latest minified AMD release and add it to your project.
As a standalone library
Download the latest minified standalone release and add it to your project.
<script src="/your/js/path/axn.globals.min.js"></script>
This makes the axn module available in the global namespace.
Examples
import axn from 'axn';
let action = axn();
let unlisten = action.listen(data => data.toUpperCase());
action.listen((data, modified) => console.log('received data:', data, modified));
action.listen(() => 42);
let result = action('hello'); // -> received data: hello HELLO
result === 42;
unlisten();
action('hello'); // -> received data: hello hello
let asyncAction = axn.async();
asyncAction.listen(data => Promise.resolve(data.toUpperCase()));
asyncAction('hello').then(result => console.log(result)); // -> HELLO
API
axn([spec]):Function
Creates a new action.
If spec is an object, its properties will be copied to the new action, overwriting its default properties.
action(data)
Invokes the action's listeners in sequence with the given data. Returns the return value of the last listener called.
If passed more than one argument, the arguments will be passed on as an array.
In addition to data, each listener will be passed the return value of the previous listener as a second argument, or data if the listener is the first in the sequence.
action.listen(fn, [ctx]):Function
Adds a given function to the action's listeners. If ctx is provided, the function will be invoked using it as its this context.
Returns a function that will remove the listener from the action.
action.unlisten(fn, [ctx]):Boolean
Removes the given function with the given context from the action's listeners.
Returns true if the listener was removed successfully, otherwise returns false.
action.listenOnce(fn, [ctx]):Function
Adds a given function to the action's listeners. If ctx is provided, the function will be invoked using it as its this context.
The function will only be invoked once and then automatically removed from the action's listeners.
Returns a function that will remove the listener from the action.
action.beforeEmit(data):data
Override this function in your action's spec to pre-process data passed to the action before it is emitted.
The return value will be passed to the action's listeners.
action.shouldEmit(data):Boolean
Override this function in your action's spec to define whether data should be emitted.
This function is passed the output of beforeEmit. If the function returns false or a non-truthy value, the data will not be emitted. Otherwise the action's listeners will be invoked as normally.
axn.methods
An object containing the default properties that will be copied to new actions.
axn.async([spec]):Function
Creates a new async action.
If spec is an object, its properties will be copied to the new action, overwriting its default properties.
NOTE: async actions use promises. axn uses the global Promise implementation defined by ES 2015. If you want to use async actions in environments that don't provide an ES2015-compatible Promise implementation, you need to make sure to use a polyfill like es6-promise. If you're not interested in async actions, you can ignore this section.
asyncAction(data):Promise
Invokes the action's listeners in sequence with the given data. Returns a promise resolving to the return value of the last listener called (or rejected accordingly).
In addition to data, each listener will be passed the resolved value of the previous listener as a second argument, or data if the listener is the first in the sequence.
The promise returned by the action has two additional methods to allow aborting an action that is still in progress:
promise.cancel([message])
Cancels the action. Listeners that have not yet been invoked will no longer be called and the promise will be rejected with an error with the given message or "cancelled" if no message was provided.
promise.cancelled():Boolean
Returns true if the action was cancelled or false otherwise.
This function can be used to determine whether a promise was rejected due to a regular error or because it was explicitly cancelled.
axn.async.methods
An object containing the default properties that will be copied to new async actions in addition to those in axn.methods.
License
The MIT/Expat license. For more information, see http://pluma.mit-license.org/ or the accompanying LICENSE file.