Functions to mix, filter, change and copy/clone objects
JavaScript CSS Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist
doc
test
.gitignore
.travis.yml
Gruntfile.js
History.md
Makefile
README.md
bower.json
component.json
index.js
jsdoc-conf.json
package.json

README.md

mixing

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

NPM version Build Status Built with Grunt

Installation

Node

npm install mixing

Ringo

ringo-admin install gamtiq/mixing

Bower

bower install mixing

JSPM

jspm install mixing

AMD, script tag

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

Usage

Node, Ringo, JSPM

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

Duo

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

JSPM

System.import("mixing").then(function(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 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}

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"}

// Mix arrays
mixing([1, 2, 3], ["a", "b", "c", "d"], {overwrite: true, oneSource: true});   // Returns ["a", "b", "c", "d"]
mixing([3, 2, 1, 4, 5], [1, 2, 3], {overwrite: true, oneSource: true});   // Returns [1, 2, 3, 4, 5]

// 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}

// 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: ...}

API

See doc directory 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 - Should a field/function be overwritten when it exists in the destination 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?
  • 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.

.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).

.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: ""});

Related projects

Licence

MIT