mixing
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    mixing

    Functions to mix, filter, change and copy/clone objects. Supports processing of symbol property keys that are introduced in ECMAScript 2015.

    mixing is like an improved version of Object.assign and is compatible with ECMAScript 3+.

    Features

    • Overwrite all or only some fields, or do not change existent fields (specified by overwrite setting).
    • Mix recursively objects and arrays (use recursive and mixArray settings).
    • Copy only own or all fields of a source object (ownProperty setting).
    • Selectively copy fields from a source object (copy, except and filter settings).
    • Rename fields of a source object that are added into the target object (otherName setting).
    • Change values that are copied into the target object (change setting).
    • Several helpful "shortcut" functions that can be used standalone or as methods.
    const obj = {a: 1, b: {c: "", d: false}, e: [{f1: 1, f2: 2}, {f1: 0, f3: 9}], z: true};
    ...
    mixing(
        obj,
        {a: 3, b: {c: 1, c2: "abc"}, e: [{f2: -3}, {f1: 7, f2: null}, {f1: 10}], x: "way"},
        {overwrite: true, recursive: true, mixArray: true}
    );
    // obj is {a: 3, b: {c: 1, d: false, c2: "abc"}, e: [{f1: 1, f2: -3}, {f1: 7, f3: 9, f2: null}, {f1: 10}], x: "way", z: true}

    NPM version Build Status Built with Grunt

    Installation

    Node

    npm install mixing
    

    Ringo

    ringo-admin install gamtiq/mixing
    

    Bower

    bower install mixing
    

    AMD, script tag

    Use dist/mixing.js or dist/mixing.min.js (minified version).

    Usage

    Node, Ringo

    var mixing = require("mixing");
    ...

    AMD

    define(["path/to/dist/mixing.js"], function(mixing) {
        ...
    });

    Bower, script tag

    <!-- Use bower_components/mixing/dist/mixing.js if the library was installed via Bower -->
    <script type="text/javascript" src="path/to/dist/mixing.js"></script>
    <script type="text/javascript">
        // mixing is available via mixing field of window object
        ...
    </script>

    Examples

    var source = {a: 1, b: 2};
    var copy = mixing.copy(source);   // Make a shallow copy of source
    var result = mixing({a: 1, b: 2}, {c: 3, d: 4});   // result is {a: 1, b: 2, c: 3, d: 4}
    mixing({a: 1, b: 2}, {a: "a", b: {}, c: 3, d: 4});   // Returns {a: 1, b: 2, c: 3, d: 4}
    mixing(
        {a: 1, b: 2, z: 100},
        {a: "a", b: {}, c: 3, d: 4},
        {overwrite: true}
    );   // Returns {a: "a", b: {}, c: 3, d: 4, z: 100}
    // Overwrite only fields whose names are matching regular expression
    mixing(
        {a: 1, b: 2, alfa: "omega", delta: "gamma", z: 100},
        {a: "a", b: {c: true}, d: 4, delta: 3, z: false},
        {overwrite: /^[a-c]$/}
    );   // Returns {a: "a", alfa: "omega", b: {c: true}, d: 4, delta: "gamma", z: 100}
    // Recursive mix
    mixing(
        {a: 1, b: {c: "", d: false}, e: [{f1: 1, f2: 2}, {f1: 0, f3: 9}], z: true},
        {a: 3, b: {c: 1, c2: "abc"}, e: [{f2: -3}, {f1: 7, f2: null}, {f1: 10}], x: "way"},
        {overwrite: true, recursive: true, mixArray: true}
    );   // Returns {a: 3, b: {c: 1, d: false, c2: "abc"}, e: [{f1: 1, f2: -3}, {f1: 7, f3: 9, f2: null}, {f1: 10}], x: "way", z: true}
    
    mixing(
        {a: 1, b: 2, c: "", d: false},
        {a: -1, b: null, c: true, d: "empty"},
        {overwrite: true, except: {a: false, b: true, c: null, d: "yes"}}
    );   // Returns {a: -1, b: 2, c: true, d: false}
    mixing(
        {a: 1, b: 2},
        {a3: 3, b: null, c4: "e5", d_97: new Date(), c: 3, "e-2": "empty"},
        {except: /\d/}
    );   // Returns {a: 1, b: 2, c: 3}
    mixing.copy(
        {a: 1, a2: 2, a3: "a3", b: 4, copy5: 5, d: "delta", e: "-123"},
        {except: /a/, filter: /\W/}
    );   // Returns {e: "-123"}
    mixing(
        {x: 5},
        {a: 1, a2: "2man", a3: "a3", b: 4, copy5: 5, delta: "plus", e: 4},
        {copy: /a/, filter: /^\D/}
    );   // Returns {x: 5, a3: "a3", delta: "plus"}
    mixing.assign(
        {a: "start"},
        {a: 1, b: 0},
        {b: 2, c: 3, d: 4},
        null,
        {e: "end"}
    );   // Returns {a: 1, b: 2, c: 3, d: 4, e: "end"}
    
    // Change default settings
    mixing.setSettings({overwrite: true, oneSource: true});
    // Mix arrays
    mixing([1, 2, 3], ["a", "b", "c", "d"]);   // Returns ["a", "b", "c", "d"]
    mixing([3, 2, 1, 4, 5], [1, 2, 3]);   // Returns [1, 2, 3, 4, 5]
    // Get redefined default settings
    mixing.getSettings();   // Returns {overwrite: true, oneSource: true}
    // Reset default settings to initial values
    mixing.setSettings();
    
    // Filter and change field values
    mixing({}, 
           [{a: 1, b: 100}, null, {c: 3, d: new Date(), e: 4}, {f: "str", g: 50}, undefined, {h: 7}], 
           {
               except: ["a", "g"],
               filter: function(data) {
                   var value = data.value;
                   return typeof value === "number" && value < 10;
               },
               change: function(data) {
                   var value = data.value;
                   return value > 5 ? value * value : value;
               }
           });   // Returns {c: 3, e: 4, h: 49}
    
    mixing.change(
        {a: 1, b: "abc", c: null, d: 4444, e: false},
        {b: 22, c: 333, e: 55555}
    );   // Returns {a: 1, b: 22, c: 333, d:4444, e: 55555}
    
    // Change items in array
    mixing.mixToItems(
        [{a: 1, b: 2}, {b: 3}, 83, {}],
        {a: null, c: 9}
    );   // Returns [{a: 1, b: 2, c: 9}, {a: null, b: 3, c: 9}, 83, {a: null, c: 9}]
    mixing.mixToItems(
        [null, {a: 1, b: 2}, {b: 3, z: 0}, {}],
        {a: null, b: false},
        {overwrite: true}
    );   // Returns [null, {a: null, b: false}, {a: null, b: false, z: 0}, {a: null, b: false}]
    
    // Clone, filter, map, update
    var obj = {
        a: 1,
        b: 2,
        clone: mixing.clone,
        filter: mixing.filter,
        map: mixing.map,
        update: mixing.update
    };
    obj[Symbol("field")] = Symbol("value");
    var obj2 = obj.clone();   // obj2 is a shallow copy of obj (contains symbol property key)
    
    function isNumericValue(data) {
        return typeof data.value === "number";
    }
    
    var obj3 = obj.filter(isNumericValue);   // {a: 1, b: 2}
    
    var obj4 = obj.map({
        filter: isNumericValue,
        change: function(data) {
            return data.value + data.value;
        }
    });   // {a: 2, b: 4}
    
    obj.update(function(data) {
        var value = data.value;
        return typeof value === "number"
                    ? ++value
                    : value;
    });   // obj is {a: 2, b: 3, clone: ...}

    See additional examples in tests.

    API

    See docs for details.

    mixing(destination: Object, source: Array | Object, [settings: Object]);

    Copy/add all fields and functions from source object(s) into the destination object. As a result the destination object may be modified.

    Several settings are supported (see doc/module-mixing.html for details):

    • copyFunc: Boolean - Should functions be copied?
    • funcToProto: Boolean - Should functions be copied into prototype of the destination object's constructor?
    • processSymbol: Boolean - Should symbol property keys be processed?
    • overwrite: Boolean | Function | RegExp - Specifies whether a field/function should be overwritten when it exists in the target object.
    • recursive: Boolean - Should this function be called recursively when field's value of the destination and source object is an object?
    • mixFromArray: Boolean - Should in recursive mode contents of a field of the source object be copied when the field's value is an array?
    • mixToArray: Boolean - Should in recursive mode 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?
    • mixArray: Boolean - Default value for mixFromArray and mixToArray settings.
    • oneSource: Boolean - Should source array be interpreted directly as copied object instead of list of source objects?
    • ownProperty: Boolean - Should only own properties of the source object be copied into the target object?
    • copy: Array | Object | RegExp | String | Symbol - Array, object, regular expression or string/symbol that defines names of fields/functions that should be copied.
    • except: Array | Object | RegExp | String | Symbol - Array, object, regular expression or string/symbol that defines names of fields/functions that shouldn't be copied.
    • filter: Function | RegExp - Function or regular expression that can be used to select elements that should be copied.
    • otherName: Object - Defines "renaming table" for copied elements.
    • change: Function | Object - Function or object that gives ability to change values that should be copied.

    .assign(destination: Object, ...source: Object);

    Copy values of all of the own properties from one or more source objects to the target object (similar to Object.assign).

    .change(source: Array | Object, change: Function | Object);

    Change values of fields of given object.

    .copy(source: Array | Object, [settings: Object]);

    Make a copy of source object(s).

    .mixToItems(destinationList: Array, source: Array | Object, [settings: Object]);

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

    .clone([settings: Object]);

    Make a copy of this object. This function can be transferred to an object to use as a method. For example:

    SomeClass.prototype.clone = mixing.clone;
    ...
    var obj = new SomeClass();
    ...
    var copy = obj.clone();

    .filter(filter: Function | Object);

    Filter this object. This function can be transferred to an object to use as a method. For example:

    SomeClass.prototype.filter = mixing.filter;
    ...
    var obj = new SomeClass();
    ...
    var result = obj.filter(function(data) {
        // data.source is obj, data.target is result
        ...
    });

    .map(change: Function | Object);

    Copy and change values of fields of this object. This function can be transferred to an object to use as a method. For example:

    SomeClass.prototype.map = mixing.map;
    ...
    var obj = new SomeClass();
    ...
    var result = obj.map(function(data) {
        // data.source is obj, data.target is result
        ...
    });

    .mix(source: Array | Object, [settings: Object]);

    Copy/add all fields and functions from source objects into this object. As a result this object may be modified. This function can be transferred to an object to use as a method. For example:

    SomeClass.prototype.mix = mixing.mix;
    ...
    var obj = new SomeClass();
    ...
    obj.mix([obj1, obj2]);

    .update(change: Function | Object);

    Change values of fields of this object. This function can be transferred to an object to use as a method. For example:

    SomeClass.prototype.update = mixing.update;
    ...
    var obj = new SomeClass();
    ...
    obj.update({a: 2, b: ""});

    .getSettings();

    Return default settings that were set earlier.

    .setSettings([settings: Object]);

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

    Related projects

    Licence

    MIT

    Install

    npm i mixing

    DownloadsWeekly Downloads

    62

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    5.12 MB

    Total Files

    64

    Last publish

    Collaborators

    • gamtiq