Pledges
A micro JS library for promises based on the Promises/A+ specification.
License This work is licensed under a MIT License.
Contributing Please make contributions by forking the project and creating a pull-request. Other contributions include maintaining the Wiki and issues.
Documentation
1 Installation
1.1 Browser
Reference the raw Github version of release.min.js in your code.
Pledges is compatible with requireJS and can be used by wrapping your code in the following block:
require(['deferred'], function (deferred) { // Your code.});
1.2 Node
Pledges is also available as a node package called "pledges". You can install it to your local repository using npm install pledges --save-dev
and you can use the library with node by using var deferred = require('pledges').deferred;
in your JavaScript file.
1.3 Versioning
This project is maintained under the semantic versioning guidlines. This means that releases will have the following format <major>.<minor>.<patch>
.
- Breaking backward compatibility bumps the major (and resets the minor and patch).
- New additions without breaking backward compatibility bumps the minor (and resets the patch).
- Bug fixes and misc changes bumps the patch.
2 Getting Started
To create a new deferred, use the global "deferred" function.
deferred();
Arguments None.
Returns {Object} deferred: A structure that can be manipulated like a deferred.
3 Methods
3.1 resolve
Resolves the promise.
deferred().resolve(value);
Arguments
- {Object} value: The promised value.
Returns {Object} deferred: The current deferred.
3.2 reject
Rejects the promise.
deferred().reject(reason);
Arguments
- {Object} reason: The reason why the promise was rejected.
Returns {Object} deferred: The current deferred.
3.3 then
What to do when the state of the promise has changed.
deferred().then(onFulfilment, onRejection);
Arguments
- {Function} onFulfilment: A function to be called when the promise is fulfilled.
- {Function} onRejection: A function to be called when the promise is rejected.
Returns {Object} restrictedDeferred: Promises the completion of onFulfilment or onRejection (restricted deferred - see restrict method).
3.4 state
The current state of the promise.
deferred().state();
Arguments None.
Returns {String} state: The current state of the promise (either 'pending', 'fulfilled', or 'rejected').
3.5 restrict
Restricts access to the deferred.
deferred().restrict();
Arguments None.
Returns
{Object} deferred: A deferred that provides access to the then
and state
methods only.