immutable 3.7.2 → 3.7.6

package/README.md

@@ -86,7 +86,7 @@ Just add a reference with a relative path to the type declarations at the top
 of your file.
 
 ```javascript
-///<reference path='./node_modules/immutable/dist/Immutable.d.ts'/>
+///<reference path='./node_modules/immutable/dist/immutable.d.ts'/>
 import Immutable = require('immutable');
 var map1: Immutable.Map<string, number>;
 map1 = Immutable.Map({a:1, b:2, c:3});
@@ -116,18 +116,31 @@ and especially well with an application designed using the ideas of [Flux][].
 
 When data is passed from above rather than being subscribed to, and you're only
 interested in doing work when something has changed, you can use equality.
-`Immutable` always returns itself when a mutation results in an identical
-collection, allowing for using `===` equality to determine if something
-has changed.
+
+Immutable collections should be treated as *values* rather than *objects*. While
+objects represents some thing which could change over time, a value represents
+the state of that thing at a particular instance of time. This principle is most
+important to understanding the appropriate use of immutable data. In order to
+treat Immutable.js collections as values, it's important to use the
+`Immutable.is()` function or `.equals()` method to determine value equality
+instead of the `===` operator which determines object reference identity.
 
 ```javascript
 var map1 = Immutable.Map({a:1, b:2, c:3});
 var map2 = map1.set('b', 2);
-assert(map1 === map2); // no change
+assert(map1.equals(map2) === true);
 var map3 = map1.set('b', 50);
-assert(map1 !== map3); // change
+assert(map1.equals(map3) === false);
 ```
 
+Note: As a performance optimization `Immutable` attempts to return the existing
+collection when an operation would result in an identical collection, allowing
+for using `===` reference equality to determine if something definitely has not
+changed. This can be extremely useful when used within memoization function
+which would prefer to re-run the function if a deeper equality check could
+potentially be more costly. The `===` equality check is also used internally by
+`Immutable.is` and `.equals()` as a performance optimization.
+
 If an object is immutable, it can be "copied" simply by making another reference
 to it instead of copying the entire object. Because a reference is much smaller
 than the object itself, this results in memory savings and a potential boost in
@@ -209,6 +222,26 @@ Immutable.Seq(myObject).map(x => x * x).toObject();
 // { a: 1, b: 4, c: 9 }
 ```
 
+Keep in mind, when using JS objects to construct Immutable Maps, that
+JavaScript Object properties are always strings, even if written in a quote-less
+shorthand, while Immutable Maps accept keys of any type.
+
+```js
+var obj = { 1: "one" };
+Object.keys(obj); // [ "1" ]
+obj["1"]; // "one"
+obj[1];   // "one"
+
+var map = Immutable.fromJS(obj);
+map.get("1"); // "one"
+map.get(1);   // undefined
+```
+
+Property access for JavaScript Objects first converts the key to a string, but
+since Immutable Map keys can be of any type the argument to `get()` is
+not altered.
+
+
 ### Converts back to raw JavaScript objects.
 
 All `immutable` Iterables can be converted to plain JavaScript Arrays and
@@ -337,8 +370,9 @@ data, performing a deep equality check if necessary.
 ```javascript
 var map1 = Immutable.Map({a:1, b:1, c:1});
 var map2 = Immutable.Map({a:1, b:1, c:1});
-assert(map1 !== map2);
-assert(Immutable.is(map1, map2) === true);
+assert(map1 !== map2); // two different instances
+assert(Immutable.is(map1, map2)); // have equivalent values
+assert(map1.equals(map2)); // alternatively use the equals method
 ```
 
 `Immutable.is()` uses the same measure of equality as [Object.is][]
@@ -359,9 +393,9 @@ Batching Mutations
 > — Rich Hickey, Clojure
 
 Applying a mutation to create a new immutable object results in some overhead,
-which can add up to a performance penalty. If you need to apply a series of
-mutations locally before returning, `Immutable` gives you the ability to create
-a temporary mutable (transient) copy of a collection and apply a batch of
+which can add up to a minor performance penalty. If you need to apply a series
+of mutations locally before returning, `Immutable` gives you the ability to
+create a temporary mutable (transient) copy of a collection and apply a batch of
 mutations in a performant manner by using `withMutations`. In fact, this is
 exactly how  `Immutable` applies complex mutations itself.
 
@@ -381,6 +415,12 @@ Note: `immutable` also provides `asMutable` and `asImmutable`, but only
 encourages their use when `withMutations` will not suffice. Use caution to not
 return a mutable copy, which could result in undesired behavior.
 
+*Important!*: Only a select few methods can be used in `withMutations` including
+`set`, `push` and `pop`. These methods can be applied directly against a
+persistent data-structure where other methods like `map`, `filter`, `sort`,
+and `splice` will always return new immutable data-structures and never mutate
+a mutable collection.
+
 
 Documentation
 -------------

package/contrib/cursor/__tests__/Cursor.ts

@@ -354,4 +354,38 @@ describe('Cursor', () => {
     );
   });
 
+  it('can get Record value as a property', () => {
+    var User = Immutable.Record({ name: 'John' });
+    var users = Immutable.List.of(new User());
+    var data = Immutable.Map({'users': users});
+    var cursor = Cursor.from(data, ['users']);
+    expect(cursor.first().name).toBe('John');
+  });
+
+  it('can set value of a cursor directly', () => {
+    var onChange = jest.genMockFunction();
+    var data = Immutable.fromJS({a:1});
+    var c = Cursor.from(data, ['a'], onChange);
+    var c1 = c.set(2);
+    expect(c1.deref()).toBe(2);
+    expect(onChange).lastCalledWith(
+      Immutable.fromJS({a:2}),
+      data,
+      ['a']
+    );
+  });
+
+  it('can set value of a cursor to undefined directly', () => {
+    var onChange = jest.genMockFunction();
+    var data = Immutable.fromJS({a:1});
+    var c = Cursor.from(data, ['a'], onChange);
+    var c1 = c.set(undefined);
+    expect(c1.deref()).toBe(undefined);
+    expect(onChange).lastCalledWith(
+      Immutable.fromJS({a:undefined}),
+      data,
+      ['a']
+    );
+  });
+
 });

package/contrib/cursor/index.d.ts

@@ -91,8 +91,11 @@ declare module 'immutable/contrib/cursor' {
     /**
      * Sets `value` at `key` in the cursor, returning a new cursor to the same
      * point in the new data.
+     *
+     * If only one parameter is provided, it is set directly as the cursor's value.
      */
     set(key: any, value: any): Cursor;
+    set(value: any): Cursor;
 
     /**
      * Deletes `key` from the cursor, returning a new cursor to the same

package/contrib/cursor/index.js

@@ -20,6 +20,7 @@ var Iterable = Immutable.Iterable;
 var Iterator = Iterable.Iterator;
 var Seq = Immutable.Seq;
 var Map = Immutable.Map;
+var Record = Immutable.Record;
 
 
 function cursorFrom(rootData, keyPath, onChange) {
@@ -85,7 +86,11 @@ IndexedCursorPrototype.getIn = function(keyPath, notSetValue) {
 
 IndexedCursorPrototype.set =
 KeyedCursorPrototype.set = function(key, value) {
-  return updateCursor(this, function (m) { return m.set(key, value); }, [key]);
+  if(arguments.length === 1) {
+    return updateCursor(this, function() { return key; }, []);
+  } else {
+    return updateCursor(this, function (m) { return m.set(key, value); }, [key]);
+  }
 }
 
 IndexedCursorPrototype.push = function(/* values */) {
@@ -251,7 +256,34 @@ function makeCursor(rootData, keyPath, onChange, value) {
   }
   var size = value && value.size;
   var CursorClass = Iterable.isIndexed(value) ? IndexedCursor : KeyedCursor;
-  return new CursorClass(rootData, keyPath, onChange, size);
+  var cursor = new CursorClass(rootData, keyPath, onChange, size);
+
+  if (value instanceof Record) {
+    defineRecordProperties(cursor, value);
+  }
+
+  return cursor;
+}
+
+function defineRecordProperties(cursor, value) {
+  try {
+    value._keys.forEach(setProp.bind(undefined, cursor));
+  } catch (error) {
+    // Object.defineProperty failed. Probably IE8.
+  }
+}
+
+function setProp(prototype, name) {
+  Object.defineProperty(prototype, name, {
+    get: function() {
+      return this.get(name);
+    },
+    set: function(value) {
+      if (!this.__ownerID) {
+        throw new Error('Cannot set on an immutable record.');
+      }
+    }
+  });
 }
 
 function wrappedValue(cursor, keyPath, value) {