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

micropromise

v0.4.10

Published

A+ promises

Downloads

942

Readme

microPromise(uP) - A+ v1.1 compliant promises

Promise([mixin]:Object, [resolver]:Function)

Promise constructor

  • param Object [mixin] - Mixin promise into object

  • param Function [resolver] - Resolver function(resolve,reject,progress,timeout)

  • return Object Promise

Promise.resolver(resolver:Function)

Promise resolver

  • param Function resolver - resolver function(fulfill,reject,progress,timeout)

  • return Object Promise

Promise.thenable(p:Object)

Helper for identifying a promise-like objects or functions

  • param Object p - Object or Function to test

  • return Boolean - Returns true if thenable or else false

Promise.wrap(class:Function, [instance]:Object)

Wrap a promise around function or constructor

  • param Function class - class to wrap
  • param Object [instance] - optional instance
  • return Function function to wrap
  • throw

Example: wrap an Array

   p = Promise.wrap(Array);
   
   var r = c(1,2,3); // => calls Array constructor and returns fulfilled promise
   r.valueOf(); // => [1,2,3];

Promise.defer(-:Function, [args]:...)

Deferres a task and returns a pending promise fulfilled with the return value from task. The task may also return a promise itself which to wait on.

  • param Function - task to defer
  • param ... [args] - optional list of arguments
  • return Object - returns a pending promise

Example: Make readFileSync async

   fs = require('fs');
   var asyncReadFile = Promise().defer(fs.readFileSync,'./index.js','utf-8');
   asyncReadFile.then(function(data){
       console.log(data)
   },function(error){
       console.log("Read error:", error);
   });

Promise.async(function:Function, [callback]:Function)

Make function asyncronous and fulfill/reject promise on execution.

  • param Function function - function to make async
  • param Function [callback] - optional callback to call
  • return Object promise

Example: make readFile async

   fs = require('fs');
   var asyncReadFile = Promise.async(fs.readFile);
   asyncReadFile('package.json','utf8').then(function(data){
       console.log(data);
   },function(error){
       console.log("Read error:", error);
   });

Promise.isPending()

Check if promise is pending

  • return Boolean - Returns true if pending or else false

Promise.isFulfilled()

Check if promise is fulfilled

  • return Boolean - Returns true if pending or else false

Promise.isRejected()

Check if promise is rejeced

  • return Boolean - Returns true if pending or else false

Promise.hasResolved()

Check if promise has resolved

  • return Boolean - Returns true if pending or else false

Promise.valueOf()

Get value if promise has been fulfilled

  • return Boolean - Returns true if pending or else false

Promise.reason()

Get reason if promise has rejected

  • return Boolean - Returns true if pending or else false

Promise.then(onFulfill:Function, onReject:Function, onNotify:Function)

Attaches callback,errback,notify handlers and returns a promise

  • param Function onFulfill callback
  • param Function onReject errback
  • param Function onNotify callback
  • return Object a decendant promise

Example: catch fulfillment or rejection

   var p = Promise();
   p.then(function(value){
       console.log("received:", value);
   },function(error){
       console.log("failed with:", error);
   });
   p.fulfill('hello world!'); // => 'received: hello world!'

Example: chainable then clauses

   p.then(function(v){
       console.log('v is:', v);
       if(v > 10) throw new RangeError('to large!');
       return v*2;
   }).then(function(v){
       // gets v*2 from above
       console.log('v is:', v)
   },function(e){
       console.log('error2:', e);
   });
   p.fulfill(142); // => v is: 142, error2: [RangeError:'to large']

Example: undefined callbacks are ignored

   p.then(function(v){
       if(v < 0) throw v;
       return v;
   }).then(undefined,function(e){
       e = -e;
       return e;
   }).then(function(value){
       console.log('we got:', value);
   });
   p.fulfill(-5); // => we got: 5

Promise.spread(onFulfill:Function, onReject:Function, onNotify:Function)

Like then but spreads array into multiple arguments

  • param Function onFulfill callback
  • param Function onReject errback
  • param Function onNotify callback
  • return Object a decendant promise

Example: Multiple fulfillment values

   p = Promise();
   p.fulfill([1,2,3])
   p.spread(function(a,b,c){
       console.log(a,b,c); // => '1 2 3'
   });

Promise.done(onFulfill:Function, onReject:Function, onNotify:Function)

Terminates chain of promises, calls onerror or throws on unhandled Errors

  • param Function onFulfill callback
  • param Function onReject errback
  • param Function onNotify callback

Example: capture error with done

   p.then(function(v){
       console.log('v is:', v);
       if(v > 10) throw new RangeError('to large!');
       return v*2;
   }).done(function(v){
       // gets v*2 from above
       console.log('v is:', v)
   });
   p.fulfill(142); // => v is: 142, throws [RangeError:'to large']

Example: define onerror handler defined on promise

   p.onerror = function(error){ console.log("Sorry:",error) };
   p.then(function(v){
       console.log('v is:', v);
       if(v > 10) throw new RangeError('to large!');
       return v*2;
   }).done(function(v){
       // gets v*2 from above
       console.log('v is:', v)
   });
   p.fulfill(142); // => v is: 142, "Sorry: [RangeError:'to large']"

Promise.end(callback:Function)

Terminates chain, invokes a callback or throws Error on error

  • param Function callback - Callback with value or Error object on error.

Promise.catch(onError:Function)

Catches errors, terminates promise chain and calls errBack handler.

  • param Function onError callback
  • return undefined

Example: Catch error

   p = Promise();
   p.then(function(v){
       console.log("someone said:", v);  //-> "Hello there"
       return "boom!";
     })
    .then(function(v){ if(v === 'boom!') throw "something bad happened!";})
    .catch(function(e){
       console.log("error:",e);
    });
   p.resolve("Hello there");

Promise.fulfill(value:Object)

Fulfills a promise with a value

  • param Object value
  • return Object promise

Example: fulfillment

   p = Promise();
   p.fulfill(123);

Example: multiple fulfillment values in array

   p = Promise();
   p.fulfill([1,2,3]);
   p.resolved; // => [1,2,3]

Example: Pass through opaque arguments (experimental)

   p = Promise();
   p.fulfill("hello","world");
   p.then(function(x,o){
       console.log(x,o[0]); // => "hello world"
       o.push("!");
       return "bye bye";
   }).then(function(x,o){
       console.log(x,o.join('')); // => "bye bye world!"
   })

Promise.reject(reason:Object)

Rejects promise with a reason

  • param Object reason
  • return Object promise

Example:

   p = Promise();
   p.then(function(ok){
      console.log("ok:",ok);
   }, function(error){
      console.log("error:",error);
   });
   p.reject('some error'); // outputs => 'error: some error'

Promise.resolve(value:Object)

Resolves a promise and performs unwrapping if necessary

  • param Object value - Promise or literal
  • return Object promise

Example: resolve a literal

   p = Promise();
   p.resolve(123); // fulfills promise to 123

Example: resolve value from pending promise

   p1 = Promise();
   p2 = Promise();
   p1.resolve(p2);
   p2.fulfill(123) // => p1 fulfills to 123

Promise.progress(arguments:Object)

Notifies attached handlers

  • param Object arguments

Example:

   p = Promise();
   p.then(function(ok){
      console.log("ok:",ok);
   }, function(error){
      console.log("error:",error);
   }, function(notify){
      console.log(notify);
   });
   p.progress("almost done"); // optputs => 'almost done'
   p.reject('some error'); // outputs => 'error: some error'

Promise.timeout(time:Number, callback:Function)

Timeout a pending promise and invoke callback function on timeout. Without a callback it throws a RangeError('exceeded timeout').

  • param Number time - timeout value in ms or null to clear timeout
  • param Function callback - optional timeout function callback
  • throw
  • return Object promise

Example: timeout & abort()

   var p = Promise();
   p.timeout(5000);
   // ... after 5 secs ... => Aborted: |RangeError: 'exceeded timeout']

Example: cancel timeout

   p.timeout(5000);
   p.timeout(null); // timeout cancelled

Promise.callback(callback:Function)

Resolves promise to a nodejs styled callback function(err,ret) and passes the callbacks return value down the chain.

  • param Function callback - Callback function
  • return Object promise

Example:

   function cb(err,ret){
     if(err) console.log("error(%s):",err,ret);
     else console.log("success:", ret);
     return "nice";
   }
   p = Promise();
   p.callback(cb)
    .then(function(cbret){ 
      console.log("callback says:", cbret); //-> callback says: nice 
   });
   p.fulfill("ok"); //-> success: ok

Promise.join(promises:Array)

Joins promises and collects results into an array. If any of the promises are rejected the chain is also rejected.

  • param Array promises
  • return Object promise

Example: join with two promises

   a = Promise();
   b = Promise();
   c = Promise();
   a.join([b,c]).spread(function(a,b,c){
       console.log(a,b,c);
   },function(err){
       console.log('error=',err);
   });
   b.fulfill('world');
   a.fulfill('hello');
   c.fulfill('!'); // => 'hello world !''