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.
- attach extends an object (prototype) with the obj-ease functions (non-enumerable)(obj)
- split
Split str by . - supports backslash escaped delimiters(str) ⇒
Array.<string> - delProp
delete an objects property. supports nested properties through dot-notation, dots may be escaped by backslash.(obj, prop) ⇒
boolean - setProp
set an objects property. supports nested properties through dot-notation, dots may be escaped by backslash.(obj, prop, val) ⇒
boolean - getProp
get an objects property. supports nested properties through dot-notation, dots may be escaped by backslash(obj, prop) ⇒
all - equal
compare objects by value(obj1, obj2) ⇒
boolean - clone
clone obj(obj) ⇒
Object|Array - extend
extend that by obj. observes if a change happens while extending(that, obj) ⇒
undefined|Object
extends an object (prototype) with the obj-ease functions (non-enumerable)(obj) Kind: global function
| Param | Type | Description |
|---|---|---|
| obj | object |
object to extend |
Split str by . - supports backslash escaped delimiters(str) ⇒ Array.<string>
Kind: global function
| Param | Type |
|---|---|
| str | string |
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 |
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 |
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 |
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 obj(obj) ⇒ Object | Array
Kind: global function
Returns: Object | Array - the cloned object
| Param | Type |
|---|---|
| obj | Object | Array |
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 |
- 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
MIT © Sebastian Raff