Options

All options of AsyncLoaderOptions.

Overview

Option	Type	Default	Description
autostart	boolean	true	Whether to start loading on construction; set to false for lazy loading on first get()
cache	number	0	Cache TTL in ms. =0 disables caching, >0 sets the TTL
hash	string	auto-generated	Unique hash identifying the load task, also used as cache key; auto-generated per instance when cache>0 but not provided
abortSignal	AbortSignal	—	External abort signal; aborts loading when triggered (and does not trigger retry)
timeout	number	—	Per-attempt timeout in ms, effective when >0; a timeout counts as a retryable failure
retry	number	0	Max retry count on failure. Manual abort does not retry; timeout and business errors do
retryDelay	number	0	Milliseconds to wait before each retry
multiplex	"off" | "restart" | "share"	"off"	Reuse loader instances by hash (see below)
multiLoaderStrategy	"fallback" | "combine"	"fallback"	Multi-loader orchestration strategy (effective when loader is an array with length > 1, see below)
onResults	(results: (T | Error)[], defaultValue: T | undefined) => T	—	Result merge hook for the combine strategy (see below)
defaultValue	T	—	Fallback resolved on final failure (see below)
storage	IStorage	MapStorage	Storage backend for cache entries
onPending	(() => void) | (() => void)[]	—	Called when loading starts (only on actual loads, not cache hits)
onFulfilled	((result: T) => void) | ((result: T) => void)[]	—	Called on success including defaultValue fallback (not on cache hits)
onRejected	((error: Error) => void) | ((error: Error) => void)[]	—	Called on final failure or abort (not on cache hits)

multiplex values

• "off" (default): each instance is independent.
• "restart": when hitting the same hash that is inflight, abort that load and reload with the first instance's loader (later loaders are ignored).
• "share": fully share the inflight load and result of the first instance.

When not off and no hash is given, a hash is auto-generated from the loaders. See Multiplexing.

multiLoaderStrategy values

The constructor's loader argument accepts either a single function or an array (IAsyncLoader | IAsyncLoader[]). When it is an array with length > 1, multiLoaderStrategy decides how to orchestrate them:

• "fallback" (default): failover. Try loaders in order; the first success stops the rest; on a loader failure, try the next; all failures count as one failed attempt (which can trigger retry of the whole sequence).
• "combine": multi-source merge. Run all loaders concurrently; results (successful T, failed Error) are collected and passed to onResults to merge.

No-op for a single loader (original behavior is preserved). See Multi-Loader.

onResults notes

• Called only when multiLoaderStrategy="combine"; fallback never calls it (ignored even if provided).
• results: array of all loaders' results (in loaders order); successful items are T, failed items are Error objects.
• defaultValue: the value from options.defaultValue (may be undefined), available for the hook to fall back.
• Returns the merged result T; a synchronous throw is treated as a failed attempt (goes through the retry / onRejected / defaultValue terminal flow).
• This is a transformation function with a return value (not an event callback) — errors must propagate, and it does not go through the error-swallowing mechanism of onFulfilled/onRejected.

defaultValue notes

• Resolved on final failure (business error / timeout after retries exhausted).
• Falsy values (0 / "" / null / false) are valid fallbacks when explicitly provided.
• Has no effect on manual abort() (still rejects with AbortError).
• The fallback is not written to the cache. See Default Value.

Callbacks

onPending / onFulfilled / onRejected each accept one callback or an array; array items are invoked concurrently, and errors thrown inside are ignored.

Two layers of timeout

options.timeout is a per-attempt loading timeout (retryable); the args.timeout forwarded by get(args) is a wait timeout — they have different semantics.