1 # jsprim: utilities for primitive JavaScript types
3 This module provides miscellaneous facilities for working with strings,
4 numbers, dates, and objects and arrays of these basic types.
9 Creates a deep copy of a primitive type, object, or array of primitive types.
12 ### deepEqual(obj1, obj2)
14 Returns whether two objects are equal.
19 Returns true if the given object has no properties and false otherwise. This
20 is O(1) (unlike `Object.keys(obj).length === 0`, which is O(N)).
24 Returns true if the given object has an enumerable, non-inherited property
25 called `key`. [For information on enumerability and ownership of properties, see
27 documentation.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties)
29 ### forEachKey(obj, callback)
31 Like Array.forEach, but iterates enumerable, owned properties of an object
32 rather than elements of an array. Equivalent to:
34 for (var key in obj) {
35 if (Object.prototype.hasOwnProperty.call(obj, key)) {
36 callback(key, obj[key]);
41 ### flattenObject(obj, depth)
43 Flattens an object up to a given level of nesting, returning an array of arrays
44 of length "depth + 1", where the first "depth" elements correspond to flattened
45 columns and the last element contains the remaining object . For example:
83 [ 'I', 'A', 'i', { 'datum1': [ 1, 2 ], 'datum2': [ 3, 4 ] } ],
84 [ 'I', 'A', 'ii', { 'datum1': [ 3, 4 ] } ],
85 [ 'I', 'B', 'i', { 'datum1': [ 5, 6 ] } ],
86 [ 'I', 'B', 'ii', { 'datum1': [ 7, 8 ], 'datum2': [ 3, 4 ] } ],
87 [ 'I', 'B', 'iii', {} ],
88 [ 'II', 'A', 'i', { 'datum1': [ 1, 2 ], 'datum2': [ 3, 4 ] } ]
91 This function is strict: "depth" must be a non-negative integer and "obj" must
92 be a non-null object with at least "depth" levels of nesting under all keys.
95 ### flattenIter(obj, depth, func)
97 This is similar to `flattenObject` except that instead of returning an array,
98 this function invokes `func(entry)` for each `entry` in the array that
99 `flattenObject` would return. `flattenIter(obj, depth, func)` is logically
100 equivalent to `flattenObject(obj, depth).forEach(func)`. Importantly, this
101 version never constructs the full array. Its memory usage is O(depth) rather
102 than O(n) (where `n` is the number of flattened elements).
104 There's another difference between `flattenObject` and `flattenIter` that's
105 related to the special case where `depth === 0`. In this case, `flattenObject`
106 omits the array wrapping `obj` (which is regrettable).
111 Fetch nested property "key" from object "obj", traversing objects as needed.
112 For example, `pluck(obj, "foo.bar.baz")` is roughly equivalent to
113 `obj.foo.bar.baz`, except that:
115 1. If traversal fails, the resulting value is undefined, and no error is
116 thrown. For example, `pluck({}, "foo.bar")` is just undefined.
117 2. If "obj" has property "key" directly (without traversing), the
118 corresponding property is returned. For example,
119 `pluck({ 'foo.bar': 1 }, 'foo.bar')` is 1, not undefined. This is also
120 true recursively, so `pluck({ 'a': { 'foo.bar': 1 } }, 'a.foo.bar')` is
121 also 1, not undefined.
126 Returns an element from "array" selected uniformly at random. If "array" is
127 empty, throws an Error.
130 ### startsWith(str, prefix)
132 Returns true if the given string starts with the given prefix and false
136 ### endsWith(str, suffix)
138 Returns true if the given string ends with the given suffix and false
144 Converts a Date object to an ISO8601 date string of the form
145 "YYYY-MM-DDTHH:MM:SS.sssZ". This format is not customizable.
148 ### parseDateTime(str)
150 Parses a date expressed as a string, as either a number of milliseconds since
151 the epoch or any string format that Date accepts, giving preference to the
152 former where these two sets overlap (e.g., strings containing small numbers).
155 ### hrtimeDiff(timeA, timeB)
157 Given two hrtime readings (as from Node's `process.hrtime()`), where timeA is
158 later than timeB, compute the difference and return that as an hrtime. It is
159 illegal to invoke this for a pair of times where timeB is newer than timeA.
161 ### hrtimeAdd(timeA, timeB)
163 Add two hrtime intervals (as from Node's `process.hrtime()`), returning a new
164 hrtime interval array. This function does not modify either input argument.
167 ### hrtimeAccum(timeA, timeB)
169 Add two hrtime intervals (as from Node's `process.hrtime()`), storing the
170 result in `timeA`. This function overwrites (and returns) the first argument
174 ### hrtimeNanosec(timeA), hrtimeMicrosec(timeA), hrtimeMillisec(timeA)
176 This suite of functions converts a hrtime interval (as from Node's
177 `process.hrtime()`) into a scalar number of nanoseconds, microseconds or
178 milliseconds. Results are truncated, as with `Math.floor()`.
181 ### validateJsonObject(schema, object)
183 Uses JSON validation (via JSV) to validate the given object against the given
184 schema. On success, returns null. On failure, *returns* (does not throw) a
188 ### extraProperties(object, allowed)
190 Check an object for unexpected properties. Accepts the object to check, and an
191 array of allowed property name strings. If extra properties are detected, an
192 array of extra property names is returned. If no properties other than those
193 in the allowed list are present on the object, the returned array will be of
196 ### mergeObjects(provided, overrides, defaults)
198 Merge properties from objects "provided", "overrides", and "defaults". The
199 intended use case is for functions that accept named arguments in an "args"
200 object, but want to provide some default values and override other values. In
201 that case, "provided" is what the caller specified, "overrides" are what the
202 function wants to override, and "defaults" contains default values.
204 The function starts with the values in "defaults", overrides them with the
205 values in "provided", and then overrides those with the values in "overrides".
206 For convenience, any of these objects may be falsey, in which case they will be
207 ignored. The input objects are never modified, but properties in the returned
208 object are not deep-copied.
212 mergeObjects(undefined, { 'objectMode': true }, { 'highWaterMark': 0 })
216 { 'objectMode': true, 'highWaterMark': 0 }
221 { 'highWaterMark': 16, 'objectMode': 7 }, /* from caller */
222 { 'objectMode': true }, /* overrides */
223 { 'highWaterMark': 0 }); /* default */
227 { 'objectMode': true, 'highWaterMark': 16 }
232 Code should be "make check" clean. This target assumes that
233 [jsl](http://github.com/davepacheco/javascriptlint) and
234 [jsstyle](http://github.com/davepacheco/jsstyle) are on your path.
236 New tests should generally accompany new functions and bug fixes. The tests
237 should pass cleanly (run tests/basic.js).