npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

spromise

v1.0.0

Published

Small Promise

Downloads

658

Readme

spromise Build Status

spromise (Small Promise), is an implementation of the promise A+ spec. It is designed to be lightweight, performant, and per spec, interoperable with other promise implementations such as jQuery's deferred.

Table of Contents

API

Static methods

spromise constructor

Creates a promise instance. It can take in a function as its single optional parameter, which is called when the promise is created. The callback function receives two parameters, a function to fulfill the promise and a function to reject the promise.

Resolve a promise
var spromise = require("spromise");

// Resolve
spromise(function(resolve, reject){
  resolve("Yes, we are resolving this");
})
.done(function(value) {
  // Will print "Yes, we are resolving this"
  console.log(value);
});
Reject a promise
var spromise = require("spromise");

// Reject
spromise(function(resolve, reject){
  reject("booo");
})
.fail(function(value) {
  // Will print "booo"
  console.log(value);
});

spromise.defer

Creates and returns a new promise to be resolved in the future.

  • returns a new promise
var spromise = require("spromise");

// Create a deferred promise
var promise = spromise.defer();

promise.done(function(data) {
  console.log(data);
});

promise.resolve("Deferred");

spromise.resolve

The primary purpose for this method is to return promise instances. If the input is a promise instance, then that's returned as is. If the input is a thenable object or function, a new promise is returned with the current/future value of the thenable. And if the value is anything else, then a new promise that is already fulfilled with the value(s) is returned.

This essentially replaces promise cast

  • returns a promise
var spromise = require("spromise");
var promise = spromise.resolve("Resolved promise");

promise.done(function(data) {
  console.log(data);
});

spromise.reject

Returns a new promise that is rejected with the reason passed in. The reason can be any data type.

  • returns a new rejected promise
var spromise = require("spromise");
var promise = spromise.reject("Rejected promise");

promise.fail(function(data) {
  console.log(data);
});

spromise.when

creates and returns a promise. when takes in N arguments that control when the when promise is resolved. Passing in promises as arguments will cause when to wait for all the input promises to resolve. If one fails, everything fails. None promise objects can also be passed in, in which case they are immediately resolved. when is very useful when synchronizing a group of asynchronous and synchronous operations.

  • returns a new promise
Synchronizing multiple $.ajax request
spromise.when($.ajax("json/array.json"), $.ajax("json/object.json")).done(function($array, $object) {
  // Will print the XHR objects $array and $object
  console.log($array, $object);
});

spromise.all

similar to when except that the input parameters are in the form of a single array.

  • returns a new promise
Synchronizing multiple $.ajax request
spromise.all([$.ajax("json/array.json"), $.ajax("json/object.json")]).done(function(result) {
  // Will print the XHR objects $array and $object
  var $array  = result[0],
      $object = result[1];
  console.log($array, $object);
});

Instance methods

then

method to register callbacks to be called when the promise is fulfilled or rejected. The first parameter is the callback to be called when the promise is fulfilled, and the second parameter is the callback to be called when the promise is rejected.

This method is generally used for creating chains of promises. If calling fulfilled or rejected returns anything, then that value is returned to the subsequent promise in a thenable chain. See examples in the Examples section.

  • returns a new promise
var spromise = require("spromise");

// Fulfilled promise
var promise = spromise.resolve("Fulfilled promise");

// Register callbacks
promise.then(resolved, rejected);

function resolved(data) {
  console.log(err);
}

function rejected(err) {
  // Does not get called because the promise was fulfilled.
}
var spromise = require("spromise");

// Reject promise
var promise = spromise.reject("Rejected promise");

// Register callbacks
promise.then(resolved, rejected);

function resolved(data) {
  // Does not get called because the promise was rejected.
}

function rejected(err) {
  console.log(err);
}

done

method takes a callback as its only parameter that gets called when the promise is fulfilled. If the promise is fulfilled with a value(s), that value will get passed in as parameter(s) to the callback.

  • returns promise (itself)
var spromise = require("spromise");
var promise = spromise.resolve("Resolved promise", "extra value");

promise.done(function(data1, data2) {
  console.log(data1, data2);
});

fail and catch

method takes a callback as its only parameter that gets called when the promise is rejected. If the promise is rejected with a reason(s), that will then get passed in as parameter(s) to the callback.

Note: fail and catch are exactly the same methods, and they both exist to provide alternatives for folks used to one vs the other.

  • returns promise (itself)
var spromise = require("spromise");
var promise = spromise.reject("Reason...");

promise.fail(function(reason) {
  console.log(reason);
});

promise.catch(function(reason) {
  console.log(reason);
});

always

method to register a callback that gets called when the promise is either fulfilled or rejected.

  • returns promise (itself)
var spromise = require("spromise");
var promise = spromise.resolve("Fulfilled promise");

promise.always(function(data) {
  console.log(data);
});
var spromise = require("spromise");
var promise = spromise.reject("Reason...");

promise.always(function(reason) {
  console.log(reason);
});

resolve

method to fulfill the promise. This will cause all registered callbacks (current as well as future ones) to be called with the resolved value.

  • returns promise (itself)
var spromise = require("spromise");

// Create a deferred promise
var promise = spromise.defer();

promise.done(function(data) {
  console.log(data);
});

promise.resolve("Deferred");

reject

method to reject the promise. This will cause all registered callbacks (current as well as future ones) to be called with the reason for rejecting the promise.

  • returns promise (itself)
var spromise = require("spromise");

// Create a deferred promise
var promise = spromise.defer();

promise.fail(function(data) {
  console.log(data);
});

promise.reject("Deferred");

delay

method that will delay the resolution of a promise chain by the amount of MilliSeconds passed in as its only parameter.

  • returns new promise.
var spromise = require("spromise");

// Create a deferred promise
var promise = spromise.defer();

promise.delay(3000).done(function(data) {
  console.log("3 seconds later", data);
});

promise.resolve("Deferred");

state

method to get the current state of the promise. The values can be "pending", "resolved", or "rejected".

  • returns string

isPending

method that returns whether or not the promise is in a pending state; meaning is has not yet been resolved.

  • returns boolean

isResolved

method that returns whether or not the promise has been successfully resolved.

  • returns boolean

isRejected

method that returns whether or not the promise has been rejected.

  • returns boolean

Instance Properties

promise

property that contains methods to read the value and status of the promise. This is useful if you want to create a promise and return the read only version of it. The methods in this object are then, always, done, catch, fail, notify, state.

var spromise = require("spromise");

// Create a deferred promise
var promise = spromise.defer();

// Print out the promise property
console.log(promise.promise);

Install

bower

$ bower install spromise

npm

$ npm install spromise

Downloads

General purpose UMD (Browser, Node):

For inline inclusion in your AMD code:

Build

Run the following command in the terminal:

$ npm install

Tests

Unit tests

Run the following commands in the terminal:

$ npm install
$ grunt test

Compliance unit tests:

Run the following commands in the terminal:

$ npm install
$ npm test

Compliance notes

With the exception of 2.2.5, which states that onFullfilled/onRejected must not be called with "this", all tests for compliance pass. The reason spromise was left non compliant for this particular item is to faithfully handle "context" configured in jQuery ajax requests.

NOTE: The spec makes use of fulfilled, which is the exact same thing as resolved in spromise. The different names exists because it seems more consistent that if you call resolve to transition a promise to the resolved state, that the state is resolved and not fulfilled. In spromise's documention both are used simply for better readability.

Test results: