Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vietj/ceylon-promises

A promise module for Ceylon based on Promises/A+ specification
https://github.com/vietj/ceylon-promises

Last synced: 30 days ago
JSON representation

A promise module for Ceylon based on Promises/A+ specification

Awesome Lists containing this project

README 

        
A module that provides Promises/A+ semantics adapted to the Ceylon language.



This implementation conforms to the [Promises/A+](https://github.com/promises-aplus/promises-tests) specification although

it is not a formal implementation due to the adaptation to the Ceylon language and type system. However it attempts

to respect the meaning of the specification and the same terminology.



The modules provides:



- the Thenable interface forming the ground of promises, implemented primarily by the Promise interface.

- the Promise interface conforming to the specification, a promise is a Thenable for a single value.

- the Deferred type providing support for the Promise interface.

- the Status enumerated instance with the  pending, fulfilled and rejected instances.

- the Term interface for combining promises into a conjonction promise.



# Goal

 

If a function cannot return a value or throw an exception without blocking, it can return a promise instead. A promise is

an object that represents the return value or the thrown exception that the function may eventually provide. A promise

can also be used as a proxy for a remote object to overcome latency.

 

# Usage

 

## Promise

 

The Promise interface expose the `then_` method allowing interested parties to be notified when the promise makes

a transition to the *fulfilled* or the *rejected* status:

 

    Promise promise = getPromise();

    promise.then_(

        (String s) => print("The promise is resolved with " + s),

        (Exception e) => print("The promise is rejected with " + e.message));

 

The first function is called the `onFulfilled` callback and the second function is called the `onRejected` callback. The 

 `onRejected` function is optional. 

 

## Deferred

 

A Deferred object provides an implementation of the Promise interface and can be transitionned to a fulfillment

or a reject resolution. It should remain private to the part of the code using it and only its promise should be visible.



The Promise of a deferred can be retrieved with its `promise` field.

 

    value deferred = Deferred();

    return deferred.promise;

 

The Deferred object implements the Transitionnable interface which provides two methods for resolving the promise:

 

- `resolve`: resolves the promise with a *value*

- `reject`: rejects the promise with an *reason* of type `Exception`.



For example:



    value deferred = Deferred();

    void doOperation() {

      try {

        String val = getValue();

        deferred.resolve(val);

      }

      catch(Exception e) {

        deferred.reject(e);

      }

    }

 

## Chaining promises

 

When invoking the `then_` method the *onFulfilled* and *onRejected* callbacks can return a value. The `then_` method

returns a new promise that will resolve with the value of the callback. This promise will be rejected if the callback

invocation fails.



    Promise promiseOfInteger = getPromiseOfInteger();

    Promise promiseOfString = promiseOfInteger.then_((Integer i) => i.string);

    promiseOfString.then_((String s) => print("Completed with " + s));

 

or shorter

 

    getPromiseOfInteger().then_((Integer i) => i.string).then_((String s) => print("Completed with " + s));

 

## Combining promises

 

Promises can be combined into a single promise that is resolved when all the combined promises are resolved. If one

of the promise is rejected then the combined promise is rejected.

 

    Promise promiseOfInteger = getPromiseOfString();

    Promise promiseOfString = getPromiseOfInteger();

    promiseOfInteger.and(promiseOfString).then_(

        (Integer i, String s) => print("All resolved"),

        (Exception e) => print("One failed"));

 

There are two things to note here:

- the order of the arguments in the callback is in reverse order of the chaining.

- the return type of combined promise is not Promise but Thenable.

 

## Callbacks

 

Callbacks can have the type of the promise value or the `Exception` type, but they can also be a zero argument function

when the value of the reason is not meaningful:

 

    promise.then_(() => print("fulfilled"), () => print("rejected"));

 

## Always

 

The `always` method of a promise allows to be notified when the promise is fulfilled or rejected, it takes as argument

of the callback an alternative of the promise value type and reason type:

 

    promise.always((String|Integer) p => print("done!");

 

Always is useful for implementing a finally clause in a chain of promise. The callback can also have zero parameter.

 

## Feeding with a promise

 

Deferred can be transitionned with promises instead of a value:

 

    Deferred deferred1 = getDeferred1();

    Deferred deferred2 = getDeferred2();

    deferred1.resolve(deferred2);

 

Similarly the callback can return a promise instead of a value:

 

    Deferred deferred = Deferred();

    promise.then__((String s) => deferred.promise);

 

# Differences with the original specification:



- the *then must return before onFulfilled or onRejected is called* is not implemented, therefore the invocation

 occurs inside the invocation of then.

- the *Promise Resolution Procedure* is implemented for objects or promises but not for *thenable* as it requires

 a language with dynamic typing.