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