lz-promise
Lazy evaluation for asynchronous operations to simplify writing efficient imperative control flow.
Inspired by lazy evaluation in languages like Haskell and Scala, except only for async operations.
Motivation
One pitfall of Promises is that they immediately execute with construction. When programming imperatively with async/await, there are often values resulting from IO calls that you only use if the code follows a particular path. It is difficult to write elegant code while minimizing these costly operations. This package solves this problem by deferring the execution of the Promise until its value is needed, and saving the value for later use, so it is never excecuted more than necessary.
Usage
const lz = ; // creates a LazyPromiseconst lazyValue =
Examples
Early return
{ if messagelength === 0 throw 'message must have content'; const user = await lazyUser; user; // ...} { const lazyUser =
Conditional Control Flow
{ const lazyValue1 = ; const lazyValue2 = ; if x // result of costlyApiCall1() is stored for next lazy usage console; if y // uses last result if available console; console; if z console; }
Array Operations
{ // if users is empty, no time is wasted fetching the last message await Promiseallusers;}
API
Classes
Functions
- lz(promiseCreator) ⇒
LazyPromise
Alias for LazyPromise.fromPromiseCreator that creates a new LazyPromise from a function that returns a Promise.
LazyPromise
Kind: global class
- LazyPromise
- new LazyPromise(executor)
- instance
- .then(onFulfilled, onRejected) ⇒
Promise
- .catch(onRejected) ⇒
Promise
- .finally(onFinally) ⇒
Promise
- .then(onFulfilled, onRejected) ⇒
- static
new LazyPromise(executor)
Creates a new LazyPromise with the standard Promise constructor, except that executor is deferred until .then(), .catch(), or .finally() is called.
Param | Type | Description |
---|---|---|
executor | function |
Callback used to initialize the promise. This callback is passed two arguments: a resolve callback used resolve the promise with a value or the result of another promise, and a reject callback used to reject the promise with a provided reason or error. |
Promise
lazyPromise.then(onFulfilled, onRejected) ⇒ Calls the executor if it has not been executed. Attaches callbacks for the resolution and/or rejection of the resulting Promise.
Kind: instance method of LazyPromise
Returns: Promise
-
A Promise for the completion of which ever callback is executed.
Param | Type | Description |
---|---|---|
onFulfilled | function |
The callback to execute when the Promise is resolved. |
onRejected | function |
The callback to execute when the Promise is rejected. |
Promise
lazyPromise.catch(onRejected) ⇒ Calls the executor if it has not been executed. Attaches a callback for only the rejection of the resulting Promise.
Kind: instance method of LazyPromise
Returns: Promise
-
A Promise for the completion of the callback.
Param | Type | Description |
---|---|---|
onRejected | function |
The callback to execute when the Promise is rejected. |
Promise
lazyPromise.finally(onFinally) ⇒ Calls the executor if it has not been executed. Attaches a callback that is invoked when the resulting Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.
Kind: instance method of LazyPromise
Returns: Promise
-
A Promise for the completion of the callback.
Param | Type | Description |
---|---|---|
onFinally | function |
The callback to execute when the Promise is settled (fulfilled or rejected). |
LazyPromise.fromPromiseCreator(promiseCreator)
Creates a new LazyPromise from a function that returns a Promise.
Kind: static method of LazyPromise
Param | Type | Description |
---|---|---|
promiseCreator | function |
Function that the returns the Promise to be deferred until .then(), .catch(), or .finally() is called. |
Promise
LazyPromise.resolve(value) ⇒ Creates a new resolved LazyPromise for the provided value. Equivalent to Promise.resolve() because value is already executed
Kind: static method of LazyPromise
Returns: Promise
-
A promise whose internal state matches the provided value.
Param | Type | Description |
---|---|---|
value | any |
The value which is resolved |
LazyPromise
LazyPromise.reject(reason) ⇒ Creates a new rejected LazyPromise for the provided value. Equivalent to Promise.reject() because value is already executed
Kind: static method of LazyPromise
Returns: LazyPromise
-
A promise whose internal state matches the provided value.
Param | Type | Description |
---|---|---|
reason | any |
The value which is rejected |
LazyPromise
LazyPromise.all(values) ⇒ Creates a LazyPromise that, when .then(), .catch(), or .finally() is called, is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.
Kind: static method of LazyPromise
Returns: LazyPromise
-
A new LazyPromise.
Param | Type | Description |
---|---|---|
values | Iterable |
An iterator of Promises, values, or LazyPromises |
LazyPromise
LazyPromise.race(values) ⇒ Creates a LazyPromise that, when .then(), .catch(), or .finally() is called, is resolved or rejected when any of the provided Promises are resolved or rejected that Promise's value.
Kind: static method of LazyPromise
Returns: LazyPromise
-
A new LazyPromise.
Param | Type | Description |
---|---|---|
values | Iterable |
An iterator of Promises, values, or LazyPromises. |
LazyPromise
lz(promiseCreator) ⇒ Alias for LazyPromise.fromPromiseCreator that creates a new LazyPromise from a function that returns a Promise.
Kind: global function
Param | Type | Description |
---|---|---|
promiseCreator | function |
Function that the returns the Promise to be deferred until .then(), .catch(), or .finally() is called. |