immutable 4.0.0-rc.1 → 4.0.0-rc.14

package/contrib/cursor/index.d.ts

@@ -1,290 +0,0 @@
-/**
- *  Copyright (c) 2014-2015, Facebook, Inc.
- *  All rights reserved.
- *
- *  This source code is licensed under the BSD-style license found in the
- *  LICENSE file in the root directory of this source tree. An additional grant
- *  of patent rights can be found in the PATENTS file in the same directory.
- */
-
-
-/**
- * Cursors
- * -------
- *
- * Cursors allow you to hold a reference to a path in a nested immutable data
- * structure, allowing you to pass smaller sections of a larger nested
- * 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
- * libraries like [React](http://facebook.github.io/react/) or to simulate
- * "state" throughout an application while maintaining a single flow of logic.
- *
- * Cursors provide a simple API for getting the value at that path
- * (the equivalent of `this.getIn(keyPath)`), updating the value at that path
- * (the equivalent of `this.updateIn(keyPath)`), and getting a sub-cursor
- * starting from that path.
- *
- * When updated, a new root collection is created and provided to the `onChange`
- * function provided to the first call to `Cursor(map, onChange)`.
- *
- * When this cursor's (or any of its sub-cursors') `update` method is called,
- * the resulting new data structure will be provided to the `onChange`
- * function. Use this callback to keep track of the most current value or
- * update the rest of your application.
- */
-
-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;
-
-  /**
-   * @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;
-
-  /**
-   * @ignore
-   */
-  map(fn: (v: any, k: any, c: this) => any): this;
-}

package/contrib/cursor/index.js

@@ -1,362 +0,0 @@
-/**
- *  Copyright (c) 2014-2015, Facebook, Inc.
- *  All rights reserved.
- *
- *  This source code is licensed under the BSD-style license found in the
- *  LICENSE file in the root directory of this source tree. An additional grant
- *  of patent rights can be found in the PATENTS file in the same directory.
- */
-
-/**
- * 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:
- *
- *     var Cursor = require('immutable/contrib/cursor');
- *
- * If you wish to use it in the browser, please check out Browserify or WebPack!
- */
-
-var Immutable = require('../../');
-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) {
-  if (arguments.length === 1) {
-    keyPath = [];
-  } else if (typeof keyPath === 'function') {
-    onChange = keyPath;
-    keyPath = [];
-  } else {
-    keyPath = valToKeyPath(keyPath);
-  }
-  return makeCursor(rootData, keyPath, onChange);
-}
-
-
-var KeyedCursorPrototype = Object.create(Seq.Keyed.prototype);
-var IndexedCursorPrototype = Object.create(Seq.Indexed.prototype);
-
-function KeyedCursor(rootData, keyPath, onChange, size) {
-  this.size = size;
-  this._rootData = rootData;
-  this._keyPath = keyPath;
-  this._onChange = onChange;
-}
-KeyedCursorPrototype.constructor = KeyedCursor;
-
-function IndexedCursor(rootData, keyPath, onChange, size) {
-  this.size = size;
-  this._rootData = rootData;
-  this._keyPath = keyPath;
-  this._onChange = onChange;
-}
-IndexedCursorPrototype.constructor = IndexedCursor;
-
-KeyedCursorPrototype.toString = function() {
-  return this.__toString('Cursor {', '}');
-}
-IndexedCursorPrototype.toString = function() {
-  return this.__toString('Cursor [', ']');
-}
-
-KeyedCursorPrototype.deref =
-KeyedCursorPrototype.valueOf =
-IndexedCursorPrototype.deref =
-IndexedCursorPrototype.valueOf = function(notSetValue) {
-  return this._rootData.getIn(this._keyPath, notSetValue);
-}
-
-KeyedCursorPrototype.get =
-IndexedCursorPrototype.get = function(key, notSetValue) {
-  return this.getIn([key], notSetValue);
-}
-
-KeyedCursorPrototype.getIn =
-IndexedCursorPrototype.getIn = function(keyPath, notSetValue) {
-  keyPath = listToKeyPath(keyPath);
-  if (keyPath.length === 0) {
-    return this;
-  }
-  var value = this._rootData.getIn(newKeyPath(this._keyPath, keyPath), NOT_SET);
-  return value === NOT_SET ? notSetValue : wrappedValue(this, keyPath, value);
-}
-
-IndexedCursorPrototype.set =
-KeyedCursorPrototype.set = function(key, value) {
-  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 */) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.push.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.pop = function() {
-  return updateCursor(this, function (m) {
-    return m.pop();
-  });
-}
-
-IndexedCursorPrototype.unshift = function(/* values */) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.unshift.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.shift = function() {
-  return updateCursor(this, function (m) {
-    return m.shift();
-  });
-}
-
-IndexedCursorPrototype.setIn =
-KeyedCursorPrototype.setIn = Map.prototype.setIn;
-
-KeyedCursorPrototype.remove =
-KeyedCursorPrototype['delete'] =
-IndexedCursorPrototype.remove =
-IndexedCursorPrototype['delete'] = function(key) {
-  return updateCursor(this, function (m) { return m.remove(key); }, [key]);
-}
-
-IndexedCursorPrototype.removeIn =
-IndexedCursorPrototype.deleteIn =
-KeyedCursorPrototype.removeIn =
-KeyedCursorPrototype.deleteIn = Map.prototype.deleteIn;
-
-KeyedCursorPrototype.clear =
-IndexedCursorPrototype.clear = function() {
-  return updateCursor(this, function (m) { return m.clear(); });
-}
-
-IndexedCursorPrototype.update =
-KeyedCursorPrototype.update = function(keyOrFn, notSetValue, updater) {
-  return arguments.length === 1 ?
-    updateCursor(this, keyOrFn) :
-    this.updateIn([keyOrFn], notSetValue, updater);
-}
-
-IndexedCursorPrototype.updateIn =
-KeyedCursorPrototype.updateIn = function(keyPath, notSetValue, updater) {
-  return updateCursor(this, function (m) {
-    return m.updateIn(keyPath, notSetValue, updater);
-  }, keyPath);
-}
-
-IndexedCursorPrototype.merge =
-KeyedCursorPrototype.merge = function(/*...iters*/) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.merge.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.mergeWith =
-KeyedCursorPrototype.mergeWith = function(merger/*, ...iters*/) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.mergeWith.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.mergeIn =
-KeyedCursorPrototype.mergeIn = Map.prototype.mergeIn;
-
-IndexedCursorPrototype.mergeDeep =
-KeyedCursorPrototype.mergeDeep = function(/*...iters*/) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.mergeDeep.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.mergeDeepWith =
-KeyedCursorPrototype.mergeDeepWith = function(merger/*, ...iters*/) {
-  var args = arguments;
-  return updateCursor(this, function (m) {
-    return m.mergeDeepWith.apply(m, args);
-  });
-}
-
-IndexedCursorPrototype.mergeDeepIn =
-KeyedCursorPrototype.mergeDeepIn = Map.prototype.mergeDeepIn;
-
-KeyedCursorPrototype.withMutations =
-IndexedCursorPrototype.withMutations = function(fn) {
-  return updateCursor(this, function (m) {
-    return (m || Map()).withMutations(fn);
-  });
-}
-
-KeyedCursorPrototype.cursor =
-IndexedCursorPrototype.cursor = function(subKeyPath) {
-  subKeyPath = valToKeyPath(subKeyPath);
-  return subKeyPath.length === 0 ? this : subCursor(this, subKeyPath);
-}
-
-/**
- * All iterables need to implement __iterate
- */
-KeyedCursorPrototype.__iterate =
-IndexedCursorPrototype.__iterate = function(fn, reverse) {
-  var cursor = this;
-  var deref = cursor.deref();
-  return deref && deref.__iterate ? deref.__iterate(
-    function (v, k) { return fn(wrappedValue(cursor, [k], v), k, cursor); },
-    reverse
-  ) : 0;
-}
-
-/**
- * All iterables need to implement __iterator
- */
-KeyedCursorPrototype.__iterator =
-IndexedCursorPrototype.__iterator = function(type, reverse) {
-  var deref = this.deref();
-  var cursor = this;
-  var iterator = deref && deref.__iterator &&
-    deref.__iterator(Iterator.ENTRIES, reverse);
-  return new Iterator(function () {
-    if (!iterator) {
-      return { value: undefined, done: true };
-    }
-    var step = iterator.next();
-    if (step.done) {
-      return step;
-    }
-    var entry = step.value;
-    var k = entry[0];
-    var v = wrappedValue(cursor, [k], entry[1]);
-    return {
-      value: type === Iterator.KEYS ? k : type === Iterator.VALUES ? v : [k, v],
-      done: false
-    };
-  });
-}
-
-KeyedCursor.prototype = KeyedCursorPrototype;
-IndexedCursor.prototype = IndexedCursorPrototype;
-
-
-var NOT_SET = {}; // Sentinel value
-
-function makeCursor(rootData, keyPath, onChange, value) {
-  if (arguments.length < 4) {
-    value = rootData.getIn(keyPath);
-  }
-  var size = value && value.size;
-  var CursorClass = Iterable.isIndexed(value) ? IndexedCursor : KeyedCursor;
-  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) {
-  return Iterable.isIterable(value) ? subCursor(cursor, keyPath, value) : value;
-}
-
-function subCursor(cursor, keyPath, value) {
-  if (arguments.length < 3) {
-    return makeCursor( // call without value
-      cursor._rootData,
-      newKeyPath(cursor._keyPath, keyPath),
-      cursor._onChange
-    );
-  }
-  return makeCursor(
-    cursor._rootData,
-    newKeyPath(cursor._keyPath, keyPath),
-    cursor._onChange,
-    value
-  );
-}
-
-function updateCursor(cursor, changeFn, changeKeyPath) {
-  var deepChange = arguments.length > 2;
-  var newRootData = cursor._rootData.updateIn(
-    cursor._keyPath,
-    deepChange ? Map() : undefined,
-    changeFn
-  );
-  var keyPath = cursor._keyPath || [];
-  var result = cursor._onChange && cursor._onChange.call(
-    undefined,
-    newRootData,
-    cursor._rootData,
-    deepChange ? newKeyPath(keyPath, changeKeyPath) : keyPath
-  );
-  if (result !== undefined) {
-    newRootData = result;
-  }
-  return makeCursor(newRootData, cursor._keyPath, cursor._onChange);
-}
-
-function newKeyPath(head, tail) {
-  return head.concat(listToKeyPath(tail));
-}
-
-function listToKeyPath(list) {
-  return Array.isArray(list) ? list : Immutable.Iterable(list).toArray();
-}
-
-function valToKeyPath(val) {
-  return Array.isArray(val) ? val :
-    Iterable.isIterable(val) ? val.toArray() :
-    [val];
-}
-
-exports.from = cursorFrom;