Skip to content

Commit e890706

Browse files
jonschlinkertjonschlinkert
committed
run verb to generate readme
1 parent 9cabb2e commit e890706

File tree

2 files changed

+181
-70
lines changed

2 files changed

+181
-70
lines changed

‎.verb.md

Lines changed: 49 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -37,41 +37,68 @@ console.log(set({}, 'a\\.b\\.c', 'd'));
3737
//=> { 'a.b.c': 'd' }
3838
```
3939

40-
**Escaping with double-quotes or single-quotes**
40+
## Benchmarks
4141

42-
Wrap double or single quotes around the string, or part of the string, that should not be split by set-value:
42+
_(benchmarks were run on a MacBook Pro 2.5 GHz Intel Core i7, 16 GB 1600 MHz DDR3)_.
4343

44-
```js
45-
console.log(set({}, '"a.b".c', 'd'));
46-
//=> { 'a.b': { c: 'd' } }
47-
48-
console.log(set({}, "'a.b'.c", "d"));
49-
//=> { 'a.b': { c: 'd' } }
44+
set-value is more reliable and has more features than dot-prop, without sacrificing performance.
5045

51-
console.log(set({}, '"this/is/a/.file.path"', 'd'));
52-
//=> { 'this/is/a/file.path': 'd' }
46+
```
47+
{%= include("./benchmark/stats.md") %}
5348
```
5449

55-
### Bracket support
56-
57-
set-value does not split inside brackets or braces:
50+
### Running the benchmarks
5851

59-
```js
60-
console.log(set({}, '[a.b].c', 'd'));
61-
//=> { '[a.b]': { c: 'd' } }
52+
Clone this library into a local directory:
6253

63-
console.log(set({}, "(a.b).c", "d"));
64-
//=> { '(a.b)': { c: 'd' } }
54+
```sh
55+
$ git clone https://github.com/jonschlinkert/set-value.git
56+
```
6557

66-
console.log(set({}, "<a.b>.c", "d"));
67-
//=> { '<a.b>': { c: 'd' } }
58+
Then install devDependencies and run benchmarks:
6859

69-
console.log(set({}, "{a..b}.c", "d"));
70-
//=> { '{a..b}': { c: 'd' } }
60+
```sh
61+
$ npm install && node benchmark
7162
```
7263

64+
## Comparisons to other libs, or _"the list of shame"_
65+
66+
These are just a few of the duplicate libraries on NPM.
67+
68+
- [bury][] fails all of the tests. I even wrapped it to have it return the object instead of the value, but with all of that work it still fails the vast majority of tests.
69+
- [deep-get-set][] fails 22 of 26 unit tests.
70+
- [deep-object][] fails 25 of 26 unit tests, completely butchered given objects.
71+
- [deep-property][] fails 17 of 26 unit tests.
72+
- [deep-set][] fails 13 of 26 unit tests.
73+
- [deephas][] fails 17 of 26 unit tests.
74+
- [dot-prop][] fails 9 of 26 unit tests.
75+
- [dot2val][] fails 17 of 26 unit tests.
76+
- [es5-dot-prop][] fails 15 of 26 unit tests.
77+
- [getsetdeep][] fails all unit tests due to `this` being used improperly in the methods. I was able to patch it by binding the (plain) object to the methods, but it still fails 17 of 26 unit tests.
78+
- [lodash.set][] fails 11 of 26 unit tests.
79+
- [object-path-set][] fails 12 of 26 unit tests.
80+
- [object-path][] fails 16 of 26 unit tests.
81+
- [object-set][] fails 13 of 26 unit tests.
82+
- [set-nested-prop][] fails 24 of 26 unit tests.
83+
- [setvalue][] (this library is almost identical to a previous version of this library)
84+
- Many dozens of others
85+
86+
**Others that do the same thing, but use a completely different API**
87+
88+
- [deep-set-in][]
89+
- [set-deep][]
90+
- [set-deep-prop][]
91+
- [bury][]
92+
- Many dozens of others
93+
94+
7395
## History
7496

97+
### v3.0.0
98+
99+
- Added support for a custom `split` function to be passed on the options.
100+
- Removed support for splitting on brackets, since a [custom function][split-string] can be passed to do this now.
101+
75102
### v2.0.0
76103

77104
- Adds support for escaping with double or single quotes. See [escaping](#escaping) for examples.

‎README.md

Lines changed: 132 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
> Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.
44
5+
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
6+
57
## Install
68

79
Install with [npm](https://www.npmjs.com/):
@@ -48,41 +50,111 @@ console.log(set({}, 'a\\.b\\.c', 'd'));
4850
//=> { 'a.b.c': 'd' }
4951
```
5052

51-
**Escaping with double-quotes or single-quotes**
53+
## Benchmarks
5254

53-
Wrap double or single quotes around the string, or part of the string, that should not be split by set-value:
55+
_(benchmarks were run on a MacBook Pro 2.5 GHz Intel Core i7, 16 GB 1600 MHz DDR3)_.
5456

55-
```js
56-
console.log(set({}, '"a.b".c', 'd'));
57-
//=> { 'a.b': { c: 'd' } }
57+
set-value is more reliable and has more features than dot-prop, without sacrificing performance.
5858

59-
console.log(set({}, "'a.b'.c", "d"));
60-
//=> { 'a.b': { c: 'd' } }
61-
62-
console.log(set({}, '"this/is/a/.file.path"', 'd'));
63-
//=> { 'this/is/a/file.path': 'd' }
6459
```
60+
# deep (194 bytes)
61+
deep-object x 629,744 ops/sec ±0.85% (88 runs sampled)
62+
deep-property x 1,470,427 ops/sec ±0.94% (89 runs sampled)
63+
deep-set x 1,401,089 ops/sec ±1.02% (91 runs sampled)
64+
deephas x 590,005 ops/sec ±1.73% (86 runs sampled)
65+
dot-prop x 1,261,408 ops/sec ±0.94% (90 runs sampled)
66+
dot2val x 1,672,729 ops/sec ±1.12% (89 runs sampled)
67+
es5-dot-prop x 1,313,018 ops/sec ±0.79% (91 runs sampled)
68+
lodash-set x 1,074,464 ops/sec ±0.97% (93 runs sampled)
69+
object-path-set x 961,198 ops/sec ±2.07% (74 runs sampled)
70+
object-set x 258,438 ops/sec ±0.69% (90 runs sampled)
71+
set-value x 1,976,843 ops/sec ±2.07% (89 runs sampled)
72+
73+
fastest is set-value (by 186% avg)
74+
75+
# medium (98 bytes)
76+
deep-object x 3,249,287 ops/sec ±1.04% (93 runs sampled)
77+
deep-property x 3,409,307 ops/sec ±1.28% (88 runs sampled)
78+
deep-set x 3,240,776 ops/sec ±1.13% (93 runs sampled)
79+
deephas x 960,504 ops/sec ±1.39% (89 runs sampled)
80+
dot-prop x 2,776,388 ops/sec ±0.80% (94 runs sampled)
81+
dot2val x 3,889,791 ops/sec ±1.28% (91 runs sampled)
82+
es5-dot-prop x 2,779,604 ops/sec ±1.32% (91 runs sampled)
83+
lodash-set x 2,791,304 ops/sec ±0.75% (90 runs sampled)
84+
object-path-set x 2,462,084 ops/sec ±1.51% (91 runs sampled)
85+
object-set x 838,569 ops/sec ±0.87% (90 runs sampled)
86+
set-value x 4,767,287 ops/sec ±1.21% (91 runs sampled)
87+
88+
fastest is set-value (by 181% avg)
89+
90+
# shallow (101 bytes)
91+
deep-object x 4,793,168 ops/sec ±0.75% (88 runs sampled)
92+
deep-property x 4,669,218 ops/sec ±1.17% (90 runs sampled)
93+
deep-set x 4,648,247 ops/sec ±0.73% (91 runs sampled)
94+
deephas x 1,246,414 ops/sec ±1.67% (92 runs sampled)
95+
dot-prop x 3,913,694 ops/sec ±1.23% (89 runs sampled)
96+
dot2val x 5,428,829 ops/sec ±0.76% (92 runs sampled)
97+
es5-dot-prop x 3,897,931 ops/sec ±1.19% (92 runs sampled)
98+
lodash-set x 6,128,638 ops/sec ±0.95% (87 runs sampled)
99+
object-path-set x 5,429,978 ops/sec ±3.31% (87 runs sampled)
100+
object-set x 1,529,485 ops/sec ±2.37% (89 runs sampled)
101+
set-value x 7,150,921 ops/sec ±1.58% (89 runs sampled)
102+
103+
fastest is set-value (by 172% avg)
65104
66-
### Bracket support
105+
```
67106

68-
set-value does not split inside brackets or braces:
107+
### Running the benchmarks
69108

70-
```js
71-
console.log(set({}, '[a.b].c', 'd'));
72-
//=> { '[a.b]': { c: 'd' } }
109+
Clone this library into a local directory:
73110

74-
console.log(set({}, "(a.b).c", "d"));
75-
//=> { '(a.b)': { c: 'd' } }
111+
```sh
112+
$ git clone https://github.com/jonschlinkert/set-value.git
113+
```
76114

77-
console.log(set({}, "<a.b>.c", "d"));
78-
//=> { '<a.b>': { c: 'd' } }
115+
Then install devDependencies and run benchmarks:
79116

80-
console.log(set({}, "{a..b}.c", "d"));
81-
//=> { '{a..b}': { c: 'd' } }
117+
```sh
118+
$ npm install && node benchmark
82119
```
83120

121+
## Comparisons to other libs, or _"the list of shame"_
122+
123+
These are just a few of the duplicate libraries on NPM.
124+
125+
* [bury](https://github.com/kalmbach/bury) fails all of the tests. I even wrapped it to have it return the object instead of the value, but with all of that work it still fails the vast majority of tests.
126+
* [deep-get-set](https://github.com/acstll/deep-get-set) fails 22 of 26 unit tests.
127+
* [deep-object](https://github.com/ayushgp/deep-object) fails 25 of 26 unit tests, completely butchered given objects.
128+
* [deep-property](https://github.com/mikattack/node-deep-property) fails 17 of 26 unit tests.
129+
* [deep-set](https://github.com/klaemo/deep-set) fails 13 of 26 unit tests.
130+
* [deephas](https://github.com/sharpred/deepHas) fails 17 of 26 unit tests.
131+
* [dot-prop](https://github.com/sindresorhus/dot-prop) fails 9 of 26 unit tests.
132+
* [dot2val](https://github.com/yangg/dot2val) fails 17 of 26 unit tests.
133+
* [es5-dot-prop](https://github.com/sindresorhus/dot-prop) fails 15 of 26 unit tests.
134+
* [getsetdeep](https://github.com/bevry/getsetdeep) fails all unit tests due to `this` being used improperly in the methods. I was able to patch it by binding the (plain) object to the methods, but it still fails 17 of 26 unit tests.
135+
* [lodash.set](https://lodash.com/) fails 11 of 26 unit tests.
136+
* [object-path-set](https://github.com/skratchdot/object-path-set) fails 12 of 26 unit tests.
137+
* [object-path](https://github.com/mariocasciaro/object-path) fails 16 of 26 unit tests.
138+
* [object-set](https://github.com/gearcase/object-set) fails 13 of 26 unit tests.
139+
* [set-nested-prop](https://github.com/tiaanduplessis/set-nested-prop) fails 24 of 26 unit tests.
140+
* [setvalue](https://github.com/blakeembrey/setvalue) (this library is almost identical to a previous version of this library)
141+
* Many dozens of others
142+
143+
**Others that do the same thing, but use a completely different API**
144+
145+
* [deep-set-in](https://github.com/KulikovskyIgor/deep-set-in)
146+
* [set-deep](https://github.com/radubrehar/set-deep)
147+
* [set-deep-prop](https://github.com/mmckelvy/set-deep-prop)
148+
* [bury](https://github.com/kalmbach/bury)
149+
* Many dozens of others
150+
84151
## History
85152

153+
### v3.0.0
154+
155+
* Added support for a custom `split` function to be passed on the options.
156+
* Removed support for splitting on brackets, since a [custom function](https://github.com/jonschlinkert/split-string) can be passed to do this now.
157+
86158
### v2.0.0
87159

88160
* Adds support for escaping with double or single quotes. See [escaping](#escaping) for examples.
@@ -92,30 +164,26 @@ If there are any regressions please create a [bug report](../../issues/new). Tha
92164

93165
## About
94166

95-
### Related projects
167+
<details>
168+
<summary><strong>Contributing</strong></summary>
96169

97-
* [assign-value](https://www.npmjs.com/package/assign-value): Assign a value or extend a deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/assign-value) | [homepage](https://github.com/jonschlinkert/assign-value "Assign a value or extend a deeply nested property of an object using object path notation.")
98-
* [get-value](https://www.npmjs.com/package/get-value): Use property paths (`a.b.c`) to get a nested value from an object. | [homepage](https://github.com/jonschlinkert/get-value "Use property paths (`a.b.c`) to get a nested value from an object.")
99-
* [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value "Returns true if a value exists, false if empty. Works with deeply nested values using object paths.")
100-
* [merge-value](https://www.npmjs.com/package/merge-value): Similar to assign-value but deeply merges object values or nested values using object path/dot notation. | [homepage](https://github.com/jonschlinkert/merge-value "Similar to assign-value but deeply merges object values or nested values using object path/dot notation.")
101-
* [omit-value](https://www.npmjs.com/package/omit-value): Omit properties from an object or deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/omit-value) | [homepage](https://github.com/jonschlinkert/omit-value "Omit properties from an object or deeply nested property of an object using object path notation.")
102-
* [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value "Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.")
103-
* [union-value](https://www.npmjs.com/package/union-value): Set an array of unique values as the property of an object. Supports setting deeply… [more](https://github.com/jonschlinkert/union-value) | [homepage](https://github.com/jonschlinkert/union-value "Set an array of unique values as the property of an object. Supports setting deeply nested properties using using object-paths/dot notation.")
104-
* [unset-value](https://www.npmjs.com/package/unset-value): Delete nested properties from an object using dot notation. | [homepage](https://github.com/jonschlinkert/unset-value "Delete nested properties from an object using dot notation.")
170+
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
105171

106-
### Contributing
172+
</details>
107173

108-
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
174+
<details>
175+
<summary><strong>Running Tests</strong></summary>
109176

110-
### Contributors
177+
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
111178

112-
| **Commits** | **Contributor** |
113-
| --- | --- |
114-
| 59 | [jonschlinkert](https://github.com/jonschlinkert) |
115-
| 1 | [vadimdemedes](https://github.com/vadimdemedes) |
116-
| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
179+
```sh
180+
$ npm install && npm test
181+
```
182+
183+
</details>
117184

118-
### Building docs
185+
<details>
186+
<summary><strong>Building docs</strong></summary>
119187

120188
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
121189

@@ -125,26 +193,42 @@ To generate the readme, run the following command:
125193
$ npm install -g verbose/verb#dev verb-generate-readme && verb
126194
```
127195

128-
### Running tests
196+
</details>
129197

130-
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
198+
### Related projects
131199

132-
```sh
133-
$ npm install && npm test
134-
```
200+
You might also be interested in these projects:
201+
202+
* [assign-value](https://www.npmjs.com/package/assign-value): Assign a value or extend a deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/assign-value) | [homepage](https://github.com/jonschlinkert/assign-value "Assign a value or extend a deeply nested property of an object using object path notation.")
203+
* [get-value](https://www.npmjs.com/package/get-value): Use property paths like 'a.b.c' to get a nested value from an object. Even works… [more](https://github.com/jonschlinkert/get-value) | [homepage](https://github.com/jonschlinkert/get-value "Use property paths like 'a.b.c' to get a nested value from an object. Even works when keys have dots in them (no other dot-prop library can do this!).")
204+
* [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value "Returns true if a value exists, false if empty. Works with deeply nested values using object paths.")
205+
* [merge-value](https://www.npmjs.com/package/merge-value): Similar to assign-value but deeply merges object values or nested values using object path/dot notation. | [homepage](https://github.com/jonschlinkert/merge-value "Similar to assign-value but deeply merges object values or nested values using object path/dot notation.")
206+
* [omit-value](https://www.npmjs.com/package/omit-value): Omit properties from an object or deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/omit-value) | [homepage](https://github.com/jonschlinkert/omit-value "Omit properties from an object or deeply nested property of an object using object path notation.")
207+
* [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value "Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.")
208+
* [union-value](https://www.npmjs.com/package/union-value): Set an array of unique values as the property of an object. Supports setting deeply… [more](https://github.com/jonschlinkert/union-value) | [homepage](https://github.com/jonschlinkert/union-value "Set an array of unique values as the property of an object. Supports setting deeply nested properties using using object-paths/dot notation.")
209+
* [unset-value](https://www.npmjs.com/package/unset-value): Delete nested properties from an object using dot notation. | [homepage](https://github.com/jonschlinkert/unset-value "Delete nested properties from an object using dot notation.")
210+
211+
### Contributors
212+
213+
| **Commits** | **Contributor** |
214+
| --- | --- |
215+
| 64 | [jonschlinkert](https://github.com/jonschlinkert) |
216+
| 1 | [vadimdemedes](https://github.com/vadimdemedes) |
217+
| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
135218

136219
### Author
137220

138221
**Jon Schlinkert**
139222

140-
* [github/jonschlinkert](https://github.com/jonschlinkert)
141-
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
223+
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
224+
* [GitHub Profile](https://github.com/jonschlinkert)
225+
* [Twitter Profile](https://twitter.com/jonschlinkert)
142226

143227
### License
144228

145-
Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
229+
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
146230
Released under the [MIT License](LICENSE).
147231

148232
***
149233

150-
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 21, 2017._
234+
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on March 05, 2018._

0 commit comments

Comments
 (0)