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

Learn more about component.

With bower

bower install axn

Learn more about bower.

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.

Learn more about AMD modules.

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.