Set of utils Tools for Typescript mainly to enhance Promise API

Dependencies

• immutable-js

Install

yarn add @finalse/utilidade or npm install @finalse/utilidade

Future

This Future type is meant to be used as Promise, so when you see Future<T>, think "Promise<T> with additionals behaviors having 4 states : NotYetStarted, Pending, Successful, Failed"

Usages Examples

Use Case 1 - Defining Fallback

// Starting by importing Future
import {Future} from "utilidade";

// Let the following type represent a User.
type User = { name : string }
const getUserFromServer1 : () => User = // Assume this is defined somehow long computation
const getUserFromServer2 : () => User = // Assume this is defined somehow long computation

// So we can do the following :
Future.from(getUserFromServer1)            // -> Return Future<User> : Create a Future by Trying to get user from Server1.
    .completeBefore({ timeOut : 3000 })    // -> Return Future<User> : This attempt should be completed before 3s get elapsed
    .recover(exception => {})              // -> Return Future<void> : If this attempt fails, we recover from failure ignoring the exception.
    .delay({ duration : 1000 })            // -> Return Future<void> : We will then wait 1s. We still have Future<void>
    .map(ignored => getUserFromServer2())  // -> Return Future<User> : (`map` is almost like `then`) And we will try again to get user from Server2.
    .onComplete({
        ifSuccess : user => console.log("Returned User From Server " + user.name),
        ifFailure : exception  => console.log("An exception Occured " + exception.toString())
    })

Use Case 2 - Delaying execution and Retrying

You will see why the Future can be in a NotYetStarted state: In fact it is its initial state.

import {LazyFuture} from 'utilidade';

const lazyFuture: LazyFuture<User> = Future.lazyFrom(() => getUserFromServer1())
  .completeBefore({timeOut: 3000})
  .recover(exception => {})
  .delay({duration: 1000})
  .map(ignored => getUserFromServer2());
// The lazy future previously created is not yet executed
// We can pass it around as parameters

// We can also execute it
lazyFuture.start(); // Return Future<User>
lazyFuture.start(); // Won't retry as it already have been evaluated

// We can also execute it after 3seconds
lazyFuture.startAfter({duration: 3000}); // Return Future<User>

// We can also retry all of previously defined computations
lazyFuture.reinitialize(); // Return a new LazyFuture<User> Reset to its initial State
lazyFuture.reinitialize().start(); // Return a new LazyFuture<User> Reset to
// its initial State start it and Return Future<User>

Use Case 3 - Rendering Promise inside React component

There exists in Future class a method called fold that will "open and see in" the future and following the current state of the future, a computation will append with the value inside the future object if any

// Here is the render we can write with the fold method
render() {
    const getUserFromServerFuture : Future<User> = ... // Assume we have a future fetching the user from Server
    return (
        <div>
            {
                getUserFromServerFuture.fold({ // fold method will "open and see in" the future
                    ifSuccess : user => <span>Hello {user.name}</span>,
                    ifFailure : exception => <span>An Error Occured</span>,
                    otherwise : () => <Loading />
                })
            }
        </div>
    );
}

4 - Comparison with Promise API

| Promise<T> | Future<T> | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | | | Query Internal State | | | None | future.isCompleted() future.isNotYetStarted() future.isPending() future.isSuccess() future.isFailure() | | Pull the value out | | | None | future.valueOrNull() future.exceptionOrNull() | | Transform | | | then<U>(fn : T => U) : Promise<U> then<U>(fn : T => Promise<U>):Promise<U> catch<U>(fn: any => U):Promise<U> catch<U>(fn: any => Promise<U>):Promise<U> finally<U>(fn: () => U):Promise<U> finally<U>(fn: () => Promise<U>):Promise<U> | map<U>(fn : T => U) : Future<U> flatMap<U>(fn : T => Future<U>): Future<U> recover<U>(fn : T => U) : Future<U> flatRecover<U>(fn : T => Future<U>) : Future<U> transform<U>(fn: () => U): Future<U> flatTransform<U>(fn: () => Future<U>): Future<U> | | Timeout / Delay | | | None | delay(obj : { duration: number }): Future<T> completeBefore(obj:{ timeOut: number }):Future<T> | | Callback | | | None (but can be simulated with then/catch/finally) | onComplete(fn : () => void): void onSuccess(fn : T => void) : void onFailure(fn: Exception => void): void | | Static Method Creation | | | Promise.resolve<T>(value:T) : Promise<T> Promise.reject<T>(exception:any):Promise<T> | Future.successful<T>(value:T): Future<T> Future.failed<T>(exception:Exception): Future<T> Future.foreverPending<T>() : Future<T> Future.notYetStarted<T>(): Future<T> | | Static Method Helpers | | | Promise.all<T>(promises:[Promise<T>]):Promise<[T]> Promise.race<T>(promises:[Promise<T>]): Promise<T> | Future.all<T>(futures: [Future<T>]): Future<[T]> Future.firstCompletedOf<T>(futures: [Future<T>]): Future<T> Future.lastCompletedOf<T>(futures:[Future<T>]):Future<T> Future.startAfter<T>(timeout:number,                                     fn: () => Future<T>):Future<T> Future.executeAfter<T>(timeout:number,                                        fn: () => T):Future<T> |

Nomenclature

Why not using catch/then/finally ?

Because catch is a reserved keyword, we choose NOT to try to force the definition of a method named catch. Hence we did not choose then because we knew that catch won't be available. If a then method were defined, it would have been weird if the catch method were missing. The same goes for finally reserved keyword.

Why naming map instead of then ?

What does the map allows you to do ? Create a new data structure by opening you current data structure and apply a function on every items inside of it.

Array(1, 2, 3).map(i => i + 1); // Create a new Array starting from the current Array and applying a function to every elements inside of it
Future(1).map(i => i + 1); // Create a new Future starting from the current Future and applying a function to every elements inside of it

NB : See this link for some theorical resource about the map function.

Why naming flatMap / flatRecover / flatTransform ?

We all know the mapfunction defined in array

const array1 = Array(1, 2, 3).map(i => i * 2); // Return Array(2, 4, 6)
const array2 = Array(1, 2, 3).map(i => {
  num: i;
}); // Return Array({num : 1}, {num : 2}, {num : 3})

Now Assume we have the flatMap method defined on Array by this behaviour :

const array3 = Array(1, 2, 3).flatMap(i => Array(i, i)); // Return Array(1, 1, 2, 2, 3, 3)

If We use the map function defined in Array, with the same argument as flatMap function previously defined , ie i => Array(i, i), we will have the following result

const array4 = Array(1, 2, 3).map(i => Array(i, i)); // Return Array(Array(1, 1), Array(2, 2), Array(3, 3))

Now assume we have the flatten method defined on Array by this behaviour :

const array5 = Array(Array(1)).flatten; // Return Array(1)
const array6 = Array(Array(1), Array(2)).flatten; // Return Array(1, 2)

So to get what we get in array1, we have to "flatten" the array2

// array3 == array4.flatten
// because array4 = Array(1, 2, 3).map(i => Array(i, i))
// array3F == Array(1, 2, 3).map(i => Array(i, i)).flatten

We then have the nomenclature FlatMap means map and then flatten The same pattern goes for Set, List, and Future and we could define flatMap such as

// Set(1).flatMap(i => Set(i + 1))          // Return Set(2)
// List(1).flatMap(i => List(i + 1))        // Return List(2)
// Future(1).flatMap(i => Future(i + 1))    // Return Future(2)
// and so one....

NB : With this flatMap operations and others functions having some other properties, the Future Data structure is a Monad

🏠 Homepage

Author

👤 Finalse Cloud [email protected]

• Github: @finalse

Show your support

Give a ⭐️ if this project helped you!