map-merge-defaults-pmb
Merge each item from an array (e.g. of options objects) with a base (e.g. an options object with default options) and optionally convert them using a custom conversion function. Supports promises and async functions.
API
This module ESM-exports one function that holds some methods:
mapMergeDefaults(base, [{how|dfKey}, ]orig[, convert])
Returns an array of the transformed items of input array orig
.
In the most basic mode, the transformation for each input item is
just to merge it with base
.
You can modify the transformation by providing additional arguments:
-
dfKey
: If set to a non-object, acts as a shorthand for ahow
object with just one keydfKey
, using this argument as the value. -
convert
: Overrule thehow
option with same name (see below). -
how
: An optional options object that supports these options, all optional:-
dfKey
: Default input key. If set to something other thanundefined
, any non-object item fromorig
will be objectified before merging it, by making an object with one property named the value ofdfKey
, and using the original item as the property value. -
merge
: A custom merge function. Can also befalse
,undefined
ornull
to affirm the default, which is to use.dfMerge
(default default) or.awaitMerge
(default whenpr
option is set). -
convert
: A custom conversion function. If provided, it will receive the merge result as an additional step of the transformation. Can also befalse
,undefined
ornull
to affirm the default, which is to leave the merge results as they are. If a truthyconvert
argument is given, it overrules this setting. -
pr
: Boolean, whether to wrap the result list inPromise.all()
. Default:false
. Also selects the default merge function:.dfMerge
whenpr
is false-y, or.awaitMerge
ifpr
is truthy. Note however that this does not add an await step before custommerge
orconvert
functions, so in some scenarios those may need to internally await their arguments. Alsobase
is never awaited, so you need to do that in your own code if required.
-
.pr(base, [{how|dfKey}, ]orig[, convert])
Like mapMergeDefaults
but with the how.pr
option enabled by default.
.dfMerge(base, item)
The default sync merge function. Returns { ...base, ...item }
.
.awaitMerge(base, itemPr)
The default async merge function. itemPr
may be a promise.
Returns a promise for { ...base, ...(await itemPr) }
.
Usage
see from test/usage.mjs.
Known issues
- Needs more/better tests and docs.
License
ISC