Warn about __proto__.

Author: moll

CHANGELOG.md

@@ -1,3 +1,6 @@
+## Unreleased
+- Adds info and warnings about JavaScript engines (e.g. V8) that have the non-standard (as of ECMAScript 5) `__proto__` property.
+
 ## 1.15.1 (Jul 21, 2016)
 - Fixes [`Oolong.create`][create] to not mutate the prototype argument under global strict mode when given objects to assign to it.  
   This affected only people running their JavaScript engine (like V8) under global strict mode (`--use-strict`), which seems very rare.

README.md

@@ -78,6 +78,47 @@ For extended documentation on all functions, please see the
 - [.values](https://github.com/moll/js-oolong/blob/master/doc/API.md#Oolong.values)(object)
 - [.wrap](https://github.com/moll/js-oolong/blob/master/doc/API.md#Oolong.wrap)(value, key)
 
+### <a id="__proto__"></a> Warning About `__proto__`
+Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto). Assigning to the `__proto__` property, even if done dynamically via `obj[key] = {foo: 42}` changes the object's _prototype_, rather than merely giving it a new property named `__proto__`. That also means if you've got an object with a plain `__proto__` property (like when parsing JSON) and pass it to Oolong's `assign`, it could inadvertently overwrite the target's prototype:
+
+```javascript
+var O = require("oolong")
+
+function Person(name) {
+  this.name = name
+}
+
+Person.prototype.greet = function() { return "Hi, " + this.name }
+
+var john = new Person("John")
+O.assign(john, JSON.parse("{\"__proto__\": {\"age\": 42}}"))
+john.name // => "John"
+john.age // => 42
+john.greet // => undefined
+```
+
+In other situations, like when you're merging two objects recursively with `merge`, this could cause the global prototype (`Object.prototype`) to be modified.
+
+As Oolong.js is written primarily for ECMAScript 5 compliant runtimes with no engine-specific workarounds, it doesn't have special handling for ignoring `__proto__`. Unfortunately, even if it did, the presence of such special properties is far too likely to cause issues elsewhere to make a difference. It's quite common to assign dynamic values to object keys, e.g. when indexing an array (by creating an object with keys as values). Fortunately, you can and should **disable `__proto__` globally** by overwriting it on the global `Object.prototype`:
+
+```javascript
+Object.defineProperty(Object.prototype, "__proto__", {
+  value: undefined, configurable: true, writable: true
+})
+```
+
+After overwriting `__proto__` on `Object.prototype`, assigning, merging or cloning objects with `__proto__` properties won't behave in any special manner. Assignments to `__proto__` will become regular property assignments:
+
+```javascript
+var john = new Person("John")
+O.assign(john, JSON.parse("{\"__proto__\": {\"age\": 42}}"))
+
+john.name // => "John"
+john.age // => undefined
+john.greet() // => "Hi, John"
+john.__proto__ // => {age: 42}
+```
+
 
 License
 -------

doc/API.md

@@ -52,6 +52,8 @@ Returns `target`.
 
 Think of it as _extending_ the first object step by step with others.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 Oolong.assign({name: "John"}, {age: 32}, {shirt: "blue"})
@@ -65,6 +67,8 @@ Returns `target`.
 
 Think of it as _extending_ the first object step by step with others.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 Oolong.assignOwn({name: "John"}, {age: 32}, Object.create({shirt: "blue"}))
@@ -76,6 +80,8 @@ Creates a shallow clone of the given object, taking all enumerable
 properties into account.  
 Shallow means if you've got nested objects, those will be shared.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 Oolong.clone({name: "John", age: 32})
@@ -86,6 +92,8 @@ Oolong.clone({name: "John", age: 32})
 Creates a deep clone of the given object, taking all enumerable properties
 into account.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 Oolong.cloneDeep({name: "John", attributes: {age: 42}})
@@ -99,6 +107,8 @@ Uses `Object.create` and [`Oolong.assign`](#Oolong.assign)
 internally.  
 Does not modify the given `prototype` nor source objects.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 var PERSON = {name: "Unknown", age: 0}
@@ -118,6 +128,8 @@ will be skipped. Usually that's not a problem, but if you want to use
 `Oolong.defaults` for hashmaps/dictionaries with unknown keys, ensure
 `target` inherits from `null` instead (use `Object.create(null)`).
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 var PERSON = {name: "Unknown", age: 0, shirt: "blue"}
@@ -380,6 +392,8 @@ a plain object. Does not modify anything in the source objects.
 
 Think of it as _extending_ the first object step by step with others.
 
+**Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+
 **Examples**:
 ```javascript
 var person = {name: "John", attributes: {age: 42}}
@@ -487,7 +501,7 @@ Set the prototype of the given object to the given prototype.
 Pass `null` or another object for the prototype.  
 Returns `object`.
 
-Uses `Object.setPrototypeOf` if it exists. Otherwise uses a polyfill.
+Uses `Object.setPrototypeOf` if it exists. Otherwise uses a polyfill that depends on the presence of the non-standard [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) property.
 
 **Examples**:
 ```javascript

index.js

@@ -18,6 +18,8 @@ var SET_PROTO_OF_NULL = "Oolong.setPrototypeOf called on null or undefined"
  *
  * Think of it as _extending_ the first object step by step with others.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * Oolong.assign({name: "John"}, {age: 32}, {shirt: "blue"})
  * // => {name: "John", age: 32, shirt: "blue"}
@@ -43,6 +45,8 @@ exports.assign = function assign(target) {
  *
  * Think of it as _extending_ the first object step by step with others.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * Oolong.assignOwn({name: "John"}, {age: 32}, Object.create({shirt: "blue"}))
  * // => {name: "John", age: 32}
@@ -66,6 +70,8 @@ exports.assignOwn = function assignOwn(target) {
  * properties into account.  
  * Shallow means if you've got nested objects, those will be shared.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * Oolong.clone({name: "John", age: 32})
  * // => {name: "John", age: 32}
@@ -82,6 +88,8 @@ exports.clone = function clone(obj) {
  * Creates a deep clone of the given object, taking all enumerable properties
  * into account.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * Oolong.cloneDeep({name: "John", attributes: {age: 42}})
  * // => {name: "John", attributes: {age: 42}}
@@ -101,6 +109,8 @@ exports.cloneDeep = function cloneDeep(obj) {
  * internally.  
  * Does not modify the given `prototype` nor source objects.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * var PERSON = {name: "Unknown", age: 0}
  * Oolong.create(PERSON, {name: "John"}, {shirt: "blue"})
@@ -128,6 +138,8 @@ exports.create = function create(obj) {
  * `Oolong.defaults` for hashmaps/dictionaries with unknown keys, ensure
  * `target` inherits from `null` instead (use `Object.create(null)`).
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * var PERSON = {name: "Unknown", age: 0, shirt: "blue"}
  * Oolong.defaults({name: "John", age: 42}, PERSON)
@@ -573,6 +585,8 @@ exports.mapKeys = function mapKeys(obj, fn, context) {
  *
  * Think of it as _extending_ the first object step by step with others.
  *
+ * **Warning**: Some JavaScript runtimes, notably V8 (used by Chrome and Node.js) support a nonstandard (as of ECMAScript 5) property called [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) that could cause unwanted behavior. Please see the [README](https://github.com/moll/js-oolong/blob/master/README.md#__proto__) for more details.
+ *
  * @example
  * var person = {name: "John", attributes: {age: 42}}
  * Oolong.merge(person, {attributes: {height: 190}})
@@ -777,7 +791,7 @@ exports.reject = function reject(obj, fn, context) {
  * Pass `null` or another object for the prototype.  
  * Returns `object`.
  *
- * Uses `Object.setPrototypeOf` if it exists. Otherwise uses a polyfill.
+ * Uses `Object.setPrototypeOf` if it exists. Otherwise uses a polyfill that depends on the presence of the non-standard [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) property.
  *
  * @example
  * var person = {name: "Unnamed", age: 42}