290 lines
9.0 KiB
TypeScript
290 lines
9.0 KiB
TypeScript
/**
|
|
* Copyright (c) 2014-present, Facebook, Inc.
|
|
*
|
|
* This source code is licensed under the MIT license found in the
|
|
* LICENSE file in the root directory of this source tree.
|
|
*/
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
|
|
/// <reference path='../../dist/immutable.d.ts'/>
|
|
|
|
declare module __Cursor {
|
|
|
|
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.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;
|
|
}
|
|
|
|
}
|
|
|
|
declare module 'immutable/contrib/cursor' {
|
|
export = __Cursor
|
|
} |