Socket
Socket
Sign inDemoInstall

obj-ease

Package Overview
Dependencies
0
Maintainers
1
Versions
4
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

obj-ease


Version published
Weekly downloads
399
decreased by-18.24%
Maintainers
1
Created
Weekly downloads
 

Readme

Source

obj-ease

NPM version Dependency Status Build Status Coverage Status XO code style 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

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

objease

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

ParamTypeDescription
objobjectobject to extend

split

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

ParamType
strstring

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

ParamType
objObject
propstring

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

ParamType
objObject
propstring
valall

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

ParamType
objObject
propstring

equal

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

ParamType
obj1object
obj2object

clone

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

ParamType
objObject | 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

ParamType
thatObject
objObject

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

Keywords

FAQs

Last updated on 15 Sep 2017

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc