true-promise

A cancelable & typed Promise for TypeScript, Node.js & the browser.

Installation

npm install @streamhive/true-promise --save  

yarn add @streamhive/true-promise  

Features

Extended Promises

Use cancel, resolve, reject & finally on your Promise, otherwise it's just like a regular Promise.

100% Compatible

Includes babel polyfill to run your Promises without global scope pollution, it's ready-to-use.

Built-in Types

Types for TypeScript and your IDE so you can write stuff like this & avoid development errors.

new TruePromise<string, number>((resolve, reject) => {
     resolve(42000); // TS Error
     reject('Oops'); // TS Error
});

How to use

ES7+ | TypeScript

const promise0 = new TruePromise<string, number>((resolve) => {  
     setTimeout(() => resolve('I <3 Promises'), 500);  
});  

const promise1 = promise0.then(() => "Won't execute");  
  
promise0.cancel('I <3 Cancelling');  
  
console.log(await promise0);  
console.log(await promise1);

Remember to remove the types when using vanilla JavaScript.

ES5+ | Browser

<script type="text/javascript" src="true-promise.web.js"></script>  
<script type="text/javascript">  
  new TruePromise.default(function () {  
          alert('I <3 Promises')  
  });  
</script>

Documentation

Do you want to know more about .resolved(), .rejected(), ... ?

Visit Quick API Manual

Examples

Let's take a few examples through a practical. If you are not using TypeScript just remove the types.

Create a basic Promise

// Create a Promise that resolves a string and errors a number  
const promise0 = new TruePromise<string, number>((resolve) => {  
     setTimeout(() => resolve('promise0'), 500);  
});  
  
// Let's chain the Promise with then  
const promise1 = promise0.then((v) => {  
     return 'promise1';  
});  
  
// Which returns a Promise  
console.log(await promise0);  
console.log(await promise1);

promise0
promise1

Cancel your first Promise manually

// Create a Promise that resolves a string and errors a number
const promise0 = new TruePromise<string, number>((resolve) => {
     setTimeout(() => resolve('promise0'), 500);
});

// Let's chain the Promise with then
const promise1 = promise0.then((v) => {
     return 'promise1';
});

// Let's chain the Promise with then 
const promise2 = promise1.then((v) => {
     return 'promise2';
});

promise0.cancel('canceled');

// Which returns a Promise 
console.log(await promise0);
console.log(await promise1);
console.log(await promise2);

canceled
undefined
undefined

Why did it display undefined ? We canceled the parent Promise so promise1 could not yield a result (and any chained/nested Promise).

Only a pending promise can be canceled. Use .status() to check it's current status.

Resolve or reject your Promise manually

// Create a Promise that resolves a string and errors a number  
const promise0 = new TruePromise<string, number>((resolve) => {
     setTimeout(() => resolve('promise0'), 500);
});

// Let's chain the Promise with then  
const promise1 = promise0.then((v) => {
     return 'promise1';
});

promise0.resolve('resolved');
promise1.reject('42');

// Which returns a Promise  
console.log(await promise0);
console.log(await promise1);

resolved
Error: Unhandled Rejection: 42

Only a pending promise can be rejected or resolved. Use .status() to check it's current status.

Todos

• Write more serious tests.

License

AGPL 3.0