obj-ease

handle javascript objects with ease :surfer:

Purpose

get/set/delete properties by dot-notation, clone, extend and compare objects.

Why reinvent the wheel? There are more than enough modules solving the same problems!

Most of the implementations I found didn't suite my needs at 100% (e.g. useful return values, see below) and this module has also some educational purpose - I want to improve my js skills, so I would be glad and thankful to hear your opinion and critics on this implementation or - even better - get some pull requests that help to optimize performance, function, tooling, style and documentation of this module.

Usage Examples

var oe = require('obj-ease');

var obj1 = {a: {b: {c: true}}};
console.log(oe.getProp(obj1, 'a.b.c')); // true
console.log(oe.getProp(obj1, 'a.b.missing')); // undefined

var obj2 = oe.clone(obj1);
console.log(oe.equal(obj1, obj2)); // true

oe.setProp(obj2, 'a.b.c', false);
console.log(oe.equal(obj1, obj2)); // false
console.log(oe.getProp(obj1, 'a.b.c')); // true

oe.extend(obj1, {a: {b: {bla: 'blub'}}});
console.log(obj1); // { a: { b: { c: true, bla: 'blub' } } }

oe.setProp(obj1, 'a.b', {c: null});
console.log(obj1); // { a: { b: { c: null } } }

oe.delProp(obj1, 'a.b');
console.log(obj1); // { a: {} }

Advanced usage

Return values

setProp

setProp tells you if it really did a change on the object. So oe.setProp({a:1}, 'a', 1) will return false and oe.setProp({a:1}, 'a', 2) will return true.

extend

extend returns an object containing all properties that changed on the target or undefined if no change happened. So oe.extend({a: {b: {x: 1, y: 2}}}, {a: {b: {x: 1, y: 3}}}) will return { a: { b: { y: 3 } } }

alternative usage on objects

You can attach the methods of obj-ease as non-enumerable properties to an object or an object prototype:

var db = {};
require('obj-ease').attach(db);

db.setProp('a.b.c', 'test!');
console.log(db); // { a: { b: { c: 'test!' } } }

Obviously the first param of all methods has to be omitted if used on an object.

One could also extend Object.prototype (really?): require('obj-ease').attach(Object.prototype);

Escaping

You can access properties with dots in their names simply by escaping them with backslashes.

var oe = require('obj-ease');

oe.setProp(obj, 'key\\.containing\\.dots.key\\\\containing\\\\backslashes\\.and\\.dots', 'test!');
console.log(obj); // { 'key.containing.dots': { 'key\\containing\\backslashes.and.dots': 'test!' } }

Special Objects

This module works with Array and Buffer objects too.

Until now it can not handle Function objects (see Todo). Handling of Date and RegExp objects is untested also.

API

Classes

Functions

objease

Kind: global class

attach

extends an object (prototype) with the obj-ease functions (non-enumerable)(obj) Kind: global function

| Param | Type | Description | | --- | --- | --- | | obj | object | object to extend |

split

Split str by . - supports backslash escaped delimiters(str) ⇒ Array.<string> Kind: global function

| Param | Type | | --- | --- | | str | string |

delProp

delete an objects property. supports nested properties through dot-notation, dots may be escaped by backslash.(obj, prop) ⇒ boolean Kind: global function
Returns: boolean - - true if property was found and deleted

| Param | Type | | --- | --- | | obj | Object | | prop | string |

setProp

set an objects property. supports nested properties through dot-notation, dots may be escaped by backslash.(obj, prop, val) ⇒ boolean Kind: global function
Returns: boolean - - true if a change on obj happened

| Param | Type | | --- | --- | | obj | Object | | prop | string | | val | all |

getProp

get an objects property. supports nested properties through dot-notation, dots may be escaped by backslash(obj, prop) ⇒ all Kind: global function
Returns: all - the properties value or undefined

| Param | Type | | --- | --- | | obj | Object | | prop | string |

equal

compare objects by value(obj1, obj2) ⇒ boolean Kind: global function
Returns: boolean - true if both objects are equal

| Param | Type | | --- | --- | | obj1 | object | | obj2 | object |

clone

clone obj(obj) ⇒ Object | Array Kind: global function
Returns: Object | Array - the cloned object

| Param | Type | | --- | --- | | obj | Object | Array |

extend

extend that by obj. observes if a change happens while extending(that, obj) ⇒ undefined | Object Kind: global function
Returns: undefined | Object - undefined if no change happened - otherwise an object containing the changes is returned

| Param | Type | | --- | --- | | that | Object | | obj | Object |

Todo

• Handling of Date and RegExp objects
• Handle function objects in a useful manner
• Gulp task bumping version and publishing to npm and bower
• More and better tests
• Better Readme
• optimize get/set/delProp performance by integrated split method (could break prop string loop earlier)
• Auto-generate markdown from benchmark results and insert into Readme
• More and better benchmarks

License

MIT © Sebastian Raff