object

Utilities for dealing with objects.

When requiring laxar, it is available as laxar.object.

Contents

Module Members

• extend
• options
• forEach
• path
• setPath
• deepClone
• deepFreeze

Module Members

extend( target, sources )

Copies the properties from a set of source objects over to the target object. Properties of sources later in the arguments list overwrite existing properties in the target and earlier source objects.

Parameters

Returns

options( obj, defaults )

Returns all properties from obj with missing properties completed from defaults. If obj is null or undefined, an empty object is automatically created. obj and defaults are not modified by this function. This is very useful for optional map arguments, resembling some kind of configuration.

Example:

object.options( { validate: true }, {
   validate: false,
   highlight: true
} );
// =>
// {
//    validate: true,
//    highlight: true
// }

Parameters

Returns

forEach( object, iteratorFunction )

Iterates over the keys of an object and calls the given iterator function for each entry. On each iteration the iterator function is passed the value, the key and the complete object as arguments. If object is an array, the native Array.prototype.forEach function is called and hence the keys are the numeric indices of the array.

Parameters

path( obj, thePath, optionalDefault )

Finds a property in a nested object structure by a given path. A path is a string of keys, separated by a dot from each other, used to traverse that object and find the value of interest. An additional default is returned, if otherwise the value would yield undefined.

Note that object.path must only be used in situations where all path segments are also valid JavaScript identifiers, and should never be used with user-specified paths:

• there is no mechanism to escape '.' in path segments; a dot always separates keys,
• an empty string as a path segment will abort processing and return the entire sub-object under the respective position. For historical reasons, the path interpretation differs from that performed by #setPath (see there).

Example:

object.path( { one: { two: 3 } }, 'one.two' ); // => 3
object.path( { one: { two: 3 } }, 'one.three' ); // => undefined
object.path( { one: { two: 3 } }, 'one.three', 42 ); // => 42
object.path( { one: { two: 3 } }, 'one.' ); // => { two: 3 }
object.path( { one: { two: 3 } }, '' ); // => { one: { two: 3 } }
object.path( { one: { two: 3 } }, '.' ); // => { one: { two: 3 } }

Parameters

Returns

setPath( obj, path, value )

Sets a property in a nested object structure at a given path to a given value. A path is a string of keys, separated by a dot from each other, used to traverse that object and find the place where the value should be set. Any missing subtrees along the path are created.

Note that object.path must only be used in situations where all path segments are also valid JavaScript identifiers, and should never be used with user-specified paths:

• there is no mechanism to escape '.' in path segments; a dot will always create separate keys,
• an empty string as a path segment will create an empty string key in the object graph where missing. For historical reasons, the path interpretation differs from that performed by #path (see there).

Example:

object.setPath( {}, 'name.first', 'Peter' ); // => { name: { first: 'Peter' } }
object.setPath( {}, 'pets.1', 'Hamster' ); // => { pets: [ null, 'Hamster' ] }
object.setPath( {}, '', 'Hamster' ); // => { '': 'Hamster' } }
object.setPath( {}, '.', 'Hamster' ); // => { '': { '': 'Hamster' } } }

Parameters

Returns

deepClone( object )

Returns a deep clone of the given object. Note that the current implementation is intended to be used for simple object literals only. There is no guarantee that cloning objects instantiated via constructor function works and cyclic references will lead to endless recursion.

Parameters

Returns

deepFreeze( obj, optionalRecursive )

Freezes an object, optionally recursively, in any browser capable of freezing objects. In any other browser this method simply returns its first value, i.e. is an identity operation.

Parameters

Returns