till.mjs Documentation

ES6 Promise Utility Library

Small library with a collection of utilities designed to facilitate the use of the ES6 Promise, especially with the await operator.

View on GitHub

promise(executor)

executor Function/Promise/mixed

The Promise, or the executor function, or the value of resolved promise

return Promise

Original Promise, or initialized Promise, or resolved Promise

Shorcut for Promise initialization.

import {promise} from "./till.mjs";

const result = await promise((ok, ko) =>
{
	ok("Resolved!");
});

console.log(result);
// "Resolved!"

ok(value)

value mixed

The resolved result of the Promise

return Promise

Resolved promise

Shortcut for Promise.resolve.

import {ok} from "./till.mjs";

const result = await ok("Resolved!");

console.log(result);
// "Resolved!"

ko(error)

value Error/string

The Error instance or error description string for the rejected Promise

return Promise

Rejected promise

Shortcut for Promise.reject.

import {ko} "./till.mjs";

const result = await ko("Something went wrong");

// Error("Something went wrong")

all(fn, [fn, ...])

fn Function/Promise/Array

The first executor function or Promise to resolve.
The list of executors or Promises to be solved can be passed as individual arguments or as an Array in the first argument.

[fn,...] Function/Promise

Additional executor functions or Promises

return Promise

Result of all Promises or Rejection

Shortcut for Promise.all, with the ability to pass the promises as single arguments.

import {all, ok} "./till.mjs";

const result = await all(
	ok("Result #1"),
	ok("Result #2"),
	ok("Result #3")
);

console.log(result);
// ["Result #1", "Result #2", "Result #3"]

race(fn, [fn, ...])

fn Function/Promise/Array

The first executor function or Promise to resolve.
The list of executors or Promises to be solved can be passed as individual arguments or as an Array in the first argument.

[fn,...] Function/Promise

Additional executor functions or Promises

return Promise

The first resolved Promise

Shortcut for Promise.race, with the ability to pass the promises as single arguments.

import {race, ok} "./till.mjs";

const result = await race(
	(resolve) => { setTimeout(() => { resolve("One"); }, 600); },
	(resolve) => { setTimeout(() => { resolve("Two"); }, 200); },
	(resolve) => { setTimeout(() => { resolve("Three"); }, 400); },
);

console.log(result);
// "Two"

to(promise)

promise Promise

The Promise to manage

return Promise

Promise with managed result object

Function that allows the safe use of await without the need for a try / catch. In case of rejection the error is captured and returned.
The structure of the result of the function is an object with two properties: "success" true / false and depending on the case "payload" or "error" evaluated.

import {to, ok, ko} "./till.mjs";


const result1 = await to(
	ok("Resolved!")
);

console.log(result1);
// {"success": true, "payload": "Resolved!"}


const result2 = await to(
	ko("Something went wrong")
);

console.log(result2);
// {"success": false, "error": Error("Something went wrong")}

chain(fn, [fn, ...])

fn Function/Promise/mixed

The Promise, or the executor function for the Promise, or value for the resolved promise

[fn,...] Function

Sequence of functions to pass as chain of then() method calls

return Promise

Result Promise of the chain calls

Function that allows you to execute a promise followed by a sequence of transformations of the returned value through a chain of calls to the then() method.

import {chain} "./till.mjs";

const result = await chain(
	(ok, ko) =>
	{
		ok(2);
	},
	(value) =>
	{
		return value * 2;
	},
	(value) =>
	{
		return value + 3;
	}
);

console.log(result);
// 7

every(fn, [fn, ...])

fn Function/Promise/Array

The first executor function or Promise to resolve.
The list of executors or Promises to be solved can be passed as individual arguments or as an Array in the first argument.

[fn,...] Function/Promise

Additional executor functions or Promises

return Promise

Result of all Promises

Similar to the "all" function but with the "to" function applied to each element.
This allows to obtain the result of each Promise, both in case of resolution and rejection.

import {every, ok, ko} "./till.mjs";

const result = await every(
	ok("Result #1"),
	ko("Error #2"),
	ok("Result #3")
);

console.log(result);
// [{"success": true, "payload": "Result #1"},
//	{"success": false, "error": Error("Error #2")},
//	{"success": true, "payload": "Result #3"}]

sleep(ms [, data])

ms Number

The time to wait before Promise resolution, in milliseconds

data mixed

Optional. Promise, or executor function, or data value to pass to sleep() resolution after waiting time expires

return Promise

Result passed data

This function in conjunction with the use of await allows pausing the execution of the current context.
Without the use of await it allows you to perform a Promise with delay.

import {sleep} "./till.mjs";

const result = await sleep(3000, "wake up!");

console.log(result);
// "wake up!"

retry(retries, executor)

retries Number

The maximum number of attempts to retry to execute the Promise

executor Function

The executor function with the addition of two arguments, the attempt index and the total number of attempts

return Promise

Result Promise

This function allows you to execute the call to Promise several times in the case of re-rejection, until there is a resolution or the attempts are exhausted.

import {retry} "./till.mjs";

const result = await retry(3, (resolve, reject, i, n) =>
{
	if(i == n)
	{
		resolve("At the last attempt");
	}
	else
	{
		reject(new Error("Failed attempt"));
	}
});

console.log(result);
// "At the last attempt"

Generated with Iris Docs v 0.2.0
Styled with Iris CSS
Syntax highlight by prism.js