1 : /**
2 :  * @file obj.js
3 :  * @module obj
4 :  */
5 : 
6 : /**
7 :  * @callback obj:EachCallback
8 :  *
9 :  * @param {*} value
10 :  *        The current key for the object that is being iterated over.
11 :  *
12 :  * @param {string} key
13 :  *        The current key-value for object that is being iterated over
14 :  */
15 : 
16 : /**
17 :  * @callback obj:ReduceCallback
18 :  *
19 :  * @param {*} accum
20 :  *        The value that is accumulating over the reduce loop.
21 :  *
22 :  * @param {*} value
23 :  *        The current key for the object that is being iterated over.
24 :  *
25 :  * @param {string} key
26 :  *        The current key-value for object that is being iterated over
27 :  *
28 :  * @return {*}
29 :  *         The new accumulated value.
30 :  */
31 : const toString = Object.prototype.toString;
32 : 
33 : /**
34 :  * Get the keys of an Object
35 :  *
36 :  * @param {Object}
37 :  *        The Object to get the keys from
38 :  *
39 :  * @return {string[]}
40 :  *         An array of the keys from the object. Returns an empty array if the
41 :  *         object passed in was invalid or had no keys.
42 :  *
43 :  * @private
44 :  */
45 : const keys = function(object) {
46 :   return isObject(object) ? Object.keys(object) : [];
47 : };
48 : 
49 : /**
50 :  * Array-like iteration for objects.
51 :  *
52 :  * @param {Object} object
53 :  *        The object to iterate over
54 :  *
55 :  * @param {obj:EachCallback} fn
56 :  *        The callback function which is called for each key in the object.
57 :  */
58 : export function each(object, fn) {
59 :   keys(object).forEach(key => fn(object[key], key));
60 : }
61 : 
62 : /**
63 :  * Array-like reduce for objects.
64 :  *
65 :  * @param {Object} object
66 :  *        The Object that you want to reduce.
67 :  *
68 :  * @param {Function} fn
69 :  *         A callback function which is called for each key in the object. It
70 :  *         receives the accumulated value and the per-iteration value and key
71 :  *         as arguments.
72 :  *
73 :  * @param {*} [initial = 0]
74 :  *        Starting value
75 :  *
76 :  * @return {*}
77 :  *         The final accumulated value.
78 :  */
79 : export function reduce(object, fn, initial = 0) {
80 :   return keys(object).reduce((accum, key) => fn(accum, object[key], key), initial);
81 : }
82 : 
83 : /**
84 :  * Returns whether a value is an object of any kind - including DOM nodes,
85 :  * arrays, regular expressions, etc. Not functions, though.
86 :  *
87 :  * This avoids the gotcha where using `typeof` on a `null` value
88 :  * results in `'object'`.
89 :  *
90 :  * @param  {Object} value
91 :  * @return {boolean}
92 :  */
93 : export function isObject(value) {
94 :   return !!value && typeof value === 'object';
95 : }
96 : 
97 : /**
98 :  * Returns whether an object appears to be a "plain" object - that is, a
99 :  * direct instance of `Object`.
100 :  *
101 :  * @param  {Object} value
102 :  * @return {boolean}
103 :  */
104 : export function isPlain(value) {
105 :   return isObject(value) &&
106 :     toString.call(value) === '[object Object]' &&
107 :     value.constructor === Object;
108 : }
109 : 
110 : /**
111 :  * Merge two objects recursively.
112 :  *
113 :  * Performs a deep merge like
114 :  * {@link https://lodash.com/docs/4.17.10#merge|lodash.merge}, but only merges
115 :  * plain objects (not arrays, elements, or anything else).
116 :  *
117 :  * Non-plain object values will be copied directly from the right-most
118 :  * argument.
119 :  *
120 :  * @param   {Object[]} sources
121 :  *          One or more objects to merge into a new object.
122 :  *
123 :  * @return {Object}
124 :  *          A new object that is the merged result of all sources.
125 :  */
126 : export function merge(...sources) {
127 :   const result = {};
128 : 
129 :   sources.forEach(source => {
130 :     if (!source) {
131 :       return;
132 :     }
133 : 
134 :     each(source, (value, key) => {
135 :       if (!isPlain(value)) {
136 :         result[key] = value;
137 :         return;
138 :       }
139 : 
140 :       if (!isPlain(result[key])) {
141 :         result[key] = {};
142 :       }
143 : 
144 :       result[key] = merge(result[key], value);
145 :     });
146 :   });
147 : 
148 :   return result;
149 : }
150 : 
151 : /**
152 :  * Object.defineProperty but "lazy", which means that the value is only set after
153 :  * it is retrieved the first time, rather than being set right away.
154 :  *
155 :  * @param {Object} obj the object to set the property on
156 :  * @param {string} key the key for the property to set
157 :  * @param {Function} getValue the function used to get the value when it is needed.
158 :  * @param {boolean} setter whether a setter should be allowed or not
159 :  */
160 : export function defineLazyProperty(obj, key, getValue, setter = true) {
161 :   const set = (value) =>
162 :     Object.defineProperty(obj, key, {value, enumerable: true, writable: true});
163 : 
164 :   const options = {
165 :     configurable: true,
166 :     enumerable: true,
167 :     get() {
168 :       const value = getValue();
169 : 
170 :       set(value);
171 : 
172 :       return value;
173 :     }
174 :   };
175 : 
176 :   if (setter) {
177 :     options.set = set;
178 :   }
179 : 
180 :   return Object.defineProperty(obj, key, options);
181 : }