Rhodium is a TypeScript-first Promise alternative with error tracking, cancellation, common async utilities, and a sprinkle of syntax sugar.
It uses native Promise internally, resulting in minimal performance loss.
Rhodium implements all Promise's static and non-static methods, making them cancellable and error-tracking as well.
import * as Rh from "rhodium" // Static methods
import Rhodium from "rhodium" // ClassRhodium depends on nothing but ES2020, and AbortSignal with AbortController.
- About
- Table of contents
- Interoperability with
Promise - Features
- Inspired by
Rhodiumis awaitable at runtime, andAwaited<T>can be used to await it in types.Promise, or anyPromiseLike, can be converted toRhodiumby passing it toRhodium.resolve()ornew Rhodium()Rhodiumis convertible toPromise. Simply get thepromiseproperty of aRhodiuminstance.
Note
Conversion to Promise loses cancelability and other Rhodium-exclusive features.
Cancellation prevents any further callbacks from running.
Important
finally is completely unaffected by the cancellation feature. This callback will always execute, and it can be attached to a cancelled Rhodium.
Here is an example:
const myRhodium = Rhodium
.try(() => console.log(1))
.then(() => Rhodium.sleep(1000))
.then(() => console.log(2))
.finally(() => console.log(3))This should print 1, 2 and 3, right? And it does!
However, if we append this line:
setTimeout(() => myRhodium.cancel(), 500)...then suddenly only 1 and 3 are printed. Invocation of cancel has prevented the second console.log!
Important
cancelreturns aRhodium, but it is actually synchronous at its core. Oncecancelis run, its effects are immediate.- If
Rhodiumrejects right before cancellation, the reason might get suppressed. IfRhodiumrejects during cancellation, the reason gets caught into the returned value.
In addition, the described below limitation causes cancel to return a rejecting Rhodium, to preserve the ease of handling errors.
Warning
- Only the last
Rhodiumin a given chain can be cancelled. Cancelling in the middle is not allowed. - It is impossible to attach a new callback to a cancelled
Rhodium, because no callbacks would run off of it. This situation throws synchronously, as deemed unintentional by the programmer. A check usingcancelledproperty is possible, if that is the intended behaviour.
A Rhodium or a Promise chain is not really a chain - it is a tree. What happens to the other branches when one gets cut off?
In that case, a branch gets cancelled all the way up until it meets another branch. Suppose you have a following tree of Rhodiums:
A -> B -> C -> D
\> E -> F -> G
Only D and G would be cancellable, because they are at the ends of their chains. There are 3 possibilities to consider:
- When
Dgets cancelled, so doesC. - When
Ggets cancelled, so doFand thenE. - Only when both
DandGget cancelled, no matter the order, doBandAget cancelled as well.
Also known as the resolution value of cancel.
Has a non-static shorthand called Rhodium.finalized.
The returned Rhodium is resolved once
thisRhodiumhad settled, or- the currently running callback and all of the following
finallycallbacks of the cancelled chain had been executed.
Rhodium
.sleep(100)
.cancel()
.then(finalizationResult => /* == { status: "cancelled" } */)
// ^? RhodiumFinalizedResult<void, never>Tip
Awaiting finalization could be useful, for example, to
- suspense starting new chains, that use the same non-shareable resource, held by the cancelling chain;
- check for suppressed
cancelerrors, which one might want to rethrow; - etc.
Note
The returned Rhodium is the beginning of a new chain. It is detached from the input Rhodium, and will not propagate cancellation to it.
On cancel, the currently running callback will not be stopped, and it will delay finalization. If the time it takes for a Rhodium to finalize is important, then it might be of interest to optimize this time.
Every callback, attached by then, catch, etc. (except the non-cancellable finally), and the constructor, are provided an AbortSignal as the second argument, which is triggered when that callback has been running at the time of cancel. On signal, the callback should resolve as soon as possible.
Using this signal is completely optional - it is only an optimization.
Example:
const fetchRh = Rhodium.try(
(url, signal) => fetch(url, { signal })
)
fetchRh.cancel() // Aborts the network request!You no longer have to write the following boilerplate:
new Promise(resolve => setTimeout(resolve, milliseconds))The same can now be written as Rhodium.sleep(milliseconds), with the advantage of being early cancellable.
Note
sleep uses AbortSignal.timeout internally!
The timeout is based on active rather than elapsed time, and will effectively be paused if the code is running in a suspended worker, or while the document is in a back-forward cache.
Same as Promise.allSettled(); except the rejection reason is properly typed, and it is applied to one Rhodium instead of an array.
Has a non-static shorthand called Rhodium.settled.
A settled Rhodium can be safely awaited! You will not lose the error type, because it makes its way into the resolution type.
However, async functions still have rejection type unknown, and cannot be cancelled - for that reason use Rhodium.tryGen.
const myRhodium: Rhodium<"value", Error> = /* ... */
const { value, reason, status } = await myRhodium.settled()
// ^? value: "value" | undefined
// reason: Error | undefined
// status: "fulfilled" | "rejected"
if (value) {
console.log(value, reason, status)
// ^? value: "value"
// reason: undefined
// status: "fulfilled"
} else {
console.log(value, reason, status)
// ^? value: undefined
// reason: Error
// status: "rejected"
}Executes a generator function, that is now able to type-safely await Rhodiums, by yield*-ing them instead. When a yielded Rhodium resolves, the generator is resumed with that resolution value.
The return value of the generator becomes the resolution value of tryGen.
Tip
The generator function is free to
- never return;
- use any JavaScript constructs such as
while,for,switch,if,using, etc.; yield*other such generators, including itself;
Warning
But it cannot use await (including await using and for await), because it is not actually an async function.
Rhodium.tryGen(function* () {
for (let i = 1; i <= 10; i++) {
const { value: items, reason } = yield* fetchItems(i).settled()
if (items) {
console.log(`Page ${i}: ${items}`)
} else {
console.error(reason)
}
yield* Rhodium.sleep(1000)
}
})With the power of type guards, handling specific errors becomes easy. The first argument is a filter for specific errors, and the second is the callback, which gets called with only the allowed errors. Filtered out errors get rejected again, unaffected, essentially "skipping" catchFilter.
const myRhodium: Rhodium<Data, ErrorA | ErrorB> = /* ... */
myRhodium.catchFilter(
err => err instanceof ErrorA,
(err /* : ErrorA */) => "handled ErrorA" as const
) // <? Rhodium<Data | "handled ErrorA", ErrorB>Attaches a time constraint to a Rhodium.
If it fails to settle in the given time, chains after timeout get a rejection, and chain before timeout gets cancelled.
Rhodium
.sleep(10000)
.timeout(10) // Uh oh, this rejects, sleep takes too long
.finalized() // Resolves quickly, because sleep is cancelled!There are two ways to use the constructor:
This is identical to Rhodium.resolve, except it always creates a new instance. (When the input value is a Rhodium, resolve simply returns it.)
The Rhodium executor has an additional argument, signal. For example, let us convert a pre-Promise-era asynchronous function, that allows cancellation, to a Rhodium:
new Rhodium((resolve, reject, signal) => {
try {
longOperation({
shouldStop: () => signal.aborted,
onComplete: resolve,
onError: reject,
})
} catch(e) {
reject(e)
}
})Tip
If you need to cancel the new Rhodium from inside its executor, you can do so by assigning it to a variable:
const myNewRhodium = new Rhodium((resolve, reject, signal) => {
/* ... */
myCancelTrigger.addEventListener('stop',
() => myNewRhodium.cancel()
)
})Just make sure you are not attempting to use the variable before the Rhodium was instantiated.
Rhodium keeps track of all errors a Rhodium chain may reject with, if used correctly.
Rhodium
.try(
chance => chance > 0.5
? "success"
: Rhodium.reject("error"),
Math.random(),
)
.then(data => data /* <? "success" */)
.catch(e => e /* <? "error" */ )
.then(data => data /* <? "success" | "error" */)Caution
This library assumes throw keyword is never used. It is impossible to track types of throw errors. Rhodium has a neverthrow philosophy; you must always use Rhodium.reject() instead. I suggest enforcing this rule if you decide to adopt Rhodium.
Caution
All errors must be structurally distinct:
- ❌
new SyntaxError≈new TypeError - ✔️
class ErrA { code = 1 as const }≉class ErrB { code = 2 as const }
This is a TypeScript limitation. Any object containing another triggers a subtype reduction. Usually this object would be constructed by Rhodium.reject(), but this does work for everything, e.g., arrays:
class ErrorA extends Error {}
class ErrorB extends Error {}
// ▼? const result: ErrorA[]
const result = Math.random() > 0.5
? [new ErrorA()]
: [new ErrorB()]Important
Other PromiseLike objects returned inside the chain automatically change the error type to unknown. We can never be sure what type they reject, if any. This includes async callbacks, as they always return Promises.
Similarly to Awaited<T>, which returns the resolution type,
Errored<T> returns the error type.
const promise = Promise.reject()
type E = Errored<typeof promise>
// ^? unknownconst promise = Rhodium.resolve()
type E = Errored<typeof promise>
// ^? neverconst promise = Rhodium.reject()
type E = Errored<typeof promise>
// ^? voidconst promise = Rhodium.reject(new TypeError())
type E = Errored<typeof promise>
// ^? TypeError