https://github.com/hobbyquaker/obj-ease
handle javascript objects with ease :surfer:
https://github.com/hobbyquaker/obj-ease
clone compare extend javascript objects properties
Last synced: 5 months ago
JSON representation
handle javascript objects with ease :surfer:
- Host: GitHub
- URL: https://github.com/hobbyquaker/obj-ease
- Owner: hobbyquaker
- License: mit
- Created: 2016-02-11T14:39:50.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-05-01T14:55:24.000Z (over 8 years ago)
- Last Synced: 2025-08-28T03:24:41.413Z (5 months ago)
- Topics: clone, compare, extend, javascript, objects, properties
- Language: JavaScript
- Size: 25.4 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# obj-ease
[](http://badge.fury.io/js/obj-ease)
[](https://gemnasium.com/github.com/hobbyquaker/obj-ease)
[](https://travis-ci.org/hobbyquaker/obj-ease)
[](https://coveralls.io/github/hobbyquaker/obj-ease?branch=master)
[](https://github.com/sindresorhus/xo)
[![License][mit-badge]][mit-url]
[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat
[mit-url]: LICENSE
> 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
```Javascript
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:
```Javascript
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.
```Javascript
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
- 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
## 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](https://github.com/hobbyquaker)