merge-options 0.0.42

package/index.js

@@ -0,0 +1,153 @@
+'use strict';
+var isOptionObject = require('is-plain-obj');
+var hasOwnProperty = Object.prototype.hasOwnProperty;
+var propIsEnumerable = Object.propertyIsEnumerable;
+var globalThis = this;
+var defaultMergeOpts = {
+	concatArrays: false
+};
+
+function getEnumerableOwnPropertyKeys(value) {
+	var keys = [];
+
+	for (var key in value) {
+		if (hasOwnProperty.call(value, key)) {
+			keys.push(key);
+		}
+	}
+
+	if (Object.getOwnPropertySymbols) {
+		var symbols = Object.getOwnPropertySymbols(value);
+
+		for (var i = 0; i < symbols.length; i++) {
+			if (propIsEnumerable.call(value, symbols[i])) {
+				keys.push(symbols[i]);
+			}
+		}
+	}
+
+	return keys;
+}
+
+function clone(value) {
+	if (Array.isArray(value)) {
+		return cloneArray(value);
+	}
+
+	if (isOptionObject(value)) {
+		return cloneOptionObject(value);
+	}
+
+	return value;
+}
+
+function cloneArray(array) {
+	var result = array.slice(0, 0);
+
+	getEnumerableOwnPropertyKeys(array).forEach(function (key) {
+		result[key] = clone(array[key]);
+	});
+
+	return result;
+}
+
+function cloneOptionObject(obj) {
+	var result = Object.getPrototypeOf(obj) === null ? Object.create(null) : {};
+
+	getEnumerableOwnPropertyKeys(obj).forEach(function (key) {
+		result[key] = clone(obj[key]);
+	});
+
+	return result;
+}
+
+/**
+ * @param merged {already cloned}
+ * @return {cloned Object}
+ */
+function mergeKeys(merged, source, keys, mergeOpts) {
+	keys.forEach(function (key) {
+		if (key in merged) {
+			merged[key] = merge(merged[key], source[key], mergeOpts);
+		} else {
+			merged[key] = clone(source[key]);
+		}
+	});
+
+	return merged;
+}
+
+/**
+ * @param merged {already cloned}
+ * @return {cloned Object}
+ *
+ * see [Array.prototype.concat ( ...arguments )](http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.concat)
+ */
+function concatArrays(merged, source, mergeOpts) {
+	var result = merged.slice(0, 0);
+	var resultIndex = 0;
+
+	[merged, source].forEach(function (array) {
+		var indices = [];
+
+		// result.concat(array) with cloning
+		for (var k = 0; k < array.length; k++) {
+			if (!hasOwnProperty.call(array, k)) {
+				continue;
+			}
+
+			indices.push(String(k));
+
+			if (array === merged) {
+				// already cloned
+				result[resultIndex++] = array[k];
+			} else {
+				result[resultIndex++] = clone(array[k]);
+			}
+		}
+
+		// merge non-index keys
+		result = mergeKeys(result, array, getEnumerableOwnPropertyKeys(array).filter(function (key) {
+			return indices.indexOf(key) === -1;
+		}), mergeOpts);
+	});
+
+	return result;
+}
+
+/**
+ * @param merged {already cloned}
+ * @return {cloned Object}
+ */
+function merge(merged, source, mergeOpts) {
+	if (mergeOpts.concatArrays && Array.isArray(merged) && Array.isArray(source)) {
+		return concatArrays(merged, source, mergeOpts);
+	}
+
+	if (!isOptionObject(source) || !isOptionObject(merged)) {
+		return clone(source);
+	}
+
+	return mergeKeys(merged, source, getEnumerableOwnPropertyKeys(source), mergeOpts);
+}
+
+module.exports = function () {
+	var mergeOpts = merge(clone(defaultMergeOpts), (this !== globalThis && this) || {}, defaultMergeOpts);
+	var merged = {};
+
+	for (var i = 0; i < arguments.length; i++) {
+		var option = arguments[i];
+
+		if (option === undefined) {
+			continue;
+		}
+
+		if (!isOptionObject(option)) {
+			throw new TypeError('`' + option + '` is not an Option Object');
+		}
+
+		merged = merge(merged, option, mergeOpts);
+	}
+
+	return merged;
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "merge-options",
+  "version": "0.0.42",
+  "description": "Merge Option Objects",
+  "license": "MIT",
+  "repository": "schnittstabil/merge-options",
+  "author": {
+    "name": "Michael Mayer",
+    "email": "michael@schnittstabil.de",
+    "url": "schnittstabil.de"
+  },
+  "engines": {
+    "node": ">=0.10.0"
+  },
+  "scripts": {
+    "test": "xo && nyc ava && nyc report --reporter=text",
+    "clean": "rimraf .nyc_output/ coverage/",
+    "coverage-html": "nyc ava && nyc report --reporter=html",
+    "coveralls": "nyc report --reporter=text-lcov | coveralls"
+  },
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "merge",
+    "options",
+    "deep",
+    "plain",
+    "object",
+    "extend",
+    "clone"
+  ],
+  "devDependencies": {
+    "ava": "*",
+    "coveralls": "^2.11.4",
+    "nyc": "^3.2.2",
+    "rimraf": "^2.4.3",
+    "xo": "*"
+  },
+  "dependencies": {
+    "is-plain-obj": "^1.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,96 @@
+# merge-options [![Build Status](https://travis-ci.org/schnittstabil/merge-options.svg?branch=master)](https://travis-ci.org/schnittstabil/merge-options) [![Coverage Status](https://coveralls.io/repos/schnittstabil/merge-options/badge.svg?branch=master&service=github)](https://coveralls.io/github/schnittstabil/merge-options?branch=master)
+
+> Merge Option Objects
+
+`merge-options` considers [plain objects](https://github.com/sindresorhus/is-plain-obj) as *Option Objects*, everything else as *Option Values*.
+
+## Install
+
+```
+$ npm install --save merge-options
+```
+
+## Usage
+
+```js
+const mergeOptions = require('merge-options');
+
+mergeOptions({foo: 0}, {bar: 1}, {baz: 2}, {bar: 3})
+//=> {foo: 0, bar: 3, baz: 2}
+
+mergeOptions({nested: {unicorns: 'none'}}, {nested: {unicorns: 'many'}})
+//=> {nested: {unicorns: 'many'}}
+
+mergeOptions({[Symbol.for('key')]: 0}, {[Symbol.for('key')]: 42})
+//=> {Symbol(key): 42}
+```
+
+## API
+
+### mergeOptions(option1, ...options)<br/>mergeOptions.call(config, option1, ...options)
+
+`mergeOptions` recursively merges one or more *Option Objects* into a new one and returns that. The `options` are merged in order, thus *Option Values* of additional `options` take precedence over previous ones.
+
+The merging does not alter the passed `option` arguments, taking roughly the following steps:
+* recursively cloning<sup><a href="#note1">[1]</a></sup> *Option Objects* and [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) until reaching *Option Values*
+* copying<sup><a href="#note1">[1]</a></sup> references to *Option Values* to the result object
+
+
+```js
+const defaultOpts = {
+	fn:      () => false,                  // functions are Option Values
+	promise: Promise.reject(new Error()),  // all non-plain objects are Option Values
+	array:   ['foo'],                      // arrays are Option Values
+	nested:  {unicorns: 'none'}            // {…} is plain, therefore an Option Object
+};
+
+const opts = {
+	fn:      () => true,                   // [1]
+	promise: Promise.resolve('bar'),       // [2]
+	array:   ['baz'],                      // [3]
+	nested:  {unicorns: 'many'}            // [4]
+};
+
+mergeOptions(defaultOpts, opts)
+//=>
+{
+	fn:      [Function],                   // === [1]
+	promise: Promise { 'bar' },            // === [2]
+	array:   ['baz'],                      // !== [3] (arrays are cloned)
+	nested:  {unicorns: 'many'}            // !== [4] (Option Objects are cloned)
+}
+```
+
+#### config
+
+Type: `object`
+
+##### config.concatArrays
+
+Type: `boolean`<br/>Default: `false`
+
+Concatenate arrays:
+
+```js
+mergeOptions({src: ['src/**']}, {src: ['test/**']})
+//=> {src: ['test/**']}
+
+mergeOptions.call({concatArrays: true}, {src: ['src/**']}, {src: ['test/**']})
+//=> {src: ['src/**', 'test/**']}
+```
+
+
+## Related
+
+* See [object-assign](https://github.com/sindresorhus/object-assign) if you need a ES2015 Object.assign() ponyfill
+* See [deep-assign](https://github.com/sindresorhus/deep-assign) if you need to do Object.assign() recursively
+
+## Notes
+
+<ol>
+	<li id="note1">copying and cloning take only enumerable own properties into account</li>
+</ol>
+
+## License
+
+MIT © [Michael Mayer](http://schnittstabil.de)