This library provides Promise implementations (synchronous, idle, asynchronous and native), helpers and aliases built and tested using TypeScript. Apart from providing idle and synchronous implementations the primary focus is on supporting the creation of production code that can be better minified (resulting in a smaller runtime payload).
Provided implementations:
- Idle processing
- Synchronous processing
- Asynchronous processing
- Native runtime wrapper
The primary helpers are
createPromise
- Uses the current promise implementation set viasetCreatePromiseImpl
(defaults to createNativePromise)createNativePromise
- This is a wrapper around the runtimePromise
class that adds astatus
property, so this is effectivly the same asnew Promise(...)
but as a non-namespaced function it can be heavily minified to something likea(...)
createAsyncPromise
- Implements thePromise
contract and uses timeouts (defaults to 0ms, but can also be provided) to process any chained promises (of any type)createSyncPromise
- Also implements thePromise
contract but will immediately execute any chained promises at the point of the original promise getting resolved or rejected, or if already resolved, rejected then at the point of registering thethen
,catch
orfinally
createIdlePromise
- Implements thePromise
contract and will process any chained promises using the availablerequestIdleCallback
(with no timeout by default - but can also be changes bysetDetaultIdlePromiseTimeout
). And whenrequestIdleCallback
is not supported this will default to using a timeout via thescheduleIdleCallback
from@nevware21/ts-utils
doAwait
- Helper which handlesawait
"handling" via callback functions to avoid the TypeScript boilerplate code that is added for multiple branches. Has 3 callback options forresolved
,rejected
andfinally
cases all are optional.doAwaitResponse
- Helper which handlesawait
"handling" via a single callback whereresolved
andrejected
cases are handled by the same callback, this receives anAwaitResponse
object that provides thevalue
orreason
and a flag indicating whether the Promise wasrejected
)doFinally
- Helper to providefinally
handling for any promise using a callback implementation, analogous to usingtry
/finally
around anawait
function or using thefinally
on the promise directly
All promise implementations are validated using TypeScript with async
/ await
and the internal helper functions doAwait
, doFinally
and doAwaitResponse
helpers. Usage of the doAwait
is recommended as this will avoids the additional boiler plate code that is added by TypeScript when handling the branches in an async
/ await
functions, this does of course mean that your calling functions will also need to handle this async
operations via callbacks rather than just causing the code path to "halt" at the await
and can therefore may be a little more complex (depending on your implementation), however, you are not restricted to only using await
or doAwait
they can be used together.
Also of note is that all implementations will "emit/dispatch" the unhandled promise rejections event (if supported by the runtime) using the standard runtime mechanisms. So any existing handlers for native (new Promise
) unhandled rejections will also receive them from the idle
, sync
and async
implementations. The only exception to this is when the runtime (like IE) doesn't support this event in those cases "if" an onunhandledrejection
function is registered it will be called or failing that it will logged to the console (if possible).
The provided polyfill wrapper is build around the asynchronous
promise implementation which is tested and validated against the standard native (Promise()
) implementations for node, browser and web-worker to ensure compatibility.
Documentation generated from source code via typedoc