frappuccino

Promise library with coffee, ice and sugar!

You know when you order a Frappuccino on Starbucks, and sometimes it comes with more ice than you want, and other times it comes very tasty?

Yeah, I know what you're thinking, they are just like JavaScript Promises!

They can either go right, or go wrong.

# right
new Promise (resolve, reject) ->
  resolve 'tasty frappuccino'

# wrong
new Promise (resolve, reject) ->
  reject 'basically ice but more expensive'

So I wanted to understand how JavaScript Promises work, and also I wanted to drink something refreshing. That's how frappuccino came to live!

How to install and use it

To use the library, just use:

npm install --save frappuccino

And import it on your code:

Promise = require 'frappuccino'

You can do it on JavaScript too :wink:

const Promise = require('frappuccino')

API

new Promise(resolver)

Creates a new Promise object that expects a callback which receives two arguments, the resolve and reject functions.

A Promise has three possible states, they are: PENDING, FULFILLED and REJECTED.

The moment a new Promise is created, it will be on the PENDING state, waiting for one of the two callbacks to be called.

Once one of them is called, the Promise transitions to one of the other two states.

Example:

promise = new Promise (resolve, reject) ->
  resolve 'chocolate frappuccino'

To actually observe the value passed to one of the callbacks resolve or reject, you will need to call the .then method.

.then(onFulfill, onReject)

This method makes it possible to observe the value passed to one of the callbacks of the Promise constructor (resolve or reject).

promise = new Promise (resolve, reject) ->
  resolve 'chocolate frappuccino'

promise.then (value) -> 'wow, I\'ve got a ' + value

The onFulfilled callback will be called if the Promise has transitioned to the FULFILLED state.

The onRejected callback will be called if the Promise has transitioned to the REJECTED state.

A cool thing about the .then method, is that you can chain it.

promise = new Promise (resolve, reject) ->
  resolve 'chocolate frappuccino'

promise.then (value) -> 'wow, I\'ve got a ' + value
  .then (frappuccinoMessage) -> console.log 'nice message: ' + frappuccinoMessage

This is possible because the .then method always returns a new Promise with the input of the last one.

Errors

If it happens that one of your callbacks throws an error, the new Promise generated by .then will be in the REJECTED state.

promise = new Promise (resolve, reject) ->
  resolve 'chocolate frappuccino'

promise.then (value) -> throw new Error 'oopsy'
  .then null, (reason) -> console.error 'here is the reason:' + reason

It can happen on the constructor too, either with reject or with the throw itself.

promise = new Promise (resolve, reject) ->
  reject 'bad things happen'

# or

promise = new Promise (resolve, reject) ->
  throw new Error 'bad things happen'

How to build the code

Since the code is in CoffeeScript, and there is no interpreter for it, as far as I know, I compile it to JavaScript so that it can be used.

To build you will need to clone the repository, install the dependencies:

npm install

And finally just run:

npm run build

The code will be on the lib folder.

How to run the tests

Clone the repository, and run:

npm install

Then you will be able to run the tests by:

npm test

How to run the linter

Clone the repository, and run:

npm install

Then you will be able to run the linter by:

npm run lint

Notes

This project is heavly inspired by this.

License

You can check out the full license here

This project is licensed under the terms of the WTFPL license. You just DO WHAT THE FUCK YOU WANT TO.