yaku

What is yaku?

Yaku is a lightweight and fast Promise library that is fully compatible with ES6 Promises. It aims to provide better performance and smaller size compared to native Promises and other Promise libraries.

What are yaku's main functionalities?

Basic Promise Usage

This demonstrates the basic usage of Yaku to create a new Promise and handle its resolution.

const Yaku = require('yaku');

const promise = new Yaku((resolve, reject) => {
  setTimeout(() => resolve('Hello, Yaku!'), 1000);
});

promise.then(value => console.log(value));

Chaining Promises

This demonstrates how to chain multiple `then` calls to handle the resolved value step by step.

const Yaku = require('yaku');

const promise = new Yaku((resolve, reject) => {
  setTimeout(() => resolve(1), 1000);
});

promise
  .then(value => value + 1)
  .then(value => value * 2)
  .then(value => console.log(value));

Error Handling

This demonstrates how to handle errors in Yaku Promises using the `catch` method.

const Yaku = require('yaku');

const promise = new Yaku((resolve, reject) => {
  setTimeout(() => reject(new Error('Something went wrong')), 1000);
});

promise
  .then(value => console.log(value))
  .catch(error => console.error(error.message));

Promise.all

This demonstrates how to use `Yaku.all` to wait for multiple Promises to resolve.

const Yaku = require('yaku');

const promise1 = Yaku.resolve(1);
const promise2 = Yaku.resolve(2);
const promise3 = Yaku.resolve(3);

Yaku.all([promise1, promise2, promise3])
  .then(values => console.log(values));

Other packages similar to yaku

bluebird

Bluebird is a fully featured Promise library with a focus on performance and additional features not found in native Promises. It offers more utility methods and better error handling compared to Yaku, but it is larger in size.

q

Q is another Promise library that provides a lot of additional functionality such as deferred objects and more advanced control flow. It is more feature-rich compared to Yaku but also comes with a larger footprint.

when

When is a lightweight Promise library that focuses on performance and small size, similar to Yaku. It provides a few more utilities for working with Promises but is generally comparable in terms of performance and size.

README

Overview

The src/yaku.coffee of Yaku is full compatible with V8's native Promise, but much faster.

If you want to learn how Promise works, read the minimum implementation docs/minPromiseA+.coffee. Without comments, it is only 80 lines of code. It only implements the constructor and then. It passed all the tests of promises-aplus-tests.

I am not a optimization freak, I try to keep the source code readable and maintainable.

Features

• The minified file is only 2.7KB (Bluebird / 73KB, ES6-promise / 18KB)
• 100% compliant with Promise/A+ specs
• Better performance than the native Promise
• Works on IE5+ and other major browsers
• Possibly unhandled rejection support

Quick Start

Node.js

npm install yaku

Then:

Promise = require 'yaku'

Browser

Download the yaku.js file from release page. It supports both AMD and CMD. Raw usage without AMD or CMD:

<script type="text/javascript" src ="yaku.js"></script>
<script>
    // Yaku will be assigned to `window.Yaku`.
    Promise = Yaku
</script>

Compare

These comparisons only reflect some limited truth, no one is better than than others on all aspects.

iojs v1.8.1
OS   darwin
Arch x64
CPU  Intel(R) Core(TM) i7-4850HQ CPU @ 2.30GHz

Name	Unit Test	1ms async task	sync task	Helpers	file size
Yaku	872/872	283ms	68ms	++	2.7KB
Bluebird	872/872	244ms	164ms	+++++++	73KB
ES6-promise	872/872	435ms	110ms	+	18KB
native	872/872	816ms	605ms	+	0KB
q	208/872	2637ms	2327ms	+++	24K

• Helpers: extra methods that help with your promise programming, such as async flow control helpers, debug helpers.
• 1ms async task: npm run no -- benchmark, the smaller the better.
• sync task: npm run no -- benchmark --sync, the smaller the better.

API

• constructor(executor)

  This class follows the Promises/A+ and ES6 spec with some extra helpers.

  • param: executor { Function }

    Function object with two arguments resolve and reject. The first argument fulfills the promise, the second argument rejects it. We can call these functions, once our operation is completed.

  • example:

    Promise = require 'yaku'
    p = new Promise (resolve, reject) ->
    	setTimeout ->
    		if Math.random() > 0.5
    			resolve 'ok'
    		else
    			reject 'no'
    

• then(onFulfilled, onRejected)

  Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler.

  • param: onFulfilled { Function }

    Optional. Called when the Promise is resolved.

  • param: onRejected { Function }

    Optional. Called when the Promise is rejected.

  • return: { Yaku }

    It will return a new Yaku which will resolve or reject after the current Promise.

    Promise = require 'yaku'
    p = Promise.resolve 10
    
    p.then (v) ->
    	console.log v
    

• catch(onRejected)

  The catch() method returns a Promise and deals with rejected cases only. It behaves the same as calling Promise.prototype.then(undefined, onRejected).

  • param: onRejected { Function }

    A Function called when the Promise is rejected. This function has one argument, the rejection reason.

  • return: { Yaku }

    A Promise that deals with rejected cases only.

    Promise = require 'yaku'
    p = Promise.reject 10
    
    p.catch (v) ->
    	console.log v
    

• @resolve(value)

  The Promise.resolve(value) method returns a Promise object that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.

  • param: value { Any }

    Argument to be resolved by this Promise. Can also be a Promise or a thenable to resolve.

  • return: { Yaku }

    Promise = require 'yaku'
    p = Promise.resolve 10
    

• @reject(reason)

  The Promise.reject(reason) method returns a Promise object that is rejected with the given reason.

  • param: reason { Any }

    Reason why this Promise rejected.

  • return: { Yaku }

    Promise = require 'yaku'
    p = Promise.reject 10
    

• @race(iterable)

  The Promise.race(iterable) method returns a promise that resolves or rejects as soon as one of the promises in the iterable resolves or rejects, with the value or reason from that promise.

  • param: iterable { iterable }

    An iterable object, such as an Array.

  • return: { Yaku }

    The race function returns a Promise that is settled the same way as the first passed promise to settle. It resolves or rejects, whichever happens first.

    Promise = require 'yaku'
    Promise.race [
    	123
    	Promise.resolve 0
    ]
    .then (value) ->
    	console.log value # => 123
    

• @all(iterable)

  The Promise.all(iterable) method returns a promise that resolves when all of the promises in the iterable argument have resolved.

  The result is passed as an array of values from all the promises. If something passed in the iterable array is not a promise, it's converted to one by Promise.resolve. If any of the passed in promises rejects, the all Promise immediately rejects with the value of the promise that rejected, discarding all the other promises whether or not they have resolved.

  • param: iterable { iterable }

    An iterable object, such as an Array.

  • return: { Yaku }

    Promise = require 'yaku'
    Promise.all [
    	123
    	Promise.resolve 0
    ]
    .then (values) ->
    	console.log values # => [123, 0]
    

• @onUnhandledRejection(reason)

  Catch all possibly unhandled rejections. If it is set, auto console.error unhandled rejection will be disabed.

  • param: reason { Any }

    The rejection reason.

    Promise = require 'yaku'
    Promise.onUnhandledRejection = (reason) ->
    	console.error reason
    

FAQ

• Long stack trace support?

  Latest Node.js and browsers are already support it. If you enabled it, Yaku will take advantage of it without much overhead. Such as this library longjohn for Node.js, or this article for Chrome.

Unit Test

This project use promises-aplus-tests to test the compliance of Promise/A+ specification. There are about 900 test cases.

Use npm run no -- test to run the unit test.

Benchmark

Use npm run no -- benchmark to run the benchmark.

Misc.

The name yaku comes from the word 約束(yakusoku) which means promise.