Update readme to include new instance withInheritedProperties

[Fix] Rename withOwnProperties to withInheritedProperties

Author: mariocasciaro

README.md

@@ -14,11 +14,17 @@ Access deep properties using a path
 
 ## Changelog
 
+### 0.11.0
+
+* Introduce ability to specify options and create new instances of `object-path`
+* Introduce option to control the way `object-path` deals with inherited properties (`includeInheritedProps`)
+* New default `object-path` instance already configured to handle not-own object properties (`withInheritedProps`)
+
 ### 0.10.0
 
 * Improved performance of `get`, `set`, and `push` by 2x-3x
 * Introduced a benchmarking test suite
-* **BREAKING CHANGE**: `del`, `empty`, `set` will not affect not-own object's properties
+* **BREAKING CHANGE**: `del`, `empty`, `set` will not affect not-own object's properties (made them consistent with the other methods)
 
 ## Install
 
@@ -117,9 +123,49 @@ model.del("a.b"); // obj.a.b is now undefined
 model.has("a.b"); // false
 
 ```
-### Notes
+### How `object-path` deals with inherited properties
+
+By default `object-path` will only access an object's own properties. Look at the following example:
+
+```javascript
+var Obj = function() {};
+Obj.prototype.notOwn = {prop: 'a'};
+var obj = new Obj();
+
+//This will return undefined (or the default value you specified), because notOwn is
+//an inherited property
+objectPath.get(obj, 'notOwn.prop');
+
+//This will set the property on the obj instance and not the prototype.
+//In other words Obj.notOwn.prop === 'a' and obj.notOwn.prop === 'b'
+objectPath.set(obj, 'notOwn.prop', 'b');
+```
+To configure `object-path` to also deal with inherited properties, you need to create a new instance and specify
+the `includeInheritedProps = true` in the options object:
+
+```javascript
+var objectPath = require("object-path");
+var objectPathWithInheritedProps = objectPath.create({includeInheritedProps: true})
+```
+
+Alternatively, `object-path` exposes an instance already configured to handle inherited properties (`objectPath.withInheritedProps`):
+```javascript
+var objectPath = require("object-path");
+var objectPathWithInheritedProps = objectPath.withInheritedProps
+```
+
+Once you have the new instance, you can access inherited properties as you access other properties:
+```javascript
+var Obj = function() {};
+Obj.prototype.notOwn = {prop: 'a'};
+var obj = new Obj();
 
-`object-path` is intentionally designed to access only an object's own properties
+//This will return 'a'
+objectPath.withInheritedProps.get(obj, 'notOwn.prop');
+
+//This will set Obj.notOwn.prop to 'b'
+objectPath.set(obj, 'notOwn.prop', 'b');
+```
 
 ### Immutability
 

index.js

@@ -79,7 +79,7 @@
     };
 
     function getShallowProperty(obj, prop) {
-      if(options.includeOwnProperties || (typeof prop === 'number' && Array.isArray(obj)) || obj.hasOwnProperty(prop)) {
+      if(options.includeInheritedProps || (typeof prop === 'number' && Array.isArray(obj)) || obj.hasOwnProperty(prop)) {
         return obj[prop];
       }
     }
@@ -133,7 +133,7 @@
       for (var i = 0; i < path.length; i++) {
         var j = getKey(path[i]);
         if((typeof j === 'number' && isArray(obj) && j < obj.length) ||
-          (options.includeOwnProperties ? (j in Object(obj)) : _hasOwnProperty.call(obj, j))) {
+          (options.includeInheritedProps ? (j in Object(obj)) : _hasOwnProperty.call(obj, j))) {
           obj = obj[j];
         } else {
           return false;
@@ -284,6 +284,6 @@
 
   var mod = factory();
   mod.create = factory;
-  mod.withOwnProperties = factory({includeOwnProperties: true})
+  mod.withInheritedProps = factory({includeInheritedProps: true})
   return mod;
 });

test.js

@@ -835,7 +835,7 @@ describe('Access own properties [optional]', function () {
     Obj.prototype.notOwn = {a: 'a'};
     var obj = new Obj();
 
-    expect(objectPath.withOwnProperties.get(obj, 'notOwn.a')).to.be.equal('a')
+    expect(objectPath.withInheritedProps.get(obj, 'notOwn.a')).to.be.equal('a')
   });
 
   it('should set a deep not own property on the prototype (if exists)', function() {
@@ -844,7 +844,7 @@ describe('Access own properties [optional]', function () {
     }
     var obj = Object.create(proto)
 
-    objectPath.withOwnProperties.set(obj, 'notOwn.test', 'a');
+    objectPath.withInheritedProps.set(obj, 'notOwn.test', 'a');
     expect(obj.notOwn.test).to.be.equal('a');
     expect(proto.notOwn).to.be.deep.equal({test: 'a'});
   });
@@ -856,8 +856,8 @@ describe('Access own properties [optional]', function () {
     }
     var obj = Object.create(proto)
 
-    expect(objectPath.withOwnProperties.has(obj, 'notOwn')).to.be.true;
-    expect(objectPath.withOwnProperties.has(obj, 'notOwn.a')).to.be.true;
+    expect(objectPath.withInheritedProps.has(obj, 'notOwn')).to.be.true;
+    expect(objectPath.withInheritedProps.has(obj, 'notOwn.a')).to.be.true;
   });
 
   it('empty should empty a not own property', function() {
@@ -866,7 +866,7 @@ describe('Access own properties [optional]', function () {
     }
     var obj = Object.create(proto);
 
-    objectPath.withOwnProperties.empty(obj, 'notOwn');
+    objectPath.withInheritedProps.empty(obj, 'notOwn');
     expect(proto.notOwn).to.be.deep.equal({});
     expect(obj.notOwn).to.be.deep.equal({});
   });
@@ -877,10 +877,10 @@ describe('Access own properties [optional]', function () {
     }
     var obj = Object.create(proto);
 
-    objectPath.withOwnProperties.del(obj, 'notOwn.a');
+    objectPath.withInheritedProps.del(obj, 'notOwn.a');
     expect(proto.notOwn).to.be.deep.equal({});
     //expect(obj.notOwn).to.be.deep.equal({});
-    objectPath.withOwnProperties.del(obj, 'notOwn');
+    objectPath.withInheritedProps.del(obj, 'notOwn');
     //expect(proto).to.be.deep.equal({notOwn: {}});
     //expect(obj).to.be.deep.equal({notOwn: {}});
   });