transmog
transmog is a utility for converting JavaScript objects of a certain shape to JavaScript objects of a different shape. This transformation is based on standardized rules to make it easy to express and comprehend the transformation.
Features:
- reading/writing from/to nested properties
- whitelisting of properties
- conversion of property values
- default values for missing property values
API
transmog()
transmog(
rules: object,
object: object
): object
Transforms object
according to rules
.
transmog
will apply the rules
to object
without mutating it and will always return a newly created object. Note
however that the property values of the resulting object may reference the same objects as the source object
does.
There's no cloning of objects involved unless you specify individual rules which do so.
rules
The rules
object consists of key-value pairs which specify how every property of the resulting object is determined.
rules = {
"path.to.property": <boolean | function | string | object>,
...
}
The key of a rule specifies the property name or property path in the resulting object. A property path is a .
delimited string of valid property names and can be used to create nested objects.
The value of a rule is a description for how to calculate the property value based on the source object
. Different
common use cases can be expressed based on the type of the rule.
boolean rule
true | false
If true
the value of the source object
under the same path is written to the resulting object. If false
the rule
is ignored. (This is just for consistency. Instead of specifying false
the rule can be omitted as well.)
function rule
function (
sourceValue: any,
sourceObject: object
): any
The specified function is called with
- the
sourceValue
which is the property value of the sourceobject
under the same path as the rule describes - the source
object
itself.
It should return the value which will be written to the resulting object under the path which the rule describes.
string rule
"source.property.path"
The specified string is interpreted as a property path of the source object
whose value will be written to the
resulting object.
object rule
{
converter?: (sourceValue: any, sourceObject: object) => any,
sourcePath?: string,
defaultTo?: (sourceObject: object) => any
}
An object rule is the generalization of the boolean
, function
and string
rule.
The converter
function will be called with the sourceValue
and sourceObject
and should return the value which will
be written to the resulting object. If omitted the identity function will be used as a default.
The sourcePath
specifies the property path under which the sourceValue
for the converter
function will be read. If
omitted the destination path of the rule will be used as a default.
The defaultTo
function will be called if the sourceValue
is null
, undefined
or the source object
has no
property under the specified sourcePath
. It will be called with the sourceObject
as an argument and should return
the default value which will be written to the resulting object. If defaultTo
is omitted no value will be written to
the resulting object if sourceValue
is null
, undefined
or the source object
has no property under the specified
sourcePath
.
Example
TODO