Namespace: access

just.access(objectnon-null, pathopt, handleropt, opts) → {*}

Accesses to a deep property in a new object (or object if mutate evals to `true`).
Source:
access.js, line 88

Parameters:

NameTypeDefaultDescription
object
objectThe base object.
path
[optional]		string[][path]The ordered keys.
handler
[optional]		just.access~handlerreturnValueA custom function.
opts
object

Properties

NameTypeDefaultDescription
mutate
[optional]		booleanfalseIf `true`, it will use the given object as the base object, otherwise it will copy all the owned properties to a new object.
override
[optional]		booleantrueIf `true`, and the current value is different to `null` or `undefined`, the function will throw a TypeError. If `false`, the current value will be overriden by an empty object if it's not an object nor `undefined`.

Throws:

If some property causes access problems.
Type
TypeError

Returns:

If handler is given: the returned value of that function, otherwise: the last value of path in the copied object.
Type
Any

Examples

Example 1: Accessing to some existent property
just.access({a: {b: {c: {d: 4}}}}, ['a', 'b', 'c', 'd'], function (currentObject, currentKey, hasProperty, path) {
    return hasProperty ? currentObject[currentKey] : null;
}); // returns 4.
Example 2: Accessing to some property with a non-JSON-like-object as a value
just.access({a: 1}, ['a', 'b', 'c']); // throws TypeError.
just.access({a: 1}, ['a', 'b', 'c'], null, {
    'override': true
}); // returns undefined.
// Doesn't throw because it replaces `1` with an empty object
// and keeps accessing to the next properties.
Example 3: Accessing to some non-existent property
var obj = {z: 1, prototype: [...]};
var newObj = just.access(obj, 'a.b.c'.split('.'), function (currentObject, currentKey, hasProperty, path) {

    if (!hasProperty) {
        currentObject[currentKey] = path.length;
    }

    // At this point:
    //     `obj` is {z: 1},
    //     `currentObject` has a value in `currentKey`,
    //     and `this` has all the added keys (even the ones modified in `currentObject`).
    return this;

}); // returns {z: 1, a: {b: {c: 3}}}

// if you want the prototype chain of obj, just copy it.
just.assign(newObj.prototype, obj.prototype);
Example 4: Modifying the base object
var obj = {a: {b: false}, b: {b: false}, prototype: [...]};

just.access(obj, 'a.b'.split('.'), function (currentObject, currentKey, hasProperty, path) {
    currentObject[currentKey] = 2;
}, true);

// now `obj` is {a: {a: true}, b: {b: true}, prototype: [...]}.

Type Definitions

handler(lastObjectnon-null, lastKey, hasProperty, path) → {*}

A function to call when just.access reaches the deep property of an object.
Source:
access.js, line 10
This:

just.access~handler_this

Parameters:
NameTypeDescription
lastObject
objectThe object containing the lastKey.
lastKey
stringThe last value given in path.
hasProperty
boolean`false` if some key of path was created, `true` otherwise.
path
string[]The given keys.
Returns:
The return value for the main function.
Type
Any

handler_this

The given object (if mutate evals to `true`) or a copy of each own property of the given object.
Source:
access.js, line 3
Type:

object