1 | # 🇩 defu
|
2 |
|
3 | > Recursively assign default properties. Lightweight and Fast!
|
4 |
|
5 | [![Standard JS][standard-src]][standard-href]
|
6 | [![david dm][david-src]][david-href]
|
7 | [![codecov][codecov-src]][codecov-href]
|
8 |
|
9 | [![npm version][npm-v-src]][npm-v-href]
|
10 | [![npm downloads][npm-dm-src]][npm-dm-href]
|
11 | [![package phobia][packagephobia-src]][packagephobia-href]
|
12 | [![bundle phobia][bundlephobia-src]][bundlephobia-href]
|
13 |
|
14 | ## Install
|
15 |
|
16 | Install package:
|
17 |
|
18 | ```bash
|
19 | yarn add defu
|
20 | # or
|
21 | npm install defu
|
22 | ```
|
23 |
|
24 | ## Usage
|
25 |
|
26 | ```js
|
27 | const options = defu (object, ...defaults)
|
28 | ```
|
29 |
|
30 | Leftmost arguments have more priority when assigning defaults.
|
31 |
|
32 | ### Arguments
|
33 |
|
34 | - **object (Object):** The destination object.
|
35 | - **source (Object):** The source object.
|
36 |
|
37 | ```js
|
38 | const defu = require('defu')
|
39 |
|
40 | console.log(defu({ 'a': { 'b': 2 } }, { 'a': { 'b': 1, 'c': 3 } }))
|
41 | // => { a: { b: 2, c: 3 } }
|
42 | ```
|
43 |
|
44 | ## Custom Merger
|
45 |
|
46 | Sometimes default merging strategy is not desirable. Using `defu.extend` we can create a custom instance with different merging strategy.
|
47 |
|
48 | This function accepts `obj` (source object), `key` and `value` (current value) and should return `true` if applied custom merging.
|
49 |
|
50 | **Example:** Sum numbers instead of overriding
|
51 |
|
52 | ```js
|
53 | const ext = defu.extend((obj, key, value) => {
|
54 | if (typeof obj[key] === 'number' && typeof value === 'number') {
|
55 | obj[key] += val
|
56 | return true
|
57 | }
|
58 | })
|
59 |
|
60 | ext({ cost: 15 }, { cost: 10 }) // { cost: 25 }
|
61 | ```
|
62 |
|
63 | ## Function Merger
|
64 |
|
65 | Using `defu.fn`, if user provided a function, it will be called with default value instead of merging.
|
66 |
|
67 | I can be useful for default values manipulation.
|
68 |
|
69 | **Example:** Filter some items from defaults (array) and add 20 to the count default value.
|
70 |
|
71 | ```js
|
72 |
|
73 | defu.fn({
|
74 | ignore: (val) => val.filter(item => item !== 'dist'),
|
75 | count: (count) => count + 20
|
76 | }, {
|
77 | ignore: ['node_modules','dist'],
|
78 | count: 10
|
79 | })
|
80 | /*
|
81 | {
|
82 | ignore: ['node_modules'],
|
83 | count: 30
|
84 | }
|
85 | */
|
86 | ```
|
87 |
|
88 | **Note:** if the default value is not defined, the function defined won't be called and kept as value.
|
89 |
|
90 | ## Array Function Merger
|
91 |
|
92 | `defu.arrayFn` is similar to `defu.fn` but **only applies to array values defined in defaults**.
|
93 |
|
94 | **Example:** Filter some items from defaults (array) and add 20 to the count default value.
|
95 |
|
96 | ```js
|
97 |
|
98 | defu.arrayFn({
|
99 | ignore(val) => val.filter(i => i !== 'dist'),
|
100 | count: () => 20
|
101 | }, {
|
102 | ignore: [
|
103 | 'node_modules',
|
104 | 'dist'
|
105 | ],
|
106 | count: 10
|
107 | })
|
108 | /*
|
109 | {
|
110 | ignore: ['node_modules'],
|
111 | count: () => 20
|
112 | }
|
113 | */
|
114 | ```
|
115 |
|
116 | **Note:** the function is called only if the value defined in defaults is an aray.
|
117 |
|
118 | ### Remarks
|
119 |
|
120 | - `object` and `defaults` are not modified
|
121 | - `null` values are skipped same as [defaults-deep](https://www.npmjs.com/package/defaults-deep). Please use either [omit-deep](http://npmjs.com/package/omit-deep) or [lodash.defaultsdeep](https://www.npmjs.com/package/lodash.defaultsdeep) if you need to preserve.
|
122 | - Assignment of `__proto__` and `constructor` keys will be skipped to prevent security issues with object pollution.
|
123 | - Will concat `array` values (if default property is defined)
|
124 | ```js
|
125 | console.log(defu({ array: ['b', 'c'] }, { array: ['a'] }))
|
126 | // => { array: ['a', 'b', 'c']}
|
127 | ```
|
128 |
|
129 | ## License
|
130 |
|
131 | MIT. Made with 💖
|
132 |
|
133 |
|
134 | [standard-src]: https://flat.badgen.net/badge/code%20style/standard/green
|
135 | [standard-href]: https://standardjs.com
|
136 |
|
137 | [npm-v-src]: https://flat.badgen.net/npm/v/defu/latest
|
138 | [npm-v-href]: https://npmjs.com/package/defu
|
139 |
|
140 | [npm-dm-src]: https://flat.badgen.net/npm/dm/defu
|
141 | [npm-dm-href]: https://npmjs.com/package/defu
|
142 |
|
143 | [packagephobia-src]: https://flat.badgen.net/packagephobia/install/defu
|
144 | [packagephobia-href]: https://packagephobia.now.sh/result?p=defu
|
145 |
|
146 | [bundlephobia-src]: https://flat.badgen.net/bundlephobia/min/defu
|
147 | [bundlephobia-href]: https://bundlephobia.com/result?p=defu
|
148 |
|
149 | [david-src]: https://flat.badgen.net/david/dep/nuxt-contrib/defu
|
150 | [david-href]: https://david-dm.org/nuxt-contrib/defu
|
151 |
|
152 | [codecov-src]: https://flat.badgen.net/codecov/c/github/nuxt-contrib/defu/master
|
153 | [codecov-href]: https://codecov.io/gh/nuxt-contrib/defu
|