Skip to content

jim-coffey/dot-guard

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Jim Coffey
Mar 26, 2018
cfce9c2 · Mar 26, 2018

History

1 Commit
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018
Mar 26, 2018

Repository files navigation

Dot Guard CircleCI Build Status GitHub license

Safely access properites of an object via dot notation without worrying about cannot read property 'x' of undefined errors.

  • get - retrieve value of a property
  • set - set value of a property
  • has - check for existence of property
  • del - delete a property

All functions require minimum parameters of object, and propPath. (Set also requires a 'value' to set the property to).

Typical usage :

dotGuard.get({ foo: { bar: { val: 42 } } }, 'foo.bar.val'); would return 42.

dotGuard.get({ foo: { bar: { val: 42 } }, 'foo.baz.val'); would return undefined.

The propPath to the object property can be passed as a string, or an array of strings depending on requirements.

  1. 'prop1.prop2.prop3'
  2. ['prop1', 'prop2', 'prop3']

N.B. passing propPath as an array of strings, allows use of dot (.) in property keys e.g. ['prop.one', 'prop.two']

Err... don't pass an array, unless you've been decorating it with properties!

Requiring / Importing

Both formats below are supported :

  • var dotGuard = require('guard-dot'); // dotGuard.get(...)
  • import { dgGet, dgSet, dgHas, dgDel } from 'guard-dot'; // dgGet(...)

dotGuard.get / dgGet

dotGuard.get(obj, propPath[, fallBack])

Parameters :

  • obj : object you wish to retrieve value from e.g. { foo: { bar: 3 } }
  • propPath : string OR array of poperties to traverse e.g. 'foo.bar' OR ['foo', 'bar']
  • fallBack : [optional] default value to return if the value can not be retrieved from the object
import dotGuard from 'guard-dot';

dotGuard.get({ car: { make: 'Mercedes' } }, 'car.make')
//>> 'Mercedes'

dotGuard.get({ car: { make: 'Mercedes' } }, 'car.manufacturer);
//>> undefined

dotGuard.get({ car: { make: 'Mercedes' } }, 'car.model', 'Trabant')
//>> 'trabant'

dotGuard.get({ 'car.info': { make: 'Mercedes', model: 'C-class' } }, ['car.info', 'model']);
//>> 'C-class'

Returns value of fallBack, or undefined if parameters passed are invalid, or it fails.

dotGuard.set / dgSet

dotGuard.set(obj, propPath, value)

Will overwrite a pre-existing value, or create a path to a new value.

Parameters :

  • obj : object you wish to set value on e.g. { foo: { bar: 3 } }
  • propPath : string OR array of poperties to traverse e.g. 'foo.bar' OR ['foo', 'bar']
  • value : default value to return if the value can not be retrieved from the object
import { dgSet } from 'guard-dot';

let obj;

obj = {};
dgSet(obj, 'foo.bar', 42);
console.log(obj);
//>> { foo: { bar: 42 } }

obj = { prop1: {} };
dgSet(obj, ['prop1', 'prop2'], 42);
console.log(obj);
//>> { prop1: { prop2: 42 } }

obj = { key1: 0 }
dgSet(obj, 'key1', 42);
console.log(obj);
//>> { key1: 42 }

obj = 'wibble';
const result = dgSet(obj, 'key1', 'val1');
console.log(result);
//>> 'wibble'

Returns original object passed, if parameters are invalid.

dotGuard.has / dgHas

Checks for existence of a property and returns a boolean.

Can be used in conjunction with dgGet to distinguish between a non-existant property, and a property that exists with a value of undefined.

dotGuard.has(obj, propPath)

Parameters :

  • obj : object you wish to has value on e.g. { foo: { bar: 3 } }
  • propPath : string OR array of poperties to traverse e.g. 'foo.bar' OR ['foo', 'bar']
  • value : default value to return if the value can not be retrieved from the object
const dgHas = require('guard-dot').dgHas;

const obj = { foo: { bar: {} } };

dgHas(obj, 'foo.bar');
//>> true

dgHas(obj, 'foo.bar.prop');
//>> false

Returns boolean false if parameters passed are invalid, or it fails.

dotGuard.del / dgDel

dotGuard.del(obj, propPath, value)

Parameters :

  • obj : object you wish to del value on e.g. { foo: { bar: 3 } }
  • propPath : string OR array of poperties to traverse e.g. 'foo.bar' OR ['foo', 'bar']
import { dgDel } from 'guard-dot';

const obj = { prop1: { prop2: { prop3: 42 } } };

dgDel(obj, 'prop1.prop2.prop3');
console.log(obj);
//>> { prop1: { props2 {} } }

dgDel(obj, 'prop1.prop2');
console.log(obj);
//>> { prop1: {} }

const result = dgDel(obj, 'prop1.prop2');
console.log(result);
//>> { prop1: {} }
console.log(obj);
//>> { prop1: {} }

Returns original object passed, if parameters are invalid.

About

Javascript safe object dot accessor methods

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published