within

Simple library to add timeouts to ES6 Promieses

Installation

npm install @debonet/within

Usage

Take a normal Promise call and give it a timeout by going from

    const within = require( '@debonet/within' );

    // this could take a very long time
    let myPromise = somePromiseFunction( arg1, arg2, ... );

    // this will timeout
    let myPromise = within(2000, somePromiseFunction, arg1, arg2, ...);

Promise Chains

When the within times out, it rejects the promise with a within.TimeoutError. Within introduces .timedout() which operates like a .catch() statement that catch only within.TimeoutError's

    within( 1000, func)
        .timedout(( err ) => /* handle a timeout */ )
        .catch (( err ) => /* handle other errors */ );
        

Timeouts can also be handled using a regular .catch() handler:

    within( 1000, func)
        .catch( ( err ) => {
            if ( err instanceof within.TimeoutError ) {
                /* handle a timeout */
            }
            else {
                /* handle other errors */
            }
        });

Time limited functions

Create a version of a function that will timeout if it exceeds the specified duration

    const waitUpTo1Second = within.limit( 1000, wait );

    try {
        waitUpTo1Second( 2000 );
    }
    catch {
        // will get here after 1000 ms
    }

API

within( maxTime, func [, arguments] * )

Parameters

maxTime the maximum duration (in microseconds) to wait before rejecting the promise with a within.TimeoutError.

func a function whose duration is going to be limited.

arguments | optional arguments which will be passed to func. This allows one to save the sytax overhead of wrapping a call to func in a capturing lambda () => func( arguments )

Returns

a Promise that resolves with the result of func(...arguments) or Promise.reject(Within.TimeoutError) in the event that that the call to funcdoes not complete within the indicaed maxTime.

within.limit( maxTime, func )

Parameters

maxTime the maximum duration (in microseconds) to wait before rejecting the promise with a within.TimeoutError.

func a function that will be timelimited

Returns

a function that returns a promise Promise that resolves with the result of func(...arguments) or Promise.reject(Within.TimeoutError) in the event that that the call to func does not complete within the indicaed maxTime.