Methods

alwaysEvolve(transforms, input) → {Object}

alwaysEvolve.js, line 18

A port of Ramda's evolve(), but the transforms are always applied regardless if the key/value pair exists in the input object or not.

Parameters:

Name	Type	Description
transforms	Object	An object whose values may be transform functions that need to be wrapped in try/catch
input	Object	The input object to pass through prop-level transformations

Returns:

Object -

The modified input object, with any prop-level transforms applied to it

alwaysFunction(val) → {function}

util.js, line 62

If the provided value is NOT a function, transform it into a function that always returns that value

Parameters:

Name	Type	Description
val	*	A value of any type

Returns:

function -

If the original value was a function, that function is returned, otherwise a function that always returns the original value is returned function that always returns that value OR

applyNonTransformProps(spec, input) → {Object}

util.js, line 135

Takes an non-transform props (non-functions) in a given spec and merges them onto the input object.

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or pass-through values to be added to the return object
input	Object	An object which will be passed through the re-shaping transform functions defined by the spec

Returns:

Object -

The input object with only the pass-through props applied to it

applyWholeObjectTransforms(spec, input) → {Object}

shape.js, line 44

Applies transform functions in a given spec to a given object, BUT only the trasnforms that DON'T match key names on the input object are applied.

Parameters:

Name	Type	Description
spec	Object	An object which contains transform functions (only those which do not correspond to keys on the input object will be applied to the input object)
input	Object	An object which will be passed through the re-shaping transform functions defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it (only those that do not correspond to key names on the input object)

defaultErrorHandler(fieldName, value, exception) → {undefined}

util.js, line 155

Logs to the console any failed transform functions, along with the field name and the value that was fed into the transform function. Plus, the exception itself is also logged.

Parameters:

Name	Type	Description
fieldName	String	The field name for the failed transform function
value	Object	The value that was fed into the transform function
exception	Object	The exception thrown by the failed transform

Returns:

undefined

evolveSpec(transforms, input) → {Object}

evolveSpec.js, line 24

A port of Ramda's evolve(), but any primitive value or array in the transform spec is wrapped in a function that always returns that value. Any functions already on the transform spec are applied at the prop-level (like evolve() always does) and any objects on the transform spec call the evolver recursively (again, normal behavior for evolve()). In other words, the only difference between this and Ramda's evolve() function is that primitives and array vales are wrapped in an always() function before the spec is fed to evolve() rather than being omitted from the final output.

Parameters:

Name	Type	Description
transforms	Object	An object with transform functions or nested transform functions or primitive vales to be wrapped with a function.
input	Object	The input object to pass through prop-level transformations

Returns:

Object -

The modified input object, with any prop-level transforms applied to it

impliedRemove(spec, input) → {Object}

prune.js, line 99

Removes the any props from the input not named in the spec. Doesn't matter what the value types are in the spec: if the key name doesn't exist in the spec, it won't exist in the output.

Parameters:

Name	Type	Description
spec	Object	An object
input	Object	An object which will have any props not named in the spect removed

Returns:

Object -

The input object with the props removed which were not in the spec too

isPlainObj(val) → {Boolean}

util.js, line 38

This is what you really mean when you're checking to see if something is an Object. Honestly who cares that an Array, Date and RegExp are technically objects too? You were looking for the thing with the curly braces {} right?

Parameters:

Name	Type	Description
val	*	A value of any type

Returns:

Boolean -

Whether or not the value is an Object

keepAndShape(spec, input) → {Object}

prune.js, line 40

Keeps only the props you name in your spec. If you provided a function, it is applied at the prop-level. It is expected (best practice, for conveying intent) that you give a value of true for props that you want to keep but not transform (a zipped object - where key and value are both strings of the same name - makes sense too). In this mode, if you provide any other type of value it won't be used in the spec. If the prop doesn't exist, you won't see it on the output (use shapeSuperStrictly if you want to see undefined for those cases instead).

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or (preferrably) a value of true to signal a value to be preserved (as-is) on the output
input	Object	An object which will be passed through the pruning/re-shaping defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it and unnamed props shaved off the output

keeper(spec, input) → {Object}

prune.js, line 17

Keeps only the props you name in your spec. It is expected (best practice, for conveying intent) that you give a value of true for props that you want to keep but not transform (a zipped object - where key and value are both strings of the same name - makes sense too).

Parameters:

Name	Type	Description
spec	Object	An object whose values are true or match the key name to signal a value to be preserved (as-is) on the output
input	Object	An object which will be passed through the pruning defined by the spec

Returns:

Object -

The input object with the unnamed props shaved off the output

makeFunctionUnlessObject(val) → {function|Object}

util.js, line 74

If the provided value is neither an Object nor a Function, transform it into a function that always returns that provided value.

Parameters:

Name	Type	Description
val	*	A value of any type

Returns:

function | Object -

A function that always returns the provided value OR the original value (if it was already a Function or an Object)

makePruningSpec(spec) → {Object}

util.js, line 87

Makes sure a given spec is acceptable for one of the pruning modes (ie, "remove" or "keep"). Specs in this mode are treated more strictly, meaning the prop must be given a value of "true" or the key and value can be identical. Functions are acceptable values in the spec of course.

Parameters:

Name	Type	Description
spec	Object	A spec to be coerced into an acceptable pruning spec

Returns:

Object -

A spec that is acceptable to be used in pruning mode.

makeShaper(spec, input) → {Object}

shape.js, line 155

A single function that selects and applies one of the available re-shaping functions in the shapey library, depending on what you've set the shapeyMode prop to in the spec you provide as the first argument to this function.

Think of it like a case statement in a Redux reducer, however since you most likely don't want to sacrifice the meanining associated with the "type" property to internals of shapey, a prop called "shapeyMode" is used instead.

If for some reason you have some prop on the input (the object you're transforming) already named "shapeyMode", um . . . don't.

Available modes (case & space in-sensitive): "strict" - uses shapeStrictly, where only the props named in your spec are included in the output "keep" - uses keepAndShape, where all the props you name in your spec are kept. "remove" - uses removeAndShape, where all the props you name in your spec are removed.

In addition to controlling the mode for Shapey, you can control how the transforms are applied. This is controlled via the reserved prop in your spec called "shapeyTransforms", and the available options for it are: "prop" - All transforms are applied at the prop-level, regardless if they exist on the input object "whole" - All transforms are given the entire input object as input (regardless if a prop matching the name of the transform exists on the input object)

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or pass-through values to be added to the return object
input	Object	An object which will be passed through the re-shaping transform functions defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it

objectify(val) → {Object}

util.js, line 49

Turns any non-Object values into empty objects

Parameters:

Name	Type	Description
val	*	A value of any type

Returns:

Object -

If the original value was an Object, it is returned as-is, otherwise an empty object is returned

onlySpecTransforms(spec) → {Object}

util.js, line 103

Filters a spec (object) to only the props that are transform functions. If the input is not an object, this is just an identity function.

Parameters:

Name	Type	Description
spec	Object	An object whose values (may) be transform functions

Returns:

Object -

The input object with only the props that are functions retained

removeAndShape(spec, input) → {Object}

prune.js, line 81

Removes all the props you name in your spec. If you provided a transform function however, it is applied at the prop-level and that prop is (obviously) NOT removed but rather transformed accordingly. It is expected (best practice, for conveying intent) that you give a value of true for props you want to remove (a zipped object - where key and value are both strings of the same name - makes sense too). In this mode, if you provide any other type of value it won't be used in the spec.

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or (preferrably) a value of true to signal a value to be remove from the output
input	Object	An object which will be passed through the pruning/re-shaping defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it and name props shaved off the output

removeMagicProps(spec) → {Object}

util.js, line 120

Removes the reserved "shapey*" prefixed props from a spec.

Parameters:

Name	Type	Description
spec	Object	A shapey spec to be pruned of magic props

Returns:

Object -

A shapey spec cleaned of magic props

remover(spec, input) → {Object}

prune.js, line 59

Removes the props you name in your spec. It is expected (best practice, for conveying intent) that you give a value of true for props that you want to remove but not transform (a zipped object - where key and value are both strings of the same name - makes sense too).

Parameters:

Name	Type	Description
spec	Object	An object whose values are true or match the key name to signal a value to be removed from the output
input	Object	An object which will be passed through the pruning defined by the spec

Returns:

Object -

The input object with the named props shaved off the output

safeSpecTransforms(spec) → {Object}

util.js, line 203

Wraps every function on a given spec in a try/catch that catches any exception.

What it does with the exception is up to the consumer:

• ignores it (if "shapeyDebug" isn't set)
• logs it along with the corresponding field name, using console.error (if "shapeyDebug" is set to true)
• uses a custom handler supplied by the consumer as the value for "shapeyDebug"

Note that a custom error handler will be passed the following params (in order):

• The exception
• The field name
• The value that was fed into the transform function

Parameters:

Name	Type	Description
spec	Object	An object whose values may be transform functions that need to be wrapped in try/catch

Returns:

Object -

The same spec object but whose functions are safely wrapped in in try/catch handlers

shapeline(transforms, input) → {*}

shape.js, line 174

Applies a list of functions (in sequence) to a single input, passing the transformed output as the input value to the next function in the chain. If a spec object is included in the transforms, the shaper that corresponds to the "shapeyMode" prop is invoked (otherwise shapeLoosely() is used). This creates a transform function for the pipeline.

Parameters:

Name	Type	Description
transforms	Array.<function()>	A list of transform functions
input	*	The input value to pass through the enhancer pipeline

Returns:

* -

The output of the original input passed through the chain of transform functions

shapeLoosely(spec, input) → {Object}

shape.js, line 87

This function allows one to blend an object with a clone that is taken through prop transformations. Unlike object mappers/transformers, not every value in the spec need be a function. Non-function values are simply added to the result. If a given value in the spec IS a function however, it will be used to transform OR to create a prop. If the prop specified on the spec exists on the value (object) being mapped, a prop-level transform will be perform (just like Ramda's evolve()). But if a prop in the spec doesn't exist in the object and if that prop is a transformer function, then the transformer will be used to create that prop on the resulting object BUT the entire object will be passed into the transform function (just like Ramda's applySpec(), rather than just a single prop.

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or pass-through values to be added to the return object
input	Object	An object which will be passed through the re-shaping transform functions defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it

shapeStrictly(spec, input) → {Object}

shape.js, line 99

Applies a shaping spec to an input object, but will NOT pass through any props unless they are named in the spec. In other words, you're providing it template for creating a brand new object from some raw input.

Parameters:

Name	Type	Description
spec	Object	An object whose values are either transform functions or pass-through values to be added to the return object
input	Object	An object which will be passed through the re-shaping transform functions defined by the spec

Returns:

Object -

The input object with the spec transforms applied to it

wrapperForTheirErrorHandler(errHandler, fieldName, value, exception) → {*}

util.js, line 178

A wrapper around an (optional) error handler that the may be passed in as the "shapeyDebug" value. It is curried, but will feed their handler a more standard signature of: (err, field, value)

Parameters:

Name	Type	Description
errHandler	function	The custom error handler provided by the consumer
fieldName	String	The field name for the failed transform function
value	Object	The value that was fed into the transform function
exception	Object	The exception thrown by the failed transform

Returns:

* -

Could be anything, or nothing (it's up to the consumer)