handle javascript objects with ease ๐
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.
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: {} }
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 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 } } }
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);
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!' } }
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.
- mixed getProp( Object obj, String prop )
returns the properties value or undefined.
- Boolean setProp( Object obj, String prop, mixed val )
returns true if a change on obj
happened, false otherwise.
- Boolean delProp( Object obj, String prop )
returns true if a change on obj
happened, false otherwise.
- Object clone( Object obj )
returns a clone of obj
.
- mixed extend( Object that, Object obj )
returns an object containing all changed properties or undefined if no change on that
happened.
- Boolean equal( Object that, Object obj )
returns true if that
and obj
are equal (comparison is done recursively with strict equality).
- Clearify Browser support, publish on bower
- 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 jsdoc and insert into Readme
- jshint?, idea?
- Auto-generate markdown from benchmark results and insert into Readme
- More and better benchmarks
MIT ยฉ Sebastian Raff