mergee - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

index.js

@@ -10,3 +10,14 @@ /**
 var util = require('./lib/util');
+
 var deepEqual = require('./lib/deepequal');
+/**
+ * deep comparison of `actual` and `expected`
+ *
+ * @see https://github.com/joyent/node/blob/v0.12.0-release/lib/assert.js
+ *
+ * @function deepEqual
+ * @param {Any} actual
+ * @param {Any} expected
+ * @return {Boolean} true if `actual` equals `expected`
+ */
 exports.deepEqual = deepEqual;
@@ -16,2 +27,14 @@
  * check if an object `obj` contains circular structures
+ *
+ * #### Example
+ *
+ * ````js
+ * var isCircular  = require('mergee').isCircular,
+ *     obj = { a: {} };
+ * obj.a.c = { c: 1 };
+ * // isCircular(obj) === true
+ * ````
+ *
+ * @param {Object} obj - Object to check
+ * @return {Boolean} true if `obj` contains circularities
  */
@@ -24,3 +47,4 @@ function isCircular (obj) {
 /**
- * @private
+ * recursive helper function
+ * @api private
  */
@@ -44,5 +68,17 @@ function _checkCircular(opts, obj) {
 /**
- * extend object `target` with multiple other objects
- * @param {Object} target
- * @param {Any} arguments 1 ... n
+ * extend object `target` with multiple `source` objects
+ *
+ * #### Example
+ *
+ * ````js
+ * var extend  = require('mergee').extend,
+ *     target  = { a:{A:1}, b:{A:1} },
+ *     source1 = { b:{B:2}, c:{B:2} },
+ *     source2 = { d:{C:3} };
+ * extend(target, source1, source2);
+ * // target === { a:{A:1}, b:{B:2}, c:{B:2}, d:{C:3} };
+ * ````
+ *
+ * @param {Object|Array|Function} target
+ * @param {Any} source - arguments 2 ... n
  * @return {Object} extended target
@@ -69,4 +105,16 @@ */
  * merge multiple objects into `target`
- * @param {Object|Function|Array} target
- * @param {Any} arguments 1 ... n
+ *
+ * #### Example
+ *
+ * ````js
+ * var merge = require('mergee').merge,
+ *     target  = { t: 1, x: { y: 'z' } },
+ *     source1 = { t: { s1: /source1/ } },
+ *     source2 = { t: { s2: new Date(100), x: null } };
+ * merge(target, source1, source2);
+ * // target === { t: { s1: /source1/, s2: Wed Dec 31 1969 17:00:00 GMT-0700 (MST) }, x: null }
+ * ````
+ *
+ * @param {Object|Function|Array} target - target object
+ * @param {Any} source - arguments 2 ... n
  * @return {Object} merged target
@@ -84,4 +132,19 @@ */
  *
- * ignoreNull: true,		// treat source === null as undefined - target does not get deleted
- * ignoreCircular: true,	// ignore cirular structures - no error gets thrown
+ * #### Example
+ *
+ * ````js
+ * var merge = require('mergee').merge,
+ *     target  = { t: 1, x: { y: 'z' } },
+ *     source1 = { t: { s1: /source1/ } },
+ *     source2 = { t: { s2: new Date(100), x: null } };
+ * mergeExt({ ignoreNull: true }, target, source1, source2);
+ * // target === { t: { s1: /source1/, s2: Wed Dec 31 1969 17:00:00 GMT-0700 (MST) }, x: { y: 'z' } }
+ * ````
+ *
+ * @param {Object} opts - options
+ * @param {Boolean} opts.ignoreNull - treat `source === null` as undefined - target does not get deleted
+ * @param {Boolean} opts.ignoreCircular - ignore cirular structures - no error gets thrown
+ * @param {Object|Function|Array} target - target object
+ * @param {Any} source - arguments 3 ... n
+ * @return {Object} merged target
  */
@@ -104,3 +167,5 @@ function mergeExt (opts, target) {
 /**
- * @private
+ * recursive merge helper
+ *
+ * @api private
  * @param {Object} opts
@@ -237,3 +302,15 @@ * @param {Any} target
  * perform a deep clone of `obj`
- * @param {Object|Array} obj
+ *
+ * #### Example
+ *
+ * ```js
+ * var clone = require('mergee').clone,
+ *     obj = { a: { b: { c: 1 } } };
+ * var cloned = clone(obj);
+ * // (cloned !== obj)
+ * // (cloned.a !== obj.a)
+ * // (cloned.a.b !== obj.a.b)
+ * ```
+ *
+ * @param {Object|Array} obj - object to get cloned
  * @return {Object|Array} deep cloned object
@@ -277,3 +354,16 @@ */
  * pick properties from `obj` into a new object
- * @param {Object} obj
+ *
+ * #### Example
+ *
+ * ```js
+ * var r,
+ *     pick = require('mergee').pick,
+ *     obj = { a:1, b:2, c:3, d:4 };
+ * r = pick(o, ['a', 'd']);
+ * // r = { a:1, d: 4 }
+ * r = pick(o, 'a,d');
+ * // r = { a:1, d: 4 }
+ * ```
+ *
+ * @param {Object} obj - object to pick properties from
  * @param {Array|String} keys - Array of properties or comma separated string of properties
@@ -301,3 +391,16 @@ * @return {Object} object with picked properties
  * omit properties from `obj` into a new object
- * @param {Object} obj
+ *
+ * #### Example
+ *
+ * ```js
+ * var r,
+ *     omit = require('mergee').omit,
+ *     obj = { a:1, b:2, c:3, d:4 };
+ * r = omit(o, ['a', 'd']);
+ * // r = { b:2, c: 3 }
+ * r = omit(o, 'a,d');
+ * // r = { b:2, c: 3 }
+ * ```
+ *
+ * @param {Object} obj - object
  * @param {Array|String} keys - Array of properties or comma separated string of properties
@@ -325,3 +428,18 @@ * @return {Object} object with omitted properties
  * select properties from `obj`
- * @param {Object} obj
+ *
+ * #### Example
+ *
+ * ```js
+ * var r,
+ *     select = require('mergee').select,
+ *     obj = { a: { b: { c: 1 } } };
+ * r = select(obj, [a, b, c]);
+ * // r = 1
+ * r = select(obj, 'a.b.c');
+ * // r = 1
+ * r = select(obj, 'there.is.no.such.property'); // this will not throw!
+ * // r = undefined
+ * ```
+ *
+ * @param {Object} obj - object to select from
  * @param {Array|String} keys - Array of properties or dot separated string of properties
@@ -328,0 +446,0 @@ * @return {Object} selected object

package.json

 {
   "name": "mergee",
   "description": "Utilities for objects",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "index.js",
@@ -24,3 +24,3 @@ "engines": {
     "lint": "jshint --show-non-errors *.js */*.js",
-    "doc": "jsdoc -d doc -c jsdoc.json index.js lib/*.js",
+    "doc": "mkdir -p doc && jsdox -o doc index.js",
     "clean": "rm -rf doc coverage"
@@ -27,0 +27,0 @@ },

README.md

@@ -14,6 +14,7 @@ # mergee
 * clone - deep clone of an object or array.
-* isCircular - check object for circular structures
 * pick - pick properties from an object
 * omit - omit properties from an object
 * select - select properties from an object
+* isCircular - check object for circular structures
+* deepEqual - deep comparison
 
@@ -30,6 +31,226 @@ ## Table of Contents
 
-## Description
+## Methods
 
-TODO - detailed description missing ...
 
+### extend(target, source)
+
+extend object `target` with multiple `source` objects
+
+#### Example
+
+````js
+var extend  = require('mergee').extend,
+    target  = { a:{A:1}, b:{A:1} },
+    source1 = { b:{B:2}, c:{B:2} },
+    source2 = { d:{C:3} };
+extend(target, source1, source2);
+// target === { a:{A:1}, b:{B:2}, c:{B:2}, d:{C:3} };
+````
+
+**Parameters**
+
+**target**: `Object | Array | function`, extend object `target` with multiple `source` objects
+
+#### Example
+
+````js
+var extend  = require('mergee').extend,
+    target  = { a:{A:1}, b:{A:1} },
+    source1 = { b:{B:2}, c:{B:2} },
+    source2 = { d:{C:3} };
+extend(target, source1, source2);
+// target === { a:{A:1}, b:{B:2}, c:{B:2}, d:{C:3} };
+````
+
+**source**: `Any`, arguments 2 ... n
+
+**Returns**: `Object`, extended target
+
+
+### merge(target, source)
+
+merge multiple objects into `target`
+
+#### Example
+
+````js
+var merge = require('mergee').merge,
+    target  = { t: 1, x: { y: 'z' } },
+    source1 = { t: { s1: /source1/ } },
+    source2 = { t: { s2: new Date(100), x: null } };
+merge(target, source1, source2);
+// target === { t: { s1: /source1/, s2: Wed Dec 31 1969 17:00:00 GMT-0700 (MST) }, x: null }
+````
+
+**Parameters**
+
+**target**: `Object | function | Array`, target object
+
+**source**: `Any`, arguments 2 ... n
+
+**Returns**: `Object`, merged target
+
+
+### mergeExt(opts, opts.ignoreNull, opts.ignoreCircular, target, source)
+
+extended merge
+
+#### Example
+
+````js
+var merge = require('mergee').merge,
+    target  = { t: 1, x: { y: 'z' } },
+    source1 = { t: { s1: /source1/ } },
+    source2 = { t: { s2: new Date(100), x: null } };
+mergeExt({ ignoreNull: true }, target, source1, source2);
+// target === { t: { s1: /source1/, s2: Wed Dec 31 1969 17:00:00 GMT-0700 (MST) }, x: { y: 'z' } }
+````
+
+**Parameters**
+
+**opts**: `Object`, options
+
+**opts.ignoreNull**: `Boolean`, treat `source === null` as undefined - target does not get deleted
+
+**opts.ignoreCircular**: `Boolean`, ignore cirular structures - no error gets thrown
+
+**target**: `Object | function | Array`, target object
+
+**source**: `Any`, arguments 3 ... n
+
+**Returns**: `Object`, merged target
+
+
+### clone(obj)
+
+perform a deep clone of `obj`
+
+#### Example
+
+```js
+var clone = require('mergee').clone,
+    obj = { a: { b: { c: 1 } } };
+var cloned = clone(obj);
+// (cloned !== obj)
+// (cloned.a !== obj.a)
+// (cloned.a.b !== obj.a.b)
+```
+
+**Parameters**
+
+**obj**: `Object | Array`, object to get cloned
+
+**Returns**: `Object | Array`, deep cloned object
+
+
+### pick(obj, keys)
+
+pick properties from `obj` into a new object
+
+#### Example
+
+```js
+var r,
+    pick = require('mergee').pick,
+    obj = { a:1, b:2, c:3, d:4 };
+r = pick(o, ['a', 'd']);
+// r = { a:1, d: 4 }
+r = pick(o, 'a,d');
+// r = { a:1, d: 4 }
+```
+
+**Parameters**
+
+**obj**: `Object`, object to pick properties from
+
+**keys**: `Array | String`, Array of properties or comma separated string of properties
+
+**Returns**: `Object`, object with picked properties
+
+
+### omit(obj, keys)
+
+omit properties from `obj` into a new object
+
+#### Example
+
+```js
+var r,
+    omit = require('mergee').omit,
+    obj = { a:1, b:2, c:3, d:4 };
+r = omit(o, ['a', 'd']);
+// r = { b:2, c: 3 }
+r = omit(o, 'a,d');
+// r = { b:2, c: 3 }
+```
+
+**Parameters**
+
+**obj**: `Object`, object
+
+**keys**: `Array | String`, Array of properties or comma separated string of properties
+
+**Returns**: `Object`, object with omitted properties
+
+
+### select(obj, keys)
+
+select properties from `obj`
+
+#### Example
+
+```js
+var r,
+    select = require('mergee').select,
+    obj = { a: { b: { c: 1 } } };
+r = select(obj, [a, b, c]);
+// r = 1
+r = select(obj, 'a.b.c');
+// r = 1
+r = select(obj, 'there.is.no.such.property'); // this will not throw!
+// r = undefined
+```
+
+**Parameters**
+
+**obj**: `Object`, object to select from
+
+**keys**: `Array | String`, Array of properties or dot separated string of properties
+
+**Returns**: `Object`, selected object
+
+
+### isCircular(obj)
+
+check if an object `obj` contains circular structures
+
+#### Example
+
+````js
+var isCircular  = require('mergee').isCircular,
+    obj = { a: {} };
+obj.a.c = { c: 1 };
+// isCircular(obj) === true
+````
+
+**Parameters**
+
+**obj**: `Object`, Object to check
+
+**Returns**: `Boolean`, true if `obj` contains circularities
+
+
+### deepEqual(actual, expected)
+
+deep comparison of `actual` and `expected`
+
+**Parameters**
+
+**actual**: `Any`, deep comparison of `actual` and `expected`
+
+**expected**: `Any`, deep comparison of `actual` and `expected`
+
+**Returns**: `Boolean`, true if `actual` equals `expected`
+
+
 ## Contribution and License Agreement
@@ -44,2 +265,7 @@
 
+This module contains code from other MIT licensed sources:
+
+* `lib/deepequal.js` is from [node v0.12 assert.js](https://github.com/joyent/node/blob/v0.12.0-release/lib/assert.js) - MIT licensed
+* `lib/util.js` is from [node v0.12 util.js](https://github.com/joyent/node/blob/v0.12.0-release/lib/util.js) - MIT licensed
+
 Copyright (c) 2015 commenthol (MIT License)
@@ -46,0 +272,0 @@

test/index.mocha.js

@@ -302,2 +302,12 @@ 'use strict';
 
+	it('merging sample', function(){
+		var target  = { t: 1, x: { y: 'z' } },
+			source1 = { t: { s1: /source1/ }, x: null },
+			source2 = { t: { s2: new Date(100) } };
+
+		var res = M.merge(target, source1, source2);
+		var exp = { t: { s1: /source1/, s2: new Date(100) }, x: null };
+		assert.deepEqual(res, exp);
+	});
+
 });
@@ -335,2 +345,14 @@
 	});
+
+	it('merging sample', function(){
+		var target  = { t: 1, x: { y: 'z' } },
+			source1 = { t: { s1: /source1/ }, x: null },
+			source2 = { t: { s2: new Date(100) } };
+
+		var res = M.mergeExt({ ignoreNull: true }, target, source1, source2);
+		var exp = { t: { s1: /source1/, s2: new Date(100) }, x: { y: 'z' } };
+		//~ console.log(res)
+		assert.deepEqual(res, exp);
+	});
+
 });
@@ -356,2 +378,10 @@
 	});
+	it('clone sample', function(){
+		var obj = { a: { b: { c: 1 } } };
+		var cloned = M.clone(obj);
+		assert.ok(cloned !== obj)
+		assert.ok(cloned.a !== obj.a)
+		assert.ok(cloned.a.b !== obj.a.b)
+	});
+
 });
@@ -524,2 +554,13 @@
 	});
+	it('try select from undefined property', function(){
+		var obj = {
+			test: {
+				test: 0,
+				test2: { b: 2 }
+			}
+		};
+		var res = M.select(obj, 'there.is.no.such.prop' );
+
+		assert.deepEqual(res, undefined);
+	});
 });
@@ -526,0 +567,0 @@

No alert changes

Improved metrics

Total package byte prevSize

40041

increased by28.42%

Lines of code

1157

increased by15.01%

Number of lines in readme file

278

increased by434.62%

No dependency changes