BUMMER is a small script that helps easily and safely get, set, remove, replace or check an object's properties located at any depth.

const bummer = require('bummer');
const settings = require('./widget').settings();

// let axisFormat;
// if (settings.yAxis && settings.yAxis[0] && settings.yAxis[0].labels) {
//   axisFormat = settings.yAxis[0].labels.format;
// }
const axisFormat = bummer(settings).get('yAxis[0].labels.format').val();

if (axisFormat) {
  /*
    'settings.yAxis[1]' object may exist, or may not. Bummer script
    will create this path automaticaly.
  */
  bummer(settings).set('yAxis[1].labels.format', axisFormat);
}

Usage:

• bummer.get() - allows safely get a value from an object.

• bummer.set() - allows to set a value.

• bummer.check() - checks is a property exist or not.

• bummer.remove() - allows to delete a property from an object.

• bummer.replace() - allows to set up a new property, and returns an old one.

All these methods take two identical arguments first: subject and path, and always returns bummer_result object.

Caching:

bummer object is a function itself. It allows you to cache first argument, and only then call other methods. In this case you have to pass all the same arguments, but without first one. For example:

// const name = bummer.get(data, 'user.meta.name').val();
// const phone = bummer.get(data, 'user.meta.phone[0]').val();
const settings = bummer(data);
const name = settings.get('user.meta.name').val();
const phone = settngs.get('user.meta.phone[0]').val();

bummer.get()

bummer.get( subject, path )

Gets a value according to the given path.

Returns a bummer_result object, where:

• .value - A value placed by the given path. In case no path argument is provided, or in case the value doesn't exist (or equals to undefined) this field will be equal to undefined too.

• .done equals true in case the path fully exist. Otherwise, it equals false.

Example:

const sub = {
  user: {
    name: 'Guest',
    age: undefined,
  },
};
const name = bummer.get(sub, 'user.name');
const age = bummer.get(sub, 'user.age');
const phone = bummer.get(sub, 'user.meta.phone');

if (name.done) {
  console.log(name.val()); // > Guest
}
if (age.done) {
  console.log(name.val()); // > undefined
}
if (phone.done) {
  // Will never run because of phone.done === false
  console.log(phone.val()); // > undefined
}

bummer.set()

bummer.set( subject, path, value [, force ] )

• value<any> - Value you want to set.

• force<boolean> - Optional. true by default. Indicates whether the bummer should create a path (in case there are no neede objects on its way) or not.

Takes your value, and sets it up according to the given path. In case the force argument is omitted or set to true bummer will create all the needed objects on its way to the end of the path if some of them don't exist.
Note. If the force argument is omitted or true and one of the path keys is a number (even if it placed inside of a string, e.g.: string.path.to.value.0), and it is not the last path key, bummer will create an array for that key.

Returns a bummer_result object, where:

• .value equals to true (value was set up successfully) or false (bummer could not set up the value for some reason).

• .done - the same as the .value.

Example:

const data = {
  user: {
    name: 'Guest',
    age: undefined,
  },
};
bummer.set(data, 'user.name', 'Anonimous');
bummer.set(data, 'user.age', 35);
bummer.set(data, 'user.meta.phone[0]', '555-3141');

console.log(data.user);
// {
//   name: 'Anonimous',
//   age: 42,
//   meta: {
//     phone: [ '555-3141' ],
//   },
// }

bummer.check()

bummer.check( subject, path )

Returns a bummer_result object, where:

• .value equals to true (property exist) or false (it doesn't). Note that function doesn't take into account property value. It could be undefined .

• .done - the same as the .value.

Example:

const data = {
  name: 'Guest',
  phone: undefined,
};
if (bummer.check(data, 'name').val()) {
  console.log(data.name);   // > Guest
}
if (bummer.check(data, 'phone').val()) {
  console.log(data.phone);  // > undefined
}
if (bummer.check(data, 'address').val()) {
  console.log(data.address); // wont work
}

bummer.remove()

bummer.remove( subject, path, [, pop = false ] )

• pop<boolean> - Optional. false by default.

Returns a bummer_result object, where:

• .value is true (success) or false (fail). In case the pop argument was true, this field will be equal to the removed property value (or undefined).

Example:

const data = {
  name: 'Guest',
  age: 42,
};

bummer.remove(data, 'name').val(); // > true
bummer.remove(data, 'phone').val(); // > false
bummer.remove(data, 'age', true).val();  // > 42
bummer.remove(data, 'address', true).val(); // > undefined
console.log(data);  // > {}

bummer.replace()

bummer.replace( subject, path, value [, force = true ] )

Almost the same as bummer.get, but will return a previous property value (if exist) instead of true or false within bummer_result object.

• .value equals to true (value was set up successfully) or false (bummer could not set up the value for some reason).

• force<boolean> - Optional. true by default. Indicates whether the bummer should create a path (in case there are no neede objects on its way) or not.

Example:

const data = {
  name: 'Guest',
  age: 42,
};

const oldName = bummer.replace(data, 'name', 'Anonimous');
const oldStreet = bummer.replace(data, 'address.street', 'Oak');
const oldGender = bummer.replace(data, 'details.gender', 'Unicorn', false);

console.log(oldName.val()); // > Guest
console.log(oldStreet.val()); // > undefined
console.log(oldGender.val()); // > undefined
console.log(oldGender.done);  // > false
console.log(data);
// {
//   name: 'Anonimous',
//   age: 42,
//   address: {
//     street: 'Oak',
//   },
// }

<subject>

subject<object> - object (or an array) you want to work with.

<path>

path<key|key[]> (<key>) - path to the object's (subject) property you target to.

<key>

key<string|number|symbol> - string, number or symbol, which describes the object property (in case of string it could describe several keys):

• key<string> - describes the path to the property (for example some.path.to.the.property). The string has almost the same sintax as in javascript. The object key's should be separated by dots or they should be placed inside the square brackets. You musn't use quotes as in javascript. It is means that javascript object['propertyName'] is the same as bummer's object[propertyName]. If you will send to bummer object['propertyName'] string as the path, it will be the same as javascript object["'propertyName'"].

• key<number> - quite similar to the string type described before, and allows to get access to the array (or object) properties.

• key<symbol> - simply describes javascript symbol-key (the properties in javascript may be a symbols).

• key[] - contains ordered keys of any type described before. For example, the some.path.to.the.property is the same as ['some', 'path', 'to', 'the', 'property'], or even ['some.path', 'to', 'the[property]']. It is usefull in cases, when one of your properties is symbol type (e.g. ['users[0].permissions', sym, 'read']).

Escape character

In the case of a non-standard property name, you can use escape character /. NOTE: because of / symbol has used in javascript as an escape character too, you have to duplicate it when creating a string:

const data = { target: {} };
data.target['some.non-standard[name]'] = 42;

const answer = bummer(data).get('target.some//.non-standard//[name//]');
console.log(answer.val());  // > 42

<bummer_result>

bummer_object<object> - details of operation.

• .errors<string[]> - human-readable error messages, if there any during the operation.

• .done<boolean> - is the operation has finished successfully.

• .value - for different operations returns different values. For example for bummer.get() it would be the target property value. But for bummer.check() it would be a boolean value (is the target property exist or not).

• .val<() => any> - function, which simply returns the value. The same as bummer_object.value.

• .track<track_object[]> (<track_object>) - track details. One object for each key from the path (remember, that string-key may contain several path-keys).

<track_object>

track_object<object> - details of current step.

• .key<key> - the name of property for current step (could be any type of <key>.

• .exist<boolean> - is the needed property exist or not.

• .created<boolean> - is the property was created by the bummer.

• .available<boolean> - is the property exist, or was created.

• .target<object|null> - inspected object for current step.

• .value<any> - current-step value (target[key]).