Update readme to include new instance withInheritedProperties

[Fix] Rename withOwnProperties to withInheritedProperties

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: {}});
  });