immutable 3.8.2 → 4.0.0-rc.12

package/contrib/cursor/README.md

@@ -1,3 +1,13 @@
+# DEPRECATED
+
+The Cursor API is deprecated and will be removed in a future major release.
+
+It is strongly suggested that you use the excellent `immutable-cursor` module
+which has an extremely similar API but is much higher quality.
+
+https://github.com/redbadger/immutable-cursor
+
+
 Cursors
 -------
 
@@ -7,8 +17,8 @@ collection to portions of your application while maintaining a central point
 aware of changes to the entire data structure: an `onChange` function which is
 called whenever a cursor or sub-cursor calls `update`.
 
-This is particularly useful when used in conjuction with component-based UI
-libraries like [React](http://facebook.github.io/react/) or to simulate
+This is particularly useful when used in conjunction with component-based UI
+libraries like [React](https://facebook.github.io/react/) or to simulate
 "state" throughout an application while maintaining a single flow of logic.
 
 

package/contrib/cursor/__tests__/Cursor.ts.skip

@@ -6,25 +6,20 @@
  */
 
 ///<reference path='../../../resources/jest.d.ts'/>
-///<reference path='../../../dist/immutable.d.ts'/>
-///<reference path='../index.d.ts'/>
 
-jest.autoMockOff();
-
-import Immutable = require('immutable');
-import Cursor = require('immutable/contrib/cursor');
+import * as Immutable from '../../../';
+import * as Cursor from '../';
 
 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;
+    jasmine.addMatchers({
+      toValueEqual: function(actual, expected) {
+        var passed = Immutable.is(actual, expected);
+        return {
+          pass: passed,
+          message: 'Expected ' + actual + (passed ? '' : ' not') + ' to equal ' + expected
+        };
       }
     });
   });

package/contrib/cursor/index.d.ts

@@ -14,7 +14,7 @@
  * collection to portions of your application while maintaining a central point
  * aware of changes to the entire data structure.
  *
- * This is particularly useful when used in conjuction with component-based UI
+ * This is particularly useful when used in conjunction with component-based UI
  * libraries like [React](http://facebook.github.io/react/) or to simulate
  * "state" throughout an application while maintaining a single flow of logic.
  *
@@ -32,259 +32,256 @@
  * update the rest of your application.
  */
 
-/// <reference path='../../dist/immutable.d.ts'/>
+import * as Immutable from '../../';
+
+export function from(
+  collection: Immutable.Collection<any, any>,
+  onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+): Cursor;
+export function from(
+  collection: Immutable.Collection<any, any>,
+  keyPath: Array<any>,
+  onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+): Cursor;
+export function from(
+  collection: Immutable.Collection<any, any>,
+  key: any,
+  onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+): Cursor;
+
+
+export interface Cursor extends Immutable.Iterable<any, any>, Immutable.Seq<any, any> {
+
+  /**
+   * Returns a sub-cursor following the key-path starting from this cursor.
+   */
+  cursor(subKeyPath: Array<any>): Cursor;
+  cursor(subKey: any): Cursor;
+
+  /**
+   * Returns the value at the cursor, if the cursor path does not yet exist,
+   * returns `notSetValue`.
+   */
+  deref(notSetValue?: any): any;
+
+  /**
+   * Returns the value at the `key` in the cursor, or `notSetValue` if it
+   * does not exist.
+   *
+   * If the key would return a collection, a new Cursor is returned.
+   */
+  get(key: any, notSetValue?: any): any;
+
+  /**
+   * Returns the value at the `keyPath` in the cursor, or `notSetValue` if it
+   * does not exist.
+   *
+   * If the keyPath would return a collection, a new Cursor is returned.
+   */
+  getIn(keyPath: Array<any>, notSetValue?: any): any;
+  getIn(keyPath: Immutable.Iterable<any, any>, notSetValue?: any): any;
+
+  /**
+   * 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
+   * point in the new data.
+   *
+   * Note: `delete` cannot be safely used in IE8
+   * @alias remove
+   */
+  delete(key: any): Cursor;
+  remove(key: any): Cursor;
+
+  /**
+   * Clears the value at this cursor, returning a new cursor to the same
+   * point in the new data.
+   */
+  clear(): Cursor;
+
+  /**
+   * Updates the value in the data this cursor points to, triggering the
+   * callback for the root cursor and returning a new cursor pointing to the
+   * new data.
+   */
+  update(updater: (value: any) => any): Cursor;
+  update(key: any, updater: (value: any) => any): Cursor;
+  update(key: any, notSetValue: any, updater: (value: any) => any): Cursor;
+
+  /**
+   * @see `Map#merge`
+   */
+  merge(...iterables: Immutable.Iterable<any, any>[]): Cursor;
+  merge(...iterables: {[key: string]: any}[]): Cursor;
+
+  /**
+   * @see `Map#mergeWith`
+   */
+  mergeWith(
+    merger: (previous?: any, next?: any) => any,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeWith(
+    merger: (previous?: any, next?: any) => any,
+    ...iterables: {[key: string]: any}[]
+  ): Cursor;
 
-declare module __Cursor {
+  /**
+   * @see `Map#mergeDeep`
+   */
+  mergeDeep(...iterables: Immutable.Iterable<any, any>[]): Cursor;
+  mergeDeep(...iterables: {[key: string]: any}[]): Cursor;
+
+  /**
+   * @see `Map#mergeDeepWith`
+   */
+  mergeDeepWith(
+    merger: (previous?: any, next?: any) => any,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeDeepWith(
+    merger: (previous?: any, next?: any) => any,
+    ...iterables: {[key: string]: any}[]
+  ): Cursor;
 
-  export function from(
-    collection: Immutable.Collection<any, any>,
-    onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+  // Deep persistent changes
+
+  /**
+   * Returns a new Cursor having set `value` at this `keyPath`. If any keys in
+   * `keyPath` do not exist, a new immutable Map will be created at that key.
+   */
+  setIn(keyPath: Array<any>, value: any): Cursor;
+  setIn(keyPath: Immutable.Iterable<any, any>, value: any): Cursor;
+
+  /**
+   * Returns a new Cursor with provided `values` appended
+   */
+  push(...values: Array<any>): Cursor;
+
+  /**
+   * Returns a new Cursor with a size ones less than this Cursor,
+   * excluding the last index in this Cursor.
+   */
+  pop(): Cursor;
+
+  /**
+   * Returns a new Cursor with the provided `values` prepended,
+   * shifting other values ahead to higher indices.
+   */
+  unshift(...values: Array<any>): Cursor;
+
+  /**
+   * Returns a new Cursor with a size ones less than this Cursor, excluding
+   * the first index in this Cursor, shifting all other values to a lower index.
+   */
+  shift(): Cursor;
+
+  /**
+   * Returns a new Cursor having removed the value at this `keyPath`.
+   *
+   * @alias removeIn
+   */
+  deleteIn(keyPath: Array<any>): Cursor;
+  deleteIn(keyPath: Immutable.Iterable<any, any>): Cursor;
+  removeIn(keyPath: Array<any>): Cursor;
+  removeIn(keyPath: Immutable.Iterable<any, any>): Cursor;
+
+  /**
+   * Returns a new Cursor having applied the `updater` to the value found at
+   * the keyPath.
+   *
+   * If any keys in `keyPath` do not exist, new Immutable `Map`s will
+   * be created at those keys. If the `keyPath` does not already contain a
+   * value, the `updater` function will be called with `notSetValue`, if
+   * provided, otherwise `undefined`.
+   *
+   * If the `updater` function returns the same value it was called with, then
+   * no change will occur. This is still true if `notSetValue` is provided.
+   */
+  updateIn(
+    keyPath: Array<any>,
+    updater: (value: any) => any
   ): Cursor;
-  export function from(
-    collection: Immutable.Collection<any, any>,
+  updateIn(
     keyPath: Array<any>,
-    onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+    notSetValue: any,
+    updater: (value: any) => any
   ): Cursor;
-  export function from(
-    collection: Immutable.Collection<any, any>,
-    key: any,
-    onChange?: (newValue: any, oldValue?: any, keyPath?: Array<any>) => any
+  updateIn(
+    keyPath: Immutable.Iterable<any, any>,
+    updater: (value: any) => any
+  ): Cursor;
+  updateIn(
+    keyPath: Immutable.Iterable<any, any>,
+    notSetValue: any,
+    updater: (value: any) => any
   ): Cursor;
 
+  /**
+   * A combination of `updateIn` and `merge`, returning a new Cursor, but
+   * performing the merge at a point arrived at by following the keyPath.
+   * In other words, these two lines are equivalent:
+   *
+   *     x.updateIn(['a', 'b', 'c'], abc => abc.merge(y));
+   *     x.mergeIn(['a', 'b', 'c'], y);
+   *
+   */
+  mergeIn(
+    keyPath: Immutable.Iterable<any, any>,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeIn(
+    keyPath: Array<any>,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeIn(
+    keyPath: Array<any>,
+    ...iterables: {[key: string]: any}[]
+  ): Cursor;
 
-  export interface Cursor extends Immutable.Seq<any, any> {
-
-    /**
-     * Returns a sub-cursor following the key-path starting from this cursor.
-     */
-    cursor(subKeyPath: Array<any>): Cursor;
-    cursor(subKey: any): Cursor;
-
-    /**
-     * Returns the value at the cursor, if the cursor path does not yet exist,
-     * returns `notSetValue`.
-     */
-    deref(notSetValue?: any): any;
-
-    /**
-     * Returns the value at the `key` in the cursor, or `notSetValue` if it
-     * does not exist.
-     *
-     * If the key would return a collection, a new Cursor is returned.
-     */
-    get(key: any, notSetValue?: any): any;
-
-    /**
-     * Returns the value at the `keyPath` in the cursor, or `notSetValue` if it
-     * does not exist.
-     *
-     * If the keyPath would return a collection, a new Cursor is returned.
-     */
-    getIn(keyPath: Array<any>, notSetValue?: any): any;
-    getIn(keyPath: Immutable.Iterable<any, any>, notSetValue?: any): any;
-
-    /**
-     * 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
-     * point in the new data.
-     *
-     * Note: `delete` cannot be safely used in IE8
-     * @alias remove
-     */
-    delete(key: any): Cursor;
-    remove(key: any): Cursor;
-
-    /**
-     * Clears the value at this cursor, returning a new cursor to the same
-     * point in the new data.
-     */
-    clear(): Cursor;
-
-    /**
-     * Updates the value in the data this cursor points to, triggering the
-     * callback for the root cursor and returning a new cursor pointing to the
-     * new data.
-     */
-    update(updater: (value: any) => any): Cursor;
-    update(key: any, updater: (value: any) => any): Cursor;
-    update(key: any, notSetValue: any, updater: (value: any) => any): Cursor;
-
-    /**
-     * @see `Map#merge`
-     */
-    merge(...iterables: Immutable.Iterable<any, any>[]): Cursor;
-    merge(...iterables: {[key: string]: any}[]): Cursor;
-
-    /**
-     * @see `Map#mergeWith`
-     */
-    mergeWith(
-      merger: (previous?: any, next?: any) => any,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeWith(
-      merger: (previous?: any, next?: any) => any,
-      ...iterables: {[key: string]: any}[]
-    ): Cursor;
-
-    /**
-     * @see `Map#mergeDeep`
-     */
-    mergeDeep(...iterables: Immutable.Iterable<any, any>[]): Cursor;
-    mergeDeep(...iterables: {[key: string]: any}[]): Cursor;
-
-    /**
-     * @see `Map#mergeDeepWith`
-     */
-    mergeDeepWith(
-      merger: (previous?: any, next?: any) => any,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeDeepWith(
-      merger: (previous?: any, next?: any) => any,
-      ...iterables: {[key: string]: any}[]
-    ): Cursor;
-
-    // Deep persistent changes
-
-    /**
-     * Returns a new Cursor having set `value` at this `keyPath`. If any keys in
-     * `keyPath` do not exist, a new immutable Map will be created at that key.
-     */
-    setIn(keyPath: Array<any>, value: any): Cursor;
-    setIn(keyPath: Immutable.Iterable<any, any>, value: any): Cursor;
-
-    /**
-     * Returns a new Cursor with provided `values` appended
-     */
-    push(...values: Array<any>): Cursor;
-
-    /**
-     * Returns a new Cursor with a size ones less than this Cursor,
-     * excluding the last index in this Cursor.
-     */
-    pop(): Cursor;
-
-    /**
-     * Returns a new Cursor with the provided `values` prepended,
-     * shifting other values ahead to higher indices.
-     */
-    unshift(...values: Array<any>): Cursor;
-
-    /**
-     * Returns a new Cursor with a size ones less than this Cursor, excluding
-     * the first index in this Cursor, shifting all other values to a lower index.
-     */
-    shift(): Cursor;
-
-    /**
-     * Returns a new Cursor having removed the value at this `keyPath`.
-     *
-     * @alias removeIn
-     */
-    deleteIn(keyPath: Array<any>): Cursor;
-    deleteIn(keyPath: Immutable.Iterable<any, any>): Cursor;
-    removeIn(keyPath: Array<any>): Cursor;
-    removeIn(keyPath: Immutable.Iterable<any, any>): Cursor;
-
-    /**
-     * Returns a new Cursor having applied the `updater` to the value found at
-     * the keyPath.
-     *
-     * If any keys in `keyPath` do not exist, new Immutable `Map`s will
-     * be created at those keys. If the `keyPath` does not already contain a
-     * value, the `updater` function will be called with `notSetValue`, if
-     * provided, otherwise `undefined`.
-     *
-     * If the `updater` function returns the same value it was called with, then
-     * no change will occur. This is still true if `notSetValue` is provided.
-     */
-    updateIn(
-      keyPath: Array<any>,
-      updater: (value: any) => any
-    ): Cursor;
-    updateIn(
-      keyPath: Array<any>,
-      notSetValue: any,
-      updater: (value: any) => any
-    ): Cursor;
-    updateIn(
-      keyPath: Immutable.Iterable<any, any>,
-      updater: (value: any) => any
-    ): Cursor;
-    updateIn(
-      keyPath: Immutable.Iterable<any, any>,
-      notSetValue: any,
-      updater: (value: any) => any
-    ): Cursor;
-
-    /**
-     * A combination of `updateIn` and `merge`, returning a new Cursor, but
-     * performing the merge at a point arrived at by following the keyPath.
-     * In other words, these two lines are equivalent:
-     *
-     *     x.updateIn(['a', 'b', 'c'], abc => abc.merge(y));
-     *     x.mergeIn(['a', 'b', 'c'], y);
-     *
-     */
-    mergeIn(
-      keyPath: Immutable.Iterable<any, any>,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeIn(
-      keyPath: Array<any>,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeIn(
-      keyPath: Array<any>,
-      ...iterables: {[key: string]: any}[]
-    ): Cursor;
-
-    /**
-     * A combination of `updateIn` and `mergeDeep`, returning a new Cursor, but
-     * performing the deep merge at a point arrived at by following the keyPath.
-     * In other words, these two lines are equivalent:
-     *
-     *     x.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y));
-     *     x.mergeDeepIn(['a', 'b', 'c'], y);
-     *
-     */
-    mergeDeepIn(
-      keyPath: Immutable.Iterable<any, any>,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeDeepIn(
-      keyPath: Array<any>,
-      ...iterables: Immutable.Iterable<any, any>[]
-    ): Cursor;
-    mergeDeepIn(
-      keyPath: Array<any>,
-      ...iterables: {[key: string]: any}[]
-    ): Cursor;
-
-    // Transient changes
-
-    /**
-     * Every time you call one of the above functions, a new immutable value is
-     * created and the callback is triggered. If you need to apply a series of
-     * mutations to a Cursor without triggering the callback repeatedly,
-     * `withMutations()` creates a temporary mutable copy of the value which
-     * can apply mutations in a highly performant manner. Afterwards the
-     * callback is triggered with the final value.
-     */
-    withMutations(mutator: (mutable: any) => any): Cursor;
-  }
+  /**
+   * A combination of `updateIn` and `mergeDeep`, returning a new Cursor, but
+   * performing the deep merge at a point arrived at by following the keyPath.
+   * In other words, these two lines are equivalent:
+   *
+   *     x.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y));
+   *     x.mergeDeepIn(['a', 'b', 'c'], y);
+   *
+   */
+  mergeDeepIn(
+    keyPath: Immutable.Iterable<any, any>,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeDeepIn(
+    keyPath: Array<any>,
+    ...iterables: Immutable.Iterable<any, any>[]
+  ): Cursor;
+  mergeDeepIn(
+    keyPath: Array<any>,
+    ...iterables: {[key: string]: any}[]
+  ): Cursor;
 
+  // Transient changes
+
+  /**
+   * Every time you call one of the above functions, a new immutable value is
+   * created and the callback is triggered. If you need to apply a series of
+   * mutations to a Cursor without triggering the callback repeatedly,
+   * `withMutations()` creates a temporary mutable copy of the value which
+   * can apply mutations in a highly performant manner. Afterwards the
+   * callback is triggered with the final value.
+   */
+  withMutations(mutator: (mutable: any) => any): Cursor;
+
+  /**
+   * @ignore
+   */
+  map(fn: (v: any, k: any, c: this) => any): this;
 }
-
-declare module 'immutable/contrib/cursor' {
-  export = __Cursor
-}

package/contrib/cursor/index.js

@@ -5,6 +5,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/**
+ * DEPRECATED
+ *
+ * The Cursor API is deprecated and will be removed in a future major release.
+ *
+ * It is strongly suggested that you use the excellent `immutable-cursor` module
+ * which has an extremely similar API but is much higher quality.
+ *
+ * https://github.com/redbadger/immutable-cursor
+ */
+typeof console === 'object' && console.warn && console.warn(
+  'The Cursor API is deprecated and will be removed in a future major release.\n' +
+  '\n' +
+  'It is strongly suggested that you use the excellent `immutable-cursor` module\n' +
+  'which has an extremely similar API but is much higher quality.\n' +
+  '\n' +
+  'https://github.com/redbadger/immutable-cursor\n' +
+);
+
 /**
  * Cursor is expected to be required in a node or other CommonJS context:
  *