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

pinkyswear

v2.2.3

Published

Minimalistic Promises/A+ implementation, <500 bytes

Downloads

10,352

Readme

PinkySwear is a very small implementation of the Promises/A+ specification. After compilation with the Google Closure Compiler and gzipping it weighs less than 500 bytes. It is originally based on the implementation for Minified.js and is for embedding. In other words, you can use it as a lightweight dependency for your library if you need to return a promise. It is not intended as a stand-alone library for more complex applications, and therefore does not support assimilation of other promises. Minified's implementation does support assimilation though.

Release History

#####Version 2.2.2 released July 30, 2014

  • Support extensions for promises created using then() (thanks, Zbyszek Tenerowicz)

#####Version 2.2.1 released July 17, 2014

  • Added extend function to constructor (thanks, Zbyszek Tenerowicz)

#####Version 2.1 released June 6, 2014

  • Removed always() and error(), since they were not in the spirit of a minimal implementation.
  • Updated Promises/A+ Compliance Test to 2.0.4

#####Version 2.0.2, released May 10, 2014

  • Use setImmediate() on platforms that support it (thanks, Carl-Erik Kopseng)

#####Version 2.0.1, released Apr 3, 2014

  • Fixed PinkySwear on IE8 which can't handle apply() without arguments (thanks, Luis Nabais)
  • Fix and test case for PinkySwear's multi-arguments extension (thanks, Carl-Erik Kopseng)

#####Version 2.0, released Feb 10, 2014 Passes Promises/A+ Compliance Test 2.0.3. Allows obtaining state by calling promise function without arguments.

#####Version 1.0, released Feb 09, 2013 First release. Passes Promises/A+ Compliance Test 1.10.0 with one exception (PinkySwear is function-based, which is allowed in the spec, but not in the old test suite).

Stats

How to Include / Node.js

You can install PinkySwear.js using npm:

npm install pinkyswear

Use require() to get the initial function:

var pinkySwear = require('pinkyswear');

How to Include / Browser

To use PinkySwear in a browser, just include it with a script tag. You probably want to use the minified version in a browser:

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

API

PinkySwear has just three functions.

To create a new promise in pending state, call pinkySwear():

    var promise = pinkySwear();

The returned object has a Promises/A+ compatible then() implementation:

    promise.then(function(value) { alert("Success!"); }, function(value) { alert("Failure!"); });

The promise returned by pinkySwear() is a function itself. To fulfill the promise, call the function with true as first argument and an optional array of values to pass to the then() handler. By putting more than one value in the array, you can pass more than one value to the then() handlers. Here an example to fulfill a promise, this time with only one argument:

    promise(true, [42]);

When the promise has been rejected, call it with false as first argument:

    promise(false, [6, 6, 6]);

You can obtain the promise's current state by calling the function without arguments. It will be true if fulfilled, false if rejected, and otherwise undefined.

    var state = promise();

It is possible to extend PinkySwear's promise object with custom methods by specifying an extend function:

    function addHello(prom) { 
        prom.sayHello = function() { console.log('hello'); }; 
        return prom; 
    }
    var promise = pinkySwear(addHello);

Examples

setTimeout

A PinkySwear-powered timeout function that returns a promise:

    function promiseTimeout(timeoutMs) {
        var prom = pinkySwear();
        setTimeout(function() {
            prom(true, []);
        }, timeoutMs);
        return prom; 
    }

Using the timeout:

    console.log('Starting timeout now.');
    promiseTimeout(5000).then(function() {
        console.log('5s have passed.');
    });

XmlHttpRequest

This is a simple implementation of HTTP GET requests in browsers using XmlHttpRequest. It returns a promise with the result or failure:

   function get(url) {
       var prom = pinkySwear();
       var xhr = new XMLHttpRequest();
       xhr.onreadystatechange = function() {
           if (xhr.readyState==4 && xhr.status==200)
               prom(true, [xhr.status, xhr.responseText]);
           else 
               prom(false, [xhr.status, xhr.statusText, xhr.responseText]);
       };
       oReq.open('get', url, true);
       oReq.send();
       return prom;
   }

This is how to retrieve a simple file:

   get('http://example.com/someFile.txt').then(function(status, txt) {
       console.log('Got my file: ', txt);
       return get('http://example.com/fileTwo.txt');
   }, function(status, statusText, txt) {
       console.log('Something bad happened. Got status code: ', status, statusText);
   });

This example retrieves a file, waits 3s and gets a second one:

   get('http://example.com/fileOne.txt').then(function(status, txt) {
       console.log('Got first file: ', txt);
       return promiseTimeout(3000);
   }).then(function() {
       console.log('Waited 3s');
       return get('http://example.com/fileTwo.txt');
   }).then(function(status, txt) {
       console.log('Got second file: ', txt);
   }).then(null, function() {
       console.log('Something bad happened along the way.');
   });

Licensing

Public Domain. Use, modify and distribute it any way you like. No attribution required. To the extent possible under law, Tim Jansen has waived all copyright and related or neighboring rights to PinkySwear. Please see http://creativecommons.org/publicdomain/zero/1.0/