Rhodium

About

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" // Class

Rhodium depends on nothing but ES2020, and AbortSignal with AbortController.

Table of contents

• About
• Table of contents
• Interoperability with Promise
• Features
  • Cancellation
    • Limitations
    • But what about multiple then calls on a single Rhodium?
  • Finalization
    • Rhodium.oneFinalized
    • Early cancellation
  • Additional methods & syntax sugar
    • Rhodium.sleep
    • Rhodium.oneSettled
    • Rhodium.tryGen - the async of Rhodium
    • Rhodium.catchFilter
    • Rhodium.timeout
    • new Rhodium
      • new Rhodium(promiseOrRhodium)
      • new Rhodium(executor) - classic Promise constructor
  • Error tracking
    • The Errored<T> type
• Inspired by

Interoperability with Promise

• Rhodium is awaitable at runtime, and Awaited<T> can be used to await it in types.
• Promise, or any PromiseLike, can be converted to Rhodium by passing it to Rhodium.resolve() or new Rhodium()
• Rhodium is convertible to Promise. Simply get the promise property of a Rhodium instance.

Features

Cancellation

Cancellation prevents any further callbacks from running.

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!

In addition, the described below limitation causes cancel to return a rejecting Rhodium, to preserve the ease of handling errors.

Limitations

But what about multiple then calls on a single Rhodium?

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 D gets cancelled, so does C.
• When G gets cancelled, so do F and then E.
• Only when both D and G get cancelled, no matter the order, do B and A get cancelled as well.

Finalization

Rhodium.oneFinalized

Also known as the resolution value of cancel. Has a non-static shorthand called Rhodium.finalized.

The returned Rhodium is resolved once

• this Rhodium had settled, or
• the currently running callback and all of the following finally callbacks of the cancelled chain had been executed.

Rhodium
  .sleep(100)
  .cancel()
  .then(finalizationResult => /* == { status: "cancelled" } */)
     // ^? RhodiumFinalizedResult<void, never>

Early cancellation

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!

Additional methods & syntax sugar

Rhodium.sleep

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.

Rhodium.oneSettled

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"
}

Rhodium.tryGen - the async of Rhodium

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.

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)
  }
})

Rhodium.catchFilter

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>

Rhodium.timeout

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!

new Rhodium

There are two ways to use the constructor:

new Rhodium(promiseOrRhodium)

This is identical to Rhodium.resolve, except it always creates a new instance. (When the input value is a Rhodium, resolve simply returns it.)

new Rhodium(executor) - classic Promise constructor

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)
  }
})

const myNewRhodium = new Rhodium((resolve, reject, signal) => {
  /* ... */
  myCancelTrigger.addEventListener('stop',
    () => myNewRhodium.cancel()
  )
})

Error tracking

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" */)

class ErrorA extends Error {}
class ErrorB extends Error {}
   // ▼? const result: ErrorA[]
const result = Math.random() > 0.5
  ? [new ErrorA()]
  : [new ErrorB()]

The Errored<T> type

Similarly to Awaited<T>, which returns the resolution type, Errored<T> returns the error type.

const promise = Promise.reject()
type E = Errored<typeof promise>
//   ^? unknown

const promise = Rhodium.resolve()
type E = Errored<typeof promise>
//   ^? never

const promise = Rhodium.reject()
type E = Errored<typeof promise>
//   ^? void

const promise = Rhodium.reject(new TypeError())
type E = Errored<typeof promise>
//   ^? TypeError

Inspired by

• Effect.ts
• Bluebird
• Neverthrow