Code Monkey home page Code Monkey logo

just-promises's Introduction

Just Promises

A barebones implementation of the Promises/A+ (and by extension the CommonJS Promises/A proposal).

Features

  • Contains just the bare-minumum stuff needed to comply with the Promises/A proposal.
  • Passes all the tests from the [Promises/A+ Tests][promises-a-plus-test] and the Promise-Tests project.
  • Assured asynchronousity, no need to worry about resolution race-conditions.
  • Implemented as a JavaScript class and supports quick extensibility.
  • Extras for those who really want them.

Usage

On the Browser

If you're using the library on a browser environment, just include the promise.js file.

<script type="text/javascript" src="path/to/promise.js"></script>

If you want the "extras library" (see "Extras" below), include the promise.extra.js file after the promise.js file.

<script type="text/javascript" src="path/to/promise.js"></script>
<script type="text/javascript" src="path/to/promise.extra.js"></script>

On a CommonJS Engine

If you're using the library on a CommonJS engine such as node or ringo, import the promise.js file. You'll get a single exported object, which is the Promise class:

var Promise = require('./promise').Promise;

If you want the "extras library" (see "Extras" below), import the promise.extra.js file and then call the exported extend function, passing in the Promise class from promise.js:

var Promise = require('./promise').Promise;
require('./promise.extra').extend(Promise);

API

The library exposes a single class called Promise. To create a new promise, simply create a new instance of this class:

var promise = new Promise();

Promise.prototype.fulfill

The value of a promise can be fulfilled using the fulfill method:

var promise = new Promise();
promise.fulfill('Hello'); // the promise is now resolved.

Promise.prototype.fail

A promise can be failed using the fail method:

var promise = new Promise();
promise.fail(new Error()); // the promise is now failed.

Promise.prototype.then

As directed by the Promise/A spec, all promises have a then method that accepts three callbacks: a fulfilled callback, a fail callback and a progress callback--all of them optional.

var promise = new Promise();
promise.then(fulfilledFn, failFn, progressFn);

The fulfilled and the fail callbacks are called when the promise is fulfilled or failed, respectively. Progress handlers are, consciously, ignored for now.

Promise.prototype.pipe

There is only one "utility" method included in the main library called pipe. This method can be used to pipe the results of one promise to another.

var promiseA = new Promise();
promiseA.then(function(value) {
	console.log(value); // logs 'Hello'
});

var promiseB = new Promise();
promiseB.fulfill('Hello');

promiseB.pipe(promiseA);

Extras

The extras module includes set of additional features that you can import.

Extra Methods

The rescue method is a shortcut for adding failure handlers without a fulfillment handler:

// instead of this
promise.then(null, errorHandler);

// you can do
promise.rescue(errorHandler);

Promise.prototype.get

The get method takes a string argument that corresponds to a property name in the future value of a promise. It then returns a promise that would be fulfilled with that property's value.

var promise = new Promise();

promise.fulfill({greeting: 'Hello'})

promise.get('greeting').then(function(greeting) {
	console.log(greeting); // logs "Hello"
});

Promise.prototype.call

The call method takes a string argument that corresponds to a method name in the future value of a promise, as well zero or more additional arguments. It then returns a promise that would be fulfilled with the return value of that method called with the arguments.

var promise = new Promise();

promise.fulfill({
	sum: function() {
		var sum = 0;
		for (var l = arguments.length; l--;) sum += arguments[l];
		return sum;
	}
});

promise.call('sum', 1, 2, 3, 4).then(function(value) {
	console.log(value); // logs 10
});

Promise.prototype.thenSpread

The thenSpread method is similar to the then method, but if the promise is fulfilled with an array, it would "spread" the items in the array as arguments to the fulfillment callback:

var promise = new Promise();

promise.fulfill(['Hello', 'World!', 'Hi', 'Universe!']);

promise.thenSpread(function(first, second, third, fourth) {
	console.log(first);  // logs 'Hello'
	console.log(second); // logs 'World!'
	console.log(third);  // logs 'Hi'
	console.log(fourth); // logs 'Universe!'
});

Generics

Promise.all

Promise.all is a utility generic that accepts an array of promises and returns a promise that will be fulfilled with an array containing the resolved values of all promises. If one of the promises in the original array fails, the promise returned by Promise.all will also be failed.

Copyright and License

Copyright 2013, Mark "Keeto" Obcena <keetology.com>. Released under an MIT-Style License.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.