1 | # dot-prop
|
2 |
|
3 | > Get, set, or delete a property from a nested object using a dot path
|
4 |
|
5 | ## Install
|
6 |
|
7 | ```sh
|
8 | npm install dot-prop
|
9 | ```
|
10 |
|
11 | ## Usage
|
12 |
|
13 | ```js
|
14 | import {getProperty, setProperty, hasProperty, deleteProperty} from 'dot-prop';
|
15 |
|
16 | // Getter
|
17 | getProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
|
18 | //=> 'unicorn'
|
19 |
|
20 | getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep');
|
21 | //=> undefined
|
22 |
|
23 | getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep', 'default value');
|
24 | //=> 'default value'
|
25 |
|
26 | getProperty({foo: {'dot.dot': 'unicorn'}}, 'foo.dot\\.dot');
|
27 | //=> 'unicorn'
|
28 |
|
29 | getProperty({foo: [{bar: 'unicorn'}]}, 'foo[0].bar');
|
30 | //=> 'unicorn'
|
31 |
|
32 | // Setter
|
33 | const object = {foo: {bar: 'a'}};
|
34 | setProperty(object, 'foo.bar', 'b');
|
35 | console.log(object);
|
36 | //=> {foo: {bar: 'b'}}
|
37 |
|
38 | const foo = setProperty({}, 'foo.bar', 'c');
|
39 | console.log(foo);
|
40 | //=> {foo: {bar: 'c'}}
|
41 |
|
42 | setProperty(object, 'foo.baz', 'x');
|
43 | console.log(object);
|
44 | //=> {foo: {bar: 'b', baz: 'x'}}
|
45 |
|
46 | setProperty(object, 'foo.biz[0]', 'a');
|
47 | console.log(object);
|
48 | //=> {foo: {bar: 'b', baz: 'x', biz: ['a']}}
|
49 |
|
50 | // Has
|
51 | hasProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
|
52 | //=> true
|
53 |
|
54 | // Deleter
|
55 | const object = {foo: {bar: 'a'}};
|
56 | deleteProperty(object, 'foo.bar');
|
57 | console.log(object);
|
58 | //=> {foo: {}}
|
59 |
|
60 | object.foo.bar = {x: 'y', y: 'x'};
|
61 | deleteProperty(object, 'foo.bar.x');
|
62 | console.log(object);
|
63 | //=> {foo: {bar: {y: 'x'}}}
|
64 | ```
|
65 |
|
66 | ## API
|
67 |
|
68 | ### getProperty(object, path, defaultValue?)
|
69 |
|
70 | Get the value of the property at the given path.
|
71 |
|
72 | Returns the value if any.
|
73 |
|
74 | ### setProperty(object, path, value)
|
75 |
|
76 | Set the property at the given path to the given value.
|
77 |
|
78 | Returns the object.
|
79 |
|
80 | ### hasProperty(object, path)
|
81 |
|
82 | Check whether the property at the given path exists.
|
83 |
|
84 | Returns a boolean.
|
85 |
|
86 | ### deleteProperty(object, path)
|
87 |
|
88 | Delete the property at the given path.
|
89 |
|
90 | Returns a boolean of whether the property existed before being deleted.
|
91 |
|
92 | ### escapePath(path)
|
93 |
|
94 | Escape special characters in a path. Useful for sanitizing user input.
|
95 |
|
96 | ```js
|
97 | import {getProperty, escapePath} from 'dot-prop';
|
98 |
|
99 | const object = {
|
100 | foo: {
|
101 | bar: 'πΈπ» You found me Mario!',
|
102 | },
|
103 | 'foo.bar' : 'π The princess is in another castle!',
|
104 | };
|
105 | const escapedPath = escapePath('foo.bar');
|
106 |
|
107 | console.log(getProperty(object, escapedPath));
|
108 | //=> 'π The princess is in another castle!'
|
109 | ```
|
110 |
|
111 | ### deepKeys(object)
|
112 |
|
113 | Returns an array of every path. Non-empty plain objects and arrays are deeply recursed and are not themselves included.
|
114 |
|
115 | This can be useful to help flatten an object for an API that only accepts key-value pairs or for a tagged template literal.
|
116 |
|
117 | ```js
|
118 | import {getProperty, deepKeys} from 'dot-prop';
|
119 |
|
120 | const user = {
|
121 | name: {
|
122 | first: 'Richie',
|
123 | last: 'Bendall',
|
124 | },
|
125 | activeTasks: [],
|
126 | currentProject: null
|
127 | };
|
128 |
|
129 | for (const property of deepKeys(user)) {
|
130 | console.log(`${property}: ${getProperty(user, property)}`);
|
131 | //=> name.first: Richie
|
132 | //=> name.last: Bendall
|
133 | //=> activeTasks: []
|
134 | //=> currentProject: null
|
135 | }
|
136 | ```
|
137 |
|
138 | #### object
|
139 |
|
140 | Type: `object | array`
|
141 |
|
142 | Object or array to get, set, or delete the `path` value.
|
143 |
|
144 | You are allowed to pass in `undefined` as the object to the `get` and `has` functions.
|
145 |
|
146 | #### path
|
147 |
|
148 | Type: `string`
|
149 |
|
150 | Path of the property in the object, using `.` to separate each nested key.
|
151 |
|
152 | Use `\\.` if you have a `.` in the key.
|
153 |
|
154 | The following path components are invalid and results in `undefined` being returned: `__proto__`, `prototype`, `constructor`.
|
155 |
|
156 | #### value
|
157 |
|
158 | Type: `unknown`
|
159 |
|
160 | Value to set at `path`.
|
161 |
|
162 | #### defaultValue
|
163 |
|
164 | Type: `unknown`
|
165 |
|
166 | Default value.
|