239 lines
7.7 KiB
Markdown
239 lines
7.7 KiB
Markdown
<p align="center">
|
|
<a href="http://gulpjs.com">
|
|
<img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
|
|
</a>
|
|
</p>
|
|
|
|
# copy-props
|
|
|
|
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]
|
|
|
|
Copy properties between two objects deeply.
|
|
|
|
## Install
|
|
|
|
To install from npm:
|
|
|
|
```sh
|
|
$ npm i copy-props --save
|
|
```
|
|
|
|
## Usage
|
|
|
|
Copy _src_ to _dst_ simply (and return _dst_) :
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { b1: 'bbb' }, c: 'ccc' };
|
|
var dst = { a: 2, b: { b1: 'xxx', b2: 'yyy' } };
|
|
|
|
copyProps(src, dst);
|
|
// => { a: 1, b: { b1: 'bbb', b2: 'yyy' }, c: 'ccc' }
|
|
```
|
|
|
|
Copy _src_ to _dst_ with property mapping (and return _dst_) :
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { b1: 'bbb' }, c: 'ccc', d: 'ddd' };
|
|
var dst = { f: { a: 2, b1: 'xxx', b2: 'yyy' }, e: 'zzz' };
|
|
|
|
copyProps(src, dst, {
|
|
a: 'f.a',
|
|
'b.b1': 'f.b1',
|
|
'b.b2': 'f.b2',
|
|
c: 'f.c',
|
|
});
|
|
// => { f: { a: 1, b1: 'bbb', b2: 'yyy', c: 'ccc' }, e: 'zzz' }
|
|
```
|
|
|
|
Copy _src_ to _dst_ with convert function (and return _dst_) :
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { b1: 'bbb' } };
|
|
var dst = { a: 0 };
|
|
|
|
copyProps(src, dst, function (srcInfo) {
|
|
if (srcInfo.keyChain === 'a') {
|
|
return srcInfo.value * 2;
|
|
}
|
|
if (srcInfo.keyChain === 'b.b1') {
|
|
return srcInfo.value.toUpperCase();
|
|
}
|
|
});
|
|
// => { a: 2, b: { b1: 'BBB' } }
|
|
```
|
|
|
|
Can use an array instead of a map as property mapping :
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { c: 'CCC' }, d: { e: 'EEE' } };
|
|
var dst = { a: 9, b: { c: 'xxx' }, d: { e: 'yyy' } };
|
|
var fromto = ['b.c', 'd.e'];
|
|
copyProps(src, dst, fromto);
|
|
// => { a: 9, b: { c: 'CCC' }, d: { e: 'EEE' } }
|
|
```
|
|
|
|
Can copy reversively (from _dst_ to _src_) by reverse flag (and return _src_):
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { b1: 'bbb' }, c: 'ccc' };
|
|
var dst = { a: 2, b: { b1: 'xxx', b2: 'yyy' } };
|
|
|
|
copyProps(src, dst, true);
|
|
// => { a: 2, b: { b1: 'xxx', b2: 'yyy' }, c: 'ccc' }
|
|
```
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: { b1: 'bbb' }, c: 'ccc', d: 'ddd' };
|
|
var dst = { f: { a: 2, b1: 'xxx', b2: 'yyy' }, e: 'zzz' };
|
|
|
|
copyProps(
|
|
src,
|
|
dst,
|
|
{
|
|
a: 'f.a',
|
|
'b.b2': 'f.b2',
|
|
c: 'f.c',
|
|
},
|
|
true
|
|
);
|
|
// => { a: 2, b: { b1: 'bbb', b2: 'yyy' }, c: 'ccc', d: 'ddd' }
|
|
```
|
|
|
|
If 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.
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 'A', b: undefined, c: null, d: 1 };
|
|
var dst = { a: 'a', b: 'b', c: 'c' };
|
|
|
|
copyProps(src, dst, function (srcInfo) {
|
|
if (srcInfo.keyChain === 'd') {
|
|
return undefined;
|
|
} else {
|
|
return srcInfo.value;
|
|
}
|
|
});
|
|
// => { a: 'A', b: 'b', c: null }
|
|
```
|
|
|
|
You can operate the parent node object directly in converter.
|
|
|
|
```js
|
|
const copyProps = require('copy-props');
|
|
|
|
var src = { a: 1, b: 2 };
|
|
var dst = {};
|
|
|
|
copyProps(src, dst, function (srcInfo, dstInfo) {
|
|
Object.defineProperty(dstInfo.parent, dstInfo.key, {
|
|
writable: false,
|
|
enumerable: true,
|
|
configurable: false,
|
|
value: srcInfo.value * 2,
|
|
});
|
|
}); // => { a: 2, b: 4 }
|
|
|
|
dst; // => { a: 2, b: 4 }
|
|
dst.a = 9;
|
|
dst; // -> { a: 2, b: 4 }
|
|
```
|
|
|
|
## API
|
|
|
|
### <u>copyProps(src, dst [, fromto] [, converter] [, reverse]) => object</u>
|
|
|
|
Copy properties of _src_ to _dst_ deeply.
|
|
If _fromto_ is given, it is able to copy between different properties.
|
|
If _converter_ is given, it is able to convert the terminal values.
|
|
|
|
#### Parameters:
|
|
|
|
| Parameter | Type | Description |
|
|
| :---------- | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| _src_ | object | A source object of copy. |
|
|
| _dst_ | object | A destinate object of copy. |
|
|
| _fromto_ | object | array | An object mapping properties between _src_ and _dst_. (Optional) |
|
|
| _converter_ | function | A function to convert terminal values in _src_. (Optional) |
|
|
| _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) |
|
|
|
|
#### Returns:
|
|
|
|
_dst_ object after copying.
|
|
|
|
**Type:** object
|
|
|
|
- **Format of <i>fromto</i>**
|
|
|
|
_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_.
|
|
The key chain is a string which is concatenated property keys on each level with dots, like `'aaa.bbb.ccc'`.
|
|
|
|
The following example copys the value of `src.aaa.bbb.ccc` to `dst.xxx.yyy`.
|
|
|
|
```js
|
|
copyProps(src, dst, {
|
|
'aaa.bbb.ccc': 'xxx.yyy',
|
|
});
|
|
```
|
|
|
|
_fromto_ can be an array. In that case, the array works as a map which has pairs of same key and value.
|
|
|
|
- **API of <i>converter</i>**
|
|
|
|
**<u>converter(srcInfo, dstInfo) : Any</u>**
|
|
|
|
_converter_ is a function to convert terminal values of propeerties of _src_.
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
| :-------- | :----: | :---------------------------------------------------------------- |
|
|
| _srcInfo_ | object | An object which has informations about the current node of _src_. |
|
|
| _dstInfo_ | object | An object which has informations about the current node of _dst_. |
|
|
|
|
**Return:**
|
|
|
|
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.
|
|
|
|
**Type:** _Any_
|
|
|
|
- **Properties of <i>srcInfo</i> and <i>dstInfo</i>**
|
|
|
|
_srcInfo_ and _dstInfo_ has same properties, as follows:
|
|
|
|
| Property | Type | Description |
|
|
| :--------- | :----: | :------------------------------------------------------ |
|
|
| _value_ | _Any_ | The value of the current node. |
|
|
| _key_ | string | The key name of the current node. |
|
|
| _keyChain_ | string | The full key of the current node concatenated with dot. |
|
|
| _depth_ | number | The depth of the current node. |
|
|
| _parent_ | object | The parent node of the current node. |
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
<!-- prettier-ignore-start -->
|
|
[downloads-image]: https://img.shields.io/npm/dm/copy-props.svg?style=flat-square
|
|
[npm-url]: https://www.npmjs.org/package/copy-props
|
|
[npm-image]: https://img.shields.io/npm/v/copy-props.svg?style=flat-square
|
|
|
|
[ci-url]: https://github.com/gulpjs/copy-props/actions?query=workflow:dev
|
|
[ci-image]: https://img.shields.io/github/workflow/status/gulpjs/copy-props/dev?style=flat-square
|
|
|
|
[coveralls-url]: https://coveralls.io/r/gulpjs/copy-props
|
|
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/copy-props/master.svg
|
|
<!-- prettier-ignore-end -->
|