promise-or-value v1.0.0-alpha.2

promise-or-value

This module is designed around the idea of a custom TypeScript type:

type PromiseOrValue<T> = Promise<T> | T;

The motivations for this type is because Promises resolve asynchronously, even if you call then on an already- resolved promise (e.g. Promise.resolve(5).then(() => …)).

Promises work this way by design! It avoids bugs.

But for performance-critical code where you're working with cacheable async data in a loop, it can be too slow.

API

then(pov, onValue, onError) - "fast" equivalent of Promise.resolve(pov).then(onValue).catch(onError)

export function then<T, V>(
  value: PromiseOrValue<T>,
  onValue: (t: T, sync?: true) => PromiseOrValue<V>,
  onError: (error: any) => PromiseOrValue<V> = throwingErrorCallback,
): PromiseOrValue<V>;

Run some logic immediately on values, or later, for promises.

all(povs) - "fast" equivalent of Promise.all(povs)

export function all<T>(values: PromiseOrValue<T>[]): PromiseOrValue<T[]>;

Returns array as-is if everything is a value, or calls Promise.all if there are any promises in the array

PromiseOrValueMapLike - for caching promise data

type PromiseOrValueMapLike<K, V> = {
  get(key: K): PromiseOrValue<V> | undefined;
  set(key: K, value: PromiseOrValue<V>): void;
};

A type used by getOrAdd. A simple conforming cache can be made with new Map<K, PromiseOrValue<V>>().

getOrAdd - for working with PromiseOrValueMapLike

export function getOrAdd<K, V>(
  cache: PromiseOrValueMapLike<K, V>,
  key: K,
  compute: (key: K) => PromiseOrValue<V>,
): PromiseOrValue<V>;

If the key exists in the cache, returns it, otherwise computes it and inserts it in the cache. If the computation returns a promise, the promise is inserted in the cache, and replaced with the literal value once it resolves.