immutable 3.7.4 → 3.8.1

package/README.md

@@ -9,16 +9,21 @@ and change detection techniques with simple logic. [Persistent][] data presents
 a mutative API which does not update the data in-place, but instead always
 yields new updated data.
 
-`Immutable` provides Persistent Immutable `List`, `Stack`, `Map`, `OrderedMap`,
-`Set`, `OrderedSet` and `Record`. They are highly efficient on modern JavaScript
-VMs by using structural sharing via [hash maps tries][] and
-[vector tries][] as popularized by Clojure and Scala,
-minimizing the need to copy or cache data.
+Immutable.js provides many Persistent Immutable data structures including:
+`List`, `Stack`, `Map`, `OrderedMap`, `Set`, `OrderedSet` and `Record`.
+
+These data structures are highly efficient on modern JavaScript VMs by using
+structural sharing via [hash maps tries][] and [vector tries][] as popularized
+by Clojure and Scala, minimizing the need to copy or cache data.
 
 `Immutable` also provides a lazy `Seq`, allowing efficient
 chaining of collection methods like `map` and `filter` without creating
 intermediate representations. Create some `Seq` with `Range` and `Repeat`.
 
+Want to hear more? Watch the presentation about Immutable.js:
+
+<a href="https://youtu.be/I7IdS-PbEgI" target="_blank" alt="Immutable Data and React"><img src="https://img.youtube.com/vi/I7IdS-PbEgI/0.jpg" /></a>
+
 [Persistent]: http://en.wikipedia.org/wiki/Persistent_data_structure
 [Immutable]: http://en.wikipedia.org/wiki/Immutable_object
 [hash maps tries]: http://en.wikipedia.org/wiki/Hash_array_mapped_trie
@@ -46,7 +51,7 @@ map2.get('b'); // 50
 
 ### Browser
 
-To use `immutable` from a browser, download [dist/immutable.min.js](./dist/immutable.min.js)
+To use `immutable` from a browser, download [dist/immutable.min.js](https://github.com/facebook/immutable-js/blob/master/dist/immutable.min.js)
 or use a CDN such as [CDNJS](https://cdnjs.com/libraries/immutable)
 or [jsDelivr](http://www.jsdelivr.com/#!immutable.js).
 
@@ -86,7 +91,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});
@@ -103,8 +108,7 @@ Much of what makes application development difficult is tracking mutation and
 maintaining state. Developing with immutable data encourages you to think
 differently about how data flows through your application.
 
-Subscribing to data events throughout your application, by using
-`Object.observe`, or any other mechanism, creates a huge overhead of
+Subscribing to data events throughout your application creates a huge overhead of
 book-keeping which can hurt performance, sometimes dramatically, and creates
 opportunities for areas of your application to get out of sync with each other
 due to easy to make programmer error. Since immutable data never changes,
@@ -222,6 +226,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
@@ -414,6 +438,12 @@ Also, don't miss the [Wiki](https://github.com/facebook/immutable-js/wiki) which
 contains articles on specific topics. Can't find something? Open an [issue](https://github.com/facebook/immutable-js/issues).
 
 
+Testing
+-------
+
+If you are using the [Chai Assertion Library](http://chaijs.com/), [Chai Immutable](https://github.com/astorije/chai-immutable) provides a set of assertions to use against `Immutable` collections.
+
+
 Contribution
 ------------
 
@@ -435,7 +465,7 @@ Thanks
 and research in persistent data structures.
 
 [Hugh Jackson](https://github.com/hughfdjackson/), for providing the npm package
-name. If you're looking for his unsupported package, see [v1.4.1](https://www.npmjs.org/package/immutable/1.4.1).
+name. If you're looking for his unsupported package, see [this repository](https://github.com/hughfdjackson/immutable).
 
 
 License

package/contrib/cursor/__tests__/{Cursor.ts → Cursor.ts.skip}

@@ -7,14 +7,21 @@ jest.autoMockOff();
 import Immutable = require('immutable');
 import Cursor = require('immutable/contrib/cursor');
 
-jasmine.getEnv().addEqualityTester((a, b) =>
-  a instanceof Immutable.Iterable && b instanceof Immutable.Iterable ?
-    Immutable.is(a, b) :
-    jasmine.undefined
-);
-
 describe('Cursor', () => {
 
+  beforeEach(function () {
+    this.addMatchers({
+      toValueEqual: function (expected) {
+        var actual = this.actual;
+        if (!Immutable.is(expected, this.actual)) {
+          this.message = 'Expected\n' + this.actual + '\nto equal\n' + expected;
+          return false;
+        }
+        return true;
+      }
+    });
+  });
+
   var json = { a: { b: { c: 1 } } };
 
   it('gets from its path', () => {
@@ -60,7 +67,7 @@ describe('Cursor', () => {
     var data = Immutable.fromJS(json);
     var cursor = Cursor.from(data, ['a', 'b']);
     expect(cursor.toJS()).toEqual(json.a.b);
-    expect(cursor).toEqual(data.getIn(['a', 'b']));
+    expect(cursor).toValueEqual(data.getIn(['a', 'b']));
     expect(cursor.size).toBe(1);
     expect(cursor.get('c')).toBe(1);
   });
@@ -85,19 +92,17 @@ describe('Cursor', () => {
     // cursor edits return new cursors:
     var newDeepCursor = deepCursor.update(x => x + 1);
     expect(newDeepCursor.deref()).toBe(2);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:2}}}),
-      data,
-      ['a', 'b', 'c']
-    );
+    var call1 = onChange.mock.calls[0];
+    expect(call1[0]).toValueEqual(Immutable.fromJS({a:{b:{c:2}}}));
+    expect(call1[1]).toBe(data);
+    expect(call1[2]).toEqual(['a', 'b', 'c']);
 
     var newestDeepCursor = newDeepCursor.update(x => x + 1);
     expect(newestDeepCursor.deref()).toBe(3);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:3}}}),
-      Immutable.fromJS({a:{b:{c:2}}}),
-      ['a', 'b', 'c']
-    );
+    var call2 = onChange.mock.calls[1];
+    expect(call2[0]).toValueEqual(Immutable.fromJS({a:{b:{c:3}}}));
+    expect(call2[1]).toValueEqual(Immutable.fromJS({a:{b:{c:2}}}));
+    expect(call2[2]).toEqual(['a', 'b', 'c']);
 
     // meanwhile, data is still immutable:
     expect(data.toJS()).toEqual(json);
@@ -106,11 +111,10 @@ describe('Cursor', () => {
     expect(deepCursor.deref()).toBe(1);
     var otherNewDeepCursor = deepCursor.update(x => x + 10);
     expect(otherNewDeepCursor.deref()).toBe(11);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:11}}}),
-      data,
-      ['a', 'b', 'c']
-    );
+    var call3 = onChange.mock.calls[2];
+    expect(call3[0]).toValueEqual(Immutable.fromJS({a:{b:{c:11}}}));
+    expect(call3[1]).toBe(data);
+    expect(call3[2]).toEqual(['a', 'b', 'c']);
 
     // and update has been called exactly thrice.
     expect(onChange.mock.calls.length).toBe(3);
@@ -126,21 +130,19 @@ describe('Cursor', () => {
     // onChange returning undefined has no effect
     var newCursor = deepCursor.update(x => x + 1);
     expect(newCursor.deref()).toBe(2);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:2}}}),
-      data,
-      ['a', 'b', 'c']
-    );
+    var call1 = onChange.mock.calls[0];
+    expect(call1[0]).toValueEqual(Immutable.fromJS({a:{b:{c:2}}}));
+    expect(call1[1]).toBe(data);
+    expect(call1[2]).toEqual(['a', 'b', 'c']);
 
     onChange.mockReturnValueOnce(Immutable.fromJS({a:{b:{c:11}}}));
     // onChange returning something else has an effect
     newCursor = newCursor.update(x => 999);
     expect(newCursor.deref()).toBe(11);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:999}}}),
-      Immutable.fromJS({a:{b:{c:2}}}),
-      ['a', 'b', 'c']
-    );
+    var call2 = onChange.mock.calls[1];
+    expect(call2[0]).toValueEqual(Immutable.fromJS({a:{b:{c:999}}}));
+    expect(call2[1]).toValueEqual(Immutable.fromJS({a:{b:{c:2}}}));
+    expect(call2[2]).toEqual(['a', 'b', 'c']);
 
     // and update has been called exactly twice
     expect(onChange.mock.calls.length).toBe(2);
@@ -154,14 +156,14 @@ describe('Cursor', () => {
     var bCursor = aCursor.cursor('b');
     var cCursor = bCursor.cursor('c');
 
-    expect(bCursor.set('c', 10).deref()).toEqual(
+    expect(bCursor.set('c', 10).deref()).toValueEqual(
       Immutable.fromJS({ c: 10 })
     );
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({ a: { b: { c: 10 } } }),
-      data,
-      ['a', 'b', 'c']
-    );
+
+    var call1 = onChange.mock.calls[0];
+    expect(call1[0]).toValueEqual(Immutable.fromJS({a:{b:{c:10}}}));
+    expect(call1[1]).toBe(data);
+    expect(call1[2]).toEqual(['a', 'b', 'c']);
   });
 
   it('creates maps as necessary', () => {
@@ -169,7 +171,7 @@ describe('Cursor', () => {
     var cursor = Cursor.from(data, ['a', 'b', 'c']);
     expect(cursor.deref()).toBe(undefined);
     cursor = cursor.set('d', 3);
-    expect(cursor.deref()).toEqual(Immutable.Map({d: 3}));
+    expect(cursor.deref()).toValueEqual(Immutable.Map({d: 3}));
   });
 
   it('can set undefined', () => {
@@ -183,7 +185,7 @@ describe('Cursor', () => {
   it('has the sequence API', () => {
     var data = Immutable.Map({a: 1, b: 2, c: 3});
     var cursor = Cursor.from(data);
-    expect(cursor.map((x: number) => x * x)).toEqual(Immutable.Map({a: 1, b: 4, c: 9}));
+    expect(cursor.map((x: number) => x * x)).toValueEqual(Immutable.Map({a: 1, b: 4, c: 9}));
   });
 
   it('can push values on a List', () => {
@@ -191,12 +193,12 @@ describe('Cursor', () => {
     var data = Immutable.fromJS({a: {b: [0, 1, 2]}});
     var cursor = Cursor.from(data, ['a', 'b'], onChange);
 
-    expect(cursor.push(3,4)).toEqual(Immutable.List([0, 1, 2, 3, 4]));
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a: {b: [0, 1, 2, 3, 4]}}),
-      data,
-      ['a', 'b']
-    );
+    expect(cursor.push(3,4)).toValueEqual(Immutable.List([0, 1, 2, 3, 4]));
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a: {b: [0, 1, 2, 3, 4]}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b']);
   });
 
   it('can pop values of a List', () => {
@@ -204,12 +206,12 @@ describe('Cursor', () => {
     var data = Immutable.fromJS({a: {b: [0, 1, 2]}});
     var cursor = Cursor.from(data, ['a', 'b'], onChange);
 
-    expect(cursor.pop()).toEqual(Immutable.List([0, 1]));
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a: {b: [0, 1]}}),
-      data,
-      ['a', 'b']
-    );
+    expect(cursor.pop()).toValueEqual(Immutable.List([0, 1]));
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a: {b: [0, 1]}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b']);
   });
 
   it('can unshift values on a List', () => {
@@ -217,12 +219,12 @@ describe('Cursor', () => {
     var data = Immutable.fromJS({a: {b: [0, 1, 2]}});
     var cursor = Cursor.from(data, ['a', 'b'], onChange);
 
-    expect(cursor.unshift(-2, -1)).toEqual(Immutable.List([-2, -1, 0, 1, 2]));
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a: {b: [-2, -1, 0, 1, 2]}}),
-      data,
-      ['a', 'b']
-    );
+    expect(cursor.unshift(-2, -1)).toValueEqual(Immutable.List([-2, -1, 0, 1, 2]));
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a: {b: [-2, -1, 0, 1, 2]}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b']);
   });
 
   it('can shift values of a List', () => {
@@ -230,12 +232,12 @@ describe('Cursor', () => {
     var data = Immutable.fromJS({a: {b: [0, 1, 2]}});
     var cursor = Cursor.from(data, ['a', 'b'], onChange);
 
-    expect(cursor.shift()).toEqual(Immutable.List([1, 2]));
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a: {b: [1, 2]}}),
-      data,
-      ['a', 'b']
-    );
+    expect(cursor.shift()).toValueEqual(Immutable.List([1, 2]));
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a: {b: [1, 2]}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b']);
   });
 
 
@@ -247,11 +249,11 @@ describe('Cursor', () => {
     var found = cursor.find(map => map.get('v') === 2);
     expect(typeof found.deref).toBe('function'); // is a cursor!
     found = found.set('v', 20);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a: {v: 1}, b: {v: 20}, c: {v: 3}}),
-      data,
-      ['b', 'v']
-    );
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a: {v: 1}, b: {v: 20}, c: {v: 3}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['b', 'v']);
   });
 
   it('returns wrapped values for iteration API', () => {
@@ -309,7 +311,7 @@ describe('Cursor', () => {
     var c2 = c1.withMutations(m => m.set('x', 1).set('y', 2).set('z', 3));
 
     expect(c1.deref()).toEqual(undefined);
-    expect(c2.deref()).toEqual(Immutable.fromJS(
+    expect(c2.deref()).toValueEqual(Immutable.fromJS(
       { x: 1, y: 2, z: 3 }
     ));
     expect(onChange.mock.calls.length).toBe(1);
@@ -334,11 +336,11 @@ describe('Cursor', () => {
     var c = Cursor.from(data, ['a'], onChange);
     var c1 = c.updateIn(['b', 'c'], x => x * 10);
     expect(c1.getIn(['b', 'c'])).toBe(10);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:10}}}),
-      data,
-      ['a', 'b', 'c']
-    );
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a:{b:{c:10}}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b', 'c']);
   });
 
   it('can set deeply', () => {
@@ -347,11 +349,11 @@ describe('Cursor', () => {
     var c = Cursor.from(data, ['a'], onChange);
     var c1 = c.setIn(['b', 'c'], 10);
     expect(c1.getIn(['b', 'c'])).toBe(10);
-    expect(onChange).lastCalledWith(
-      Immutable.fromJS({a:{b:{c:10}}}),
-      data,
-      ['a', 'b', 'c']
-    );
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a:{b:{c:10}}}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a', 'b', 'c']);
   });
 
   it('can get Record value as a property', () => {
@@ -362,4 +364,30 @@ describe('Cursor', () => {
     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);
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a:2}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['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);
+
+    var call = onChange.mock.calls[0];
+    expect(call[0]).toValueEqual(Immutable.fromJS({a:undefined}));
+    expect(call[1]).toBe(data);
+    expect(call[2]).toEqual(['a']);
+  });
+
 });

package/contrib/cursor/index.d.ts

@@ -35,11 +35,9 @@
  * update the rest of your application.
  */
 
-declare module 'immutable/contrib/cursor' {
-
-  ///<reference path='../../dist/immutable.d.ts'/>
-  import Immutable = require('immutable');
+/// <reference path='../../dist/immutable.d.ts'/>
 
+declare module __Cursor {
 
   export function from(
     collection: Immutable.Collection<any, any>,
@@ -91,8 +89,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
@@ -286,3 +287,7 @@ declare module 'immutable/contrib/cursor' {
   }
 
 }
+
+declare module 'immutable/contrib/cursor' {
+  export = __Cursor
+}

package/contrib/cursor/index.js

@@ -15,7 +15,7 @@
  * If you wish to use it in the browser, please check out Browserify or WebPack!
  */
 
-var Immutable = require('immutable');
+var Immutable = require('../../');
 var Iterable = Immutable.Iterable;
 var Iterator = Iterable.Iterator;
 var Seq = Immutable.Seq;
@@ -86,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 */) {