npm package: @liqd-js/timed-promise
Description: Chainable Promises with timeouts
Author: radixxko
Latest version: 1.1.0

# TimedPromise: ECMAScript 6+ class extending standard JavaScript Promises with timeout functionality

[![NPM version](https://img.shields.io/npm/v/@liqd-js/timed-promise.svg)](https://img.shields.io/npm/v/@liqd-js/timed-promise.svg)
[![Build Status](https://api.travis-ci.org/liqd-js/timed-promise.svg?branch=master)](hhttps://api.travis-ci.org/liqd-js/timed-promise.svg?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/liqd-js/timed-promise/badge.svg?branch=master)](https://coveralls.io/repos/github/liqd-js/timed-promise/badge.svg?branch=master)
[![NPM downloads](https://img.shields.io/npm/dm/@liqd-js/timed-promise.svg)](https://img.shields.io/npm/dm/@liqd-js/timed-promise.svg)
[![Known Vulnerabilities](https://snyk.io/test/github/liqd-js/timed-promise/badge.svg?targetFile=package.json)](https://snyk.io/test/github/liqd-js/timed-promise/badge.svg?targetFile=package.json)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Sneak Peek

This library extends standard ECMAScript Promises with the timeout functionality and works in any browser supporting Promises or Node.js environment.

1. Converting standard Fetch Promise to TimedPromise with the 3s timeout
```js
let data = await new TimedPromise( fetch('http://example.com/movies.json') )
	.then( response => response.json() )
	.then( json => { return { ok: true, json } })
	.timeout( 3000, { ok: false, error: 'fetch-timeouted' })
	.catch( error => { return { ok: false, error } });
```
2. Creating new TimedPromise with the 3s timeout
```js
let data = await new TimedPromise( ( resolve, reject, timeout ) =>
{
  console.log( `Fetch timeout set to ${timeout}ms` );

  fetch('http://example.com/movies.json')
    .then( response => response.json() )
    .then( json => resolve({ ok: true, json }) )
    .catch( error => reject({ ok: false, error }) );
})
.timeout( 3000, { ok: false, error: 'fetch-timeouted' })
.catch( error => error );
```

## Motivation

Standard JavaScript [`Promises`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) does not provide any support for timeouts - failing the Promise once the timer is elapsed. There are many solutions how to simulate such functionality - for example creating new Promise with the reject callback triggered by the [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) function or using [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) method for the original Promise and a new Promise resolved by the [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) function.

## Table of Contents

* [Installing](#installing)
* [Class: TimedPromise](#class-timedpromise-extends-promise)
	+ [constructor( executor )](#new-timedpromise-executor)

## Installing

```
npm i @liqd-js/timed-promise
```
or include script for a browser release
```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/radixxko/liqd-timed-promise/dist/timed_promise.min.js"></script>
```

## Class: TimedPromise extends Promise

### new TimedPromise( executor )

- `executor` {Function|Promise}

### TimedPromise.timeout( timeout_ms[, reason = 'timeout'[, catchable_by_parent = false]] )

- `timeout_ms` {Number} Timeout for the Promise in miliseconds
- `reason` {Any} Exception thrown by the Promise when it is not resolved within a timeout
	- defaults to {String} 'timeout'
- `catchable_by_parent` {Boolean} Determines whether a timeout exception can be catched and resolved by a preceding catch in the Promise chain

Returns `this`.

### TimedPromise.created()

Returns a number representing the milliseconds elapsed between 1 January 1970 00:00:00 UTC and the TimedPromise creation.

### TimedPromise.elapsed()

Returns a number representing the milliseconds elapsed since the TimedPromise creation.

### TimedPromise.remaining()

Returns a number representing the milliseconds remaining until the TimedPromise timeout.

### TimedPromise.then( onFulfilled[, onRejected] )

Returns new TimedPromise

```js
p.then( onFulfilled[, onRejected] );

p.then( ( value, remaining_ms ) =>
{
	// fulfillment
}, ( reason, remaining_ms ) =>
{
	// rejection
});
```

### TimedPromise.catch( onRejected] )

Returns new TimedPromise

```js
p.catch( onRejected );

p.catch( ( reason, remaining_ms ) =>
{
	// rejection
});
```