Detect cycles during development

README.md

@@ -155,6 +155,18 @@ Immutable(new Square(2), {prototype: Square.prototype}).area();
 
 Beyond [the usual Object fare](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#Methods_of_Object_instances), the following methods have been added.
 
+### Stack overflow protection
+
+Currently you can't construct Immutable from an object with circular references. To protect from ugly stack overflows, we provide a simple protection during development. We stop at suspiciously deep stack level and [show an error message][deep].
+
+If your objects are deep, but not circular, you can increase this level from default `64`. For example:
+
+```javascript
+Immutable(deepObject, null, 256);
+```
+
+[deep]: https://github.com/rtfeldman/seamless-immutable/wiki/Deeply-nested-object-was-detected
+
 ### merge
 
 ```javascript

src/seamless-immutable.js

@@ -497,7 +497,7 @@
     return makeImmutable(obj, mutatingObjectMethods);
   }
 
-  function Immutable(obj, options) {
+  function Immutable(obj, options, stackRemaining) {
     if (isImmutable(obj)) {
       return obj;
     } else if (obj instanceof Array) {
@@ -512,9 +512,22 @@
           instantiatePlainObject : (function() { return Object.create(prototype); });
       var clone = instantiateEmptyObject();
 
+      if (process.env.NODE_ENV !== "production") {
+        /*jshint eqnull:true */
+        if (stackRemaining == null) {
+          stackRemaining = 64;
+        }
+        if (stackRemaining <= 0) {
+          throw new ImmutableError("Attempt to construct Immutable from a deeply nested object was detected." +
+            " Have you tried to wrap an object with circular references (e.g. React element)?" +
+            " See https://github.com/rtfeldman/seamless-immutable/wiki/Deeply-nested-object-was-detected for details.");
+        }
+        stackRemaining -= 1;
+      }
+
       for (var key in obj) {
         if (Object.getOwnPropertyDescriptor(obj, key)) {
-          clone[key] = Immutable(obj[key]);
+          clone[key] = Immutable(obj[key], undefined, stackRemaining);
         }
       }
 

test/Immutable.spec.js

@@ -98,6 +98,31 @@ var getTestUtils = require("./TestUtils.js");
           });
         });
       });
+
+      it("detects cycles", function() {
+        var obj = {};
+        obj.prop = obj;
+
+        if (config.id === 'prod') {
+          assert.throws(function() { Immutable(obj); }, RangeError);
+        } else {
+          assert.throws(function() { Immutable(obj); }, /deeply nested/);
+        }
+      });
+
+      it("can configure stackRemaining", function() {
+        var mutable = {bottom: true};
+        _.range(65).forEach(function() {
+          mutable = {prop: mutable};
+        });
+
+        if (config.id === 'prod') {
+          TestUtils.assertJsonEqual(mutable, Immutable(mutable));
+        } else {
+          assert.throws(function() { Immutable(mutable); }, /deeply nested/);
+          TestUtils.assertJsonEqual(mutable, Immutable(mutable, null, 66));
+        }
+      });
     });
   });
 });