mixing

Module: mixing

(require("mixing"))(destination, source [, settings])

Copy/add all fields and functions from source objects into the target object. As a result the target object may be modified.

Parameters:
Name Type Argument Description
destination Object | function

The target object into which fields and functions will be copied.
source Array | Object

Array of source objects or just one object whose contents will be copied. If a source is a falsy value (e.g. null or undefined), the source will be skipped.
settings Object <optional>

Operation settings. Fields are names of settings, their values are the corresponding values of settings. The following settings are being supported.

NameTypeDefault valueDescription
copyFunc Boolean true Should functions be copied?
funcToProto Boolean false Should functions be copied into prototype of the target object's constructor (i.e. into destination.constructor.prototype)?
If false then functions will be copied directly into the target object.
processSymbol Boolean true Should symbol property keys (i.e. fields whose name is a symbol) be processed?
overwrite Boolean | Function | RegExp false Specifies whether a field/function should be overwritten when it exists in the target object.
If true then any existent field will be overwritten in the target object.
Function or regular expression can be used to select fields that should be overwritten.
If a regular expression is passed, only those fields will be overwritten whose names are matching the regular expression.
If specified function returns true for a field, the field will be overwritten in the target object. An object with contextual data is passed into the function (see details below).
recursive Boolean false Should this function be called recursively when field's value of the target and source object is an object?
If true then object fields from the target and source objects will be mixed by using this function with the same settings.
This option has no dependency with overwrite setting and has priority over it.
mixFromArray Boolean false Should contents of a field of the source object be copied when the field's value is an array?
Will be used only when recursive setting has true value.
mixToArray Boolean false Should contents of a field of the source object be copied into a field of the target object when the latest field's value is an array?
Will be used only when recursive setting has true value.
mixArray Boolean false Sets default value for mixFromArray and mixToArray settings.
oneSource Boolean false Indicates that array that is passed as source parameter should be interpreted directly as copied object instead of list of source objects.
ownProperty Boolean false Should only own properties of the source object be copied in the target object?
copy Array | Object | RegExp | String | Symbol "" (empty string) Array, object, regular expression or string/symbol that defines names of fields/functions that should be copied.
If an object is passed then his fields determine copied elements. If a regular expression is passed, then field names matching the regular expression will be copied. If a string/symbol is passed then it is name of the only copied field.
except Array | Object | RegExp | String | Symbol "" (empty string) Array, object, regular expression or string/symbol that defines names of fields/functions that shouldn't be copied.
If an object is passed then his fields with true values determine non-copied elements. If a regular expression is passed, then field names matching the regular expression will not be copied. If a string/symbol is passed then it is name of the only non-copied field.
filter Function | RegExp null Function or regular expression that can be used to select elements that should be copied.
If regular expression is passed, only those fields will be copied whose values are matching regular expression.
If specified function returns true for a field, the field will be copied in the target object.
An object with contextual data is passed into function (see details below).
otherName Object null Defines "renaming table" for copied elements.
Fields of the table are names from a source object, values are the corresponding names in the target object.
For example, the call
mixing({}, {field: 1, func: "no-func"}, {otherName: {"field": "prop", "func": "method"}})
will return the following object
{prop: 1, method: "no-func"}
change Function | Object null Function or object that gives ability to change values that should be copied.
If an object is passed then his fields determine new values for copied elements.
If a function is passed then value returned by the function for a field will be copied into the target object instead of original field's value.
An object with contextual data is passed into function (see details below).
An object having the following fields is passed into overwrite, filter and change function:
  • field - field name
  • value - field value from the source object
  • targetValue - field value from the target object
  • target - reference to the target object
  • source - reference to the source object
Default values of settings can be redefined by setSettings method.
copy, except and filter settings can be used together. In such situation a field will be copied only when the field satisfies to all settings (i.e. belongs to copied elements, not in exceptions and conforms to filter).
Source:
Returns:

Modified target object.

Type
Object

Methods

<static> assign(destination, source)

Copy values of all of the own properties from one or more source objects to the target object (similar to Object.assign).
This function is a "wrap" for the following code: 

mixing(destination, Array.prototype.slice.call(arguments, 1), {overwrite: true, ownProperty: true});

Parameters:
Name Type Argument Description
destination Object | function

The target object into which fields and functions will be copied.
source Object <repeatable>

An object whose contents will be copied. If a source is a falsy value (e.g. null or undefined), the source will be skipped.
Source:
Returns:

Modified target object.

Type
Object

<static> change(source, change)

Change values of fields of given object.
This function is a "wrap" for the following code: 

mixing(source, source, {change: change, overwrite: true, oneSource: true});

Parameters:
Name Type Description
source Array | Object

An array or an object whose fields should be modified.
change function | Object

A function or an object that specifies the modification. See mixing for details.
Source:
Returns:

Modified source object.

Type
Object

<static> clone( [settings])

Make a copy of this object.
This function is a "wrap" for the following code: 

var copy = mixing({}, this, settings);
It can be transferred to an object to use as a method.

Parameters:
Name Type Argument Description
settings Object <optional>

Operation settings. See mixing for details.
Source:
Returns:

Newly created object containing contents of this object.

Type
Object

<static> copy(source [, settings])

Make a copy of source object(s).
This function is a "wrap" for the following code: 

var copy = mixing({}, source, settings);

Parameters:
Name Type Argument Description
source Array | Object

Array of source objects or just one object whose contents will be copied.
settings Object <optional>

Operation settings. See mixing for details.
Source:
Returns:

Newly created object containing contents of source objects.

Type
Object

<static> filter(filter)

Filter this object.
This function is a "wrap" for the following code: 

var result = mixing({}, this, {filter: filter});
It can be transferred to an object to use as a method.

Parameters:
Name Type Description
filter function | Object

Filter function to select fields or object that represents operation settings including filter function. See mixing for details.
Source:
Returns:

Newly created object containing fields of this object for which filter function returns true.

Type
Object

<static> getSettings()

Return default settings that were set earlier.

Source:
Returns:

Default settings that were set earlier or undefined / null if default settings were not set.

Type
Object | undefined

<static> map(change)

Copy and change values of fields of this object.
This function is a "wrap" for the following code: 

var result = mixing({}, this, {change: change});
It can be transferred to an object to use as a method.

Parameters:
Name Type Description
change function | Object

Function to change values of copied fields or object that represents operation settings including change function. See mixing for details.
Source:
Returns:

Newly created object containing fields of this object with changed values.

Type
Object

<static> mix(source [, settings])

Copy/add all fields and functions from source objects into this object. As a result this object may be modified.
This function is a "wrap" for the following code: 

mixing(this, source, settings);
It can be transferred to an object to use as a method.

Parameters:
Name Type Argument Description
source Array | Object

Array of source objects or just one object whose contents will be copied.
settings Object <optional>

Operation settings. See mixing for details.
Source:
Returns:

Modified this object.

Type
Object

<static> mixToItems(destinationList, source [, settings])

Copy fields from source object(s) into every object item of given array.

Parameters:
Name Type Argument Description
destinationList Array

An array whose items should be modified.
source Array | Object

Array of source objects or just one object whose contents will be copied.
settings Object <optional>

Operation settings that will be applied to every copying. See mixing for details.
Source:
Returns:

Original destinationList with possibly modified object items.

Type
Array

<static> setSettings( [settings])

Set (redefine, reset) default settings that should be used for subsequent mixing calls.

Parameters:
Name Type Argument Description
settings Object | undefined <optional>

Default settings that should be used for subsequent mixing calls. Initial default values will be used for settings that are not specified in the passed object. Pass undefined, null, non-object or to call without parameter to reset default settings to initial values.
Source:

<static> update(change)

Change values of fields of this object.
This function is a "wrap" for the following code: 

mixing.change(this, change);
It can be transferred to an object to use as a method.

Parameters:
Name Type Description
change function | Object

A function or an object that specifies the modification. See mixing for details.
Source:
Returns:

Modified this object.

Type
Object