\n\n# copy-props\n\n[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]\n\nCopy properties between two objects deeply.\n\n## Install\n\nTo install from npm:\n\n```sh\n$ npm i copy-props --save\n```\n\n## Usage\n\nCopy _src_ to _dst_ simply (and return _dst_) :\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { b1: 'bbb' }, c: 'ccc' };\nvar dst = { a: 2, b: { b1: 'xxx', b2: 'yyy' } };\n\ncopyProps(src, dst);\n// => { a: 1, b: { b1: 'bbb', b2: 'yyy' }, c: 'ccc' }\n```\n\nCopy _src_ to _dst_ with property mapping (and return _dst_) :\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { b1: 'bbb' }, c: 'ccc', d: 'ddd' };\nvar dst = { f: { a: 2, b1: 'xxx', b2: 'yyy' }, e: 'zzz' };\n\ncopyProps(src, dst, {\n a: 'f.a',\n 'b.b1': 'f.b1',\n 'b.b2': 'f.b2',\n c: 'f.c',\n});\n// => { f: { a: 1, b1: 'bbb', b2: 'yyy', c: 'ccc' }, e: 'zzz' }\n```\n\nCopy _src_ to _dst_ with convert function (and return _dst_) :\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { b1: 'bbb' } };\nvar dst = { a: 0 };\n\ncopyProps(src, dst, function (srcInfo) {\n if (srcInfo.keyChain === 'a') {\n return srcInfo.value * 2;\n }\n if (srcInfo.keyChain === 'b.b1') {\n return srcInfo.value.toUpperCase();\n }\n});\n// => { a: 2, b: { b1: 'BBB' } }\n```\n\nCan use an array instead of a map as property mapping :\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { c: 'CCC' }, d: { e: 'EEE' } };\nvar dst = { a: 9, b: { c: 'xxx' }, d: { e: 'yyy' } };\nvar fromto = ['b.c', 'd.e'];\ncopyProps(src, dst, fromto);\n// => { a: 9, b: { c: 'CCC' }, d: { e: 'EEE' } }\n```\n\nCan copy reversively (from _dst_ to _src_) by reverse flag (and return _src_):\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { b1: 'bbb' }, c: 'ccc' };\nvar dst = { a: 2, b: { b1: 'xxx', b2: 'yyy' } };\n\ncopyProps(src, dst, true);\n// => { a: 2, b: { b1: 'xxx', b2: 'yyy' }, c: 'ccc' }\n```\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: { b1: 'bbb' }, c: 'ccc', d: 'ddd' };\nvar dst = { f: { a: 2, b1: 'xxx', b2: 'yyy' }, e: 'zzz' };\n\ncopyProps(\n src,\n dst,\n {\n a: 'f.a',\n 'b.b2': 'f.b2',\n c: 'f.c',\n },\n true\n);\n// => { a: 2, b: { b1: 'bbb', b2: 'yyy' }, c: 'ccc', d: 'ddd' }\n```\n\nIf a value of source property is undefined (when not using converter), or a result of converter is undefined (when using converter), the value is not copied.\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 'A', b: undefined, c: null, d: 1 };\nvar dst = { a: 'a', b: 'b', c: 'c' };\n\ncopyProps(src, dst, function (srcInfo) {\n if (srcInfo.keyChain === 'd') {\n return undefined;\n } else {\n return srcInfo.value;\n }\n});\n// => { a: 'A', b: 'b', c: null }\n```\n\nYou can operate the parent node object directly in converter.\n\n```js\nconst copyProps = require('copy-props');\n\nvar src = { a: 1, b: 2 };\nvar dst = {};\n\ncopyProps(src, dst, function (srcInfo, dstInfo) {\n Object.defineProperty(dstInfo.parent, dstInfo.key, {\n writable: false,\n enumerable: true,\n configurable: false,\n value: srcInfo.value * 2,\n });\n}); // => { a: 2, b: 4 }\n\ndst; // => { a: 2, b: 4 }\ndst.a = 9;\ndst; // -> { a: 2, b: 4 }\n```\n\n## API\n\n### copyProps(src, dst [, fromto] [, converter] [, reverse]) => object\n\nCopy properties of _src_ to _dst_ deeply.\nIf _fromto_ is given, it is able to copy between different properties.\nIf _converter_ is given, it is able to convert the terminal values.\n\n#### Parameters:\n\n| Parameter | Type | Description |\n| :---------- | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| _src_ | object | A source object of copy. |\n| _dst_ | object | A destinate object of copy. |\n| _fromto_ | object | array | An object mapping properties between _src_ and _dst_. (Optional) |\n| _converter_ | function | A function to convert terminal values in _src_. (Optional) |\n| _reverse_ | boolean | True, if copying reversively from dst to src and returns src object. `fromto` is also reversively used from value to key. This default value is `false`. (Optional) |\n\n#### Returns:\n\n_dst_ object after copying.\n\n**Type:** object\n\n- **Format of fromto**\n\n _fromto_ is a non-nested key-value object. And the *key*s are property key chains of _src_ and the *value*s are property key chains of _dst_.\n The key chain is a string which is concatenated property keys on each level with dots, like `'aaa.bbb.ccc'`.\n\n The following example copys the value of `src.aaa.bbb.ccc` to `dst.xxx.yyy`.\n\n ```js\n copyProps(src, dst, {\n 'aaa.bbb.ccc': 'xxx.yyy',\n });\n ```\n\n _fromto_ can be an array. In that case, the array works as a map which has pairs of same key and value.\n\n- **API of converter**\n\n **converter(srcInfo, dstInfo) : Any**\n\n _converter_ is a function to convert terminal values of propeerties of _src_.\n\n **Parameters:**\n\n | Parameter | Type | Description |\n | :-------- | :----: | :---------------------------------------------------------------- |\n | _srcInfo_ | object | An object which has informations about the current node of _src_. |\n | _dstInfo_ | object | An object which has informations about the current node of _dst_. |\n\n **Return:**\n\n The converted value to be set as a destination property value. If this value is undefined, the destination property is not set to the destination node object.\n\n **Type:** _Any_\n\n - **Properties of srcInfo and dstInfo**\n\n _srcInfo_ and _dstInfo_ has same properties, as follows:\n\n | Property | Type | Description |\n | :--------- | :----: | :------------------------------------------------------ |\n | _value_ | _Any_ | The value of the current node. |\n | _key_ | string | The key name of the current node. |\n | _keyChain_ | string | The full key of the current node concatenated with dot. |\n | _depth_ | number | The depth of the current node. |\n | _parent_ | object | The parent node of the current node. |\n\n## License\n\nMIT\n\n\n[downloads-image]: https://img.shields.io/npm/dm/copy-props.svg?style=flat-square\n[npm-url]: https://www.npmjs.org/package/copy-props\n[npm-image]: https://img.shields.io/npm/v/copy-props.svg?style=flat-square\n\n[ci-url]: https://github.com/gulpjs/copy-props/actions?query=workflow:dev\n[ci-image]: https://img.shields.io/github/workflow/status/gulpjs/copy-props/dev?style=flat-square\n\n[coveralls-url]: https://coveralls.io/r/gulpjs/copy-props\n[coveralls-image]: https://img.shields.io/coveralls/gulpjs/copy-props/master.svg\n\n","_attachments":{},"homepage":"https://github.com/gulpjs/copy-prop#readme","bugs":{"url":"https://github.com/gulpjs/copy-prop/issues"},"license":"MIT"}
![](\"https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png\")
\n \n