@lxsmnsyc/future
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.0 • Public • Published

    @lxsmnsyc/future

    Extension to the ES6 Promise; much better reactivity in JavaScript.

    NPM JavaScript Style Guide

    Install

    npm install --save @lxsmnsyc/future
    yarn add @lxsmnsyc/future

    Introduction

    @lxsmnsyc/future attemps to extend the functionality and solve some problems that exists with the current ES6 Promise.

    First difference about Futures against Promises is that the computation is deferred: You can compose Futures without evaluating/scheduling the computation already, which is good specially if you want to compose your own logic, as well as, since Promises' resolution callback executes synchronously, you can choose when will the Future run its computation.

    By summary: Futures are the cold version of Promises.

     
    // No computation being processed
    const delayedHelloWorld = Future.success('Hello').pipe(
      Future.map(value => `${value} World`),
      Future.delay(500),
    );
     
    // Begin computation
    const computation = delayedHelloWorld.get();
     
    // get the computed value
    computation.then((value) => {
      console.log('Success: ', value);
    });
     
    // or
    const value = await computation;
    console.log('Success: ', value);

    Another difference is that Futures are cancellable. Disposing logic in Promises has been a problem, and Futures helps you with that. If a Future is cancelled, the computation stops and the asynchronous value will not be resolved. If you start a Future inside an async function, await its value, and cancels it before it has finished its computation, the async function will not continue executing.

    // Begin computation
    const computation = delayedHelloWorld.get();
     
    // get the computed value
    computation.then((value) => {
      console.log('Success: ', value);
    });
     
    // cancel the computation before it finishes
    computation.cancel();

    Usage

    Creating Futures

    Future.create is the basic operator for building your own computation logic for a Future.

    Example below is a Future that resolves Hello World after 500 ms.

    // Create our Future
    const delayedHelloWorld = Future.create((emitter) => {
      // create a timer
      const timeout = setTimeout(() => {
        // resolve the value
        emitter.success('Hello World');
      }, 500);
     
      // Make sure to cleanup our timer
      emitter.onCancel(() => {
        clearTimeout(timeout);
      });
    });

    Composing Futures

    Futures have two methods that allows you to transform the Future into a another Future with different computation logic: compose which accepts a transformation function and pipe which accepts multiple.

    For example, if we want to modify the resolved value of a Future, we can use map:

    const greeting = Future.success('Hello')
      .compose(Future.map(value => `${value} World`));
     
    greeting.get().then(console.log); // Hello World

    Computation vs Future

    There are two core classes in this library: Futures and Computation.

    To clarify, a Computation is an instance received by calling the Future#get. A Future tells how a Computation instance should run its logic.

    Documentation

    Full documentation is available here.

    Build

    This project is bootstraped with TSDX with minor changes.

    License

    MIT © lxsmnsyc

    Keywords

    none

    Install

    npm i @lxsmnsyc/future

    DownloadsWeekly Downloads

    1

    Version

    0.1.0

    License

    MIT

    Unpacked Size

    948 kB

    Total Files

    85

    Last publish

    Collaborators

    • lxsmnsyc