Skip to content

Commit 995a00d

Browse files
leebyronleebyron
committed
Cursor is no longer a separate type.
Map#cursor() and Vector#cursor() now return fully typed collections.
1 parent 18f77ce commit 995a00d

File tree

2 files changed

+158
-262
lines changed

2 files changed

+158
-262
lines changed

‎dist/Immutable.d.ts

+79-131
Original file line numberDiff line numberDiff line change
@@ -515,7 +515,7 @@ declare module 'immutable' {
515515
/**
516516
* Returns the value found by following a key path through nested sequences.
517517
*/
518-
getIn(searchKeyPath: Array<K>, notSetValue?: V): V;
518+
getIn(searchKeyPath: Array<any>, notSetValue?: any): any;
519519

520520
/**
521521
* Returns a `Sequence` of `Sequences`, grouped by the return value of the
@@ -1186,24 +1186,6 @@ declare module 'immutable' {
11861186
*/
11871187
clear(): Map<K, V>;
11881188

1189-
/**
1190-
* When this cursor's (or any of its sub-cursors') `update` method is called,
1191-
* the resulting new data structure will be provided to the `onChange`
1192-
* function. Use this callback to keep track of the most current value or
1193-
* update the rest of your application.
1194-
*/
1195-
cursor(
1196-
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, keyPath?: Array<any>) => void
1197-
): Cursor<Map<K, V>>;
1198-
cursor(
1199-
keyPath: Array<any>,
1200-
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, keyPath?: Array<any>) => void
1201-
): Cursor<any>;
1202-
cursor(
1203-
key: K,
1204-
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, keyPath?: Array<any>) => void
1205-
): Cursor<V>;
1206-
12071189
/**
12081190
* Returns a new Map having updated the value at this `key` with the return
12091191
* value of calling `updater` with the existing value, or `notSetValue` if
@@ -1343,6 +1325,69 @@ declare module 'immutable' {
13431325
* copy has become immutable and can be safely returned from a function.
13441326
*/
13451327
asImmutable(): Map<K, V>;
1328+
1329+
/**
1330+
* Cursors allow you to hold a reference to a path in a nested immutable
1331+
* data structure, allowing you to pass smaller sections of a larger nested
1332+
* collection to portions of your application while maintaining a central
1333+
* point aware of changes to the entire data structure.
1334+
*
1335+
* This is particularly useful when used in conjuction with component-based
1336+
* UI libraries like [React](http://facebook.github.io/react/) or to
1337+
* simulate "state" throughout an application while maintaining a single
1338+
* flow of logic.
1339+
*
1340+
* Cursors provide a simple API for getting the value at that path
1341+
* (the equivalent of `this.getIn(keyPath)`), updating the value at that
1342+
* path (the equivalent of `this.updateIn(keyPath)`), and getting a
1343+
* sub-cursor starting from that path.
1344+
*
1345+
* When updated, a new root collection is created and provided to the
1346+
* `onChange` function provided to the first call to `map.cursor(...)`. Use
1347+
* this callback to keep track of the most current value or update the rest
1348+
* of your application.
1349+
*
1350+
* Cursors assume the type of the data they point to. For example:
1351+
*
1352+
* var map = Immutable.Map({ x: Immutable.Vector(1, 2, 3) });
1353+
* assert(map.cursor('x') instanceof Immutable.Vector);
1354+
*
1355+
* A cursor to a value that is not an Immutable Sequence simply returns that
1356+
* value, any edits to which are not tracked:
1357+
*
1358+
* var mapToJSArray = Immutable.Map({ x: [1, 2, 3] });
1359+
* var jsArray = mapToJSArray.cursor('x');
1360+
* assert(Array.is(jsArray));
1361+
*
1362+
* The `onChange` callback is invoked whenever an edit occurs on the cursor,
1363+
* it is provided the new value, the previous value, and a key-path
1364+
* illustrating where the change occurred.
1365+
*
1366+
* var map = Immutable.fromJS({ a: { b: { x: 1, y: 2 } } });
1367+
* var ab = map.cursor(['a', 'b'], function (newValue, oldValue, path) {
1368+
* map = newValue;
1369+
* console.log('New:', newValue);
1370+
* console.log('Old:', oldValue);
1371+
* console.log('Path:', path);
1372+
* });
1373+
* ab = ab.set('y', 10);
1374+
* // New: Map { a: Map { b: Map { x: 1, y: 10 } } }
1375+
* // Old: Map { a: Map { b: Map { x: 1, y: 2 } } }
1376+
* // Path: [ 'a', 'b', 'y' ]
1377+
* console.log(ab); // Map { x: 1, y: 10 }
1378+
*
1379+
*/
1380+
cursor(
1381+
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, changePath?: Array<any>) => void
1382+
): Map<K, V>;
1383+
cursor(
1384+
keyPath: Array<any>,
1385+
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, changePath?: Array<any>) => void
1386+
): any;
1387+
cursor(
1388+
key: K,
1389+
onChange?: (newValue: Map<K, V>, oldValue?: Map<K, V>, changePath?: Array<any>) => void
1390+
): V;
13461391
}
13471392

13481393

@@ -1660,22 +1705,6 @@ declare module 'immutable' {
16601705
*/
16611706
shift(): Vector<T>;
16621707

1663-
/**
1664-
* @see Map.cursor
1665-
*/
1666-
cursor(
1667-
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, keyPath?: Array<any>) => void
1668-
): Cursor<Vector<T>>;
1669-
cursor(
1670-
keyPath: Array<any>,
1671-
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, keyPath?: Array<any>) => void
1672-
): Cursor<any>;
1673-
cursor(
1674-
key: number,
1675-
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, keyPath?: Array<any>) => void
1676-
): Cursor<T>;
1677-
1678-
16791708
/**
16801709
* Returns a new Vector with an updated value at `index` with the return
16811710
* value of calling `updater` with the existing value, or `notSetValue` if
@@ -1762,6 +1791,21 @@ declare module 'immutable' {
17621791
* @see `Map.prototype.asImmutable`
17631792
*/
17641793
asImmutable(): Vector<T>;
1794+
1795+
/**
1796+
* @see Map.cursor
1797+
*/
1798+
cursor(
1799+
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, changePath?: Array<any>) => void
1800+
): Vector<T>;
1801+
cursor(
1802+
keyPath: Array<any>,
1803+
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, changePath?: Array<any>) => void
1804+
): any;
1805+
cursor(
1806+
key: number,
1807+
onChange?: (newValue: Vector<T>, oldValue?: Vector<T>, changePath?: Array<any>) => void
1808+
): T;
17651809
}
17661810

17671811

@@ -1876,102 +1920,6 @@ declare module 'immutable' {
18761920
}
18771921

18781922

1879-
/**
1880-
* Cursors
1881-
* -------
1882-
*
1883-
* Cursors allow you to hold a reference to a path in a nested immutable data
1884-
* structure, allowing you to pass smaller sections of a larger nested
1885-
* collection to portions of your application while maintaining a central point
1886-
* aware of changes to the entire data structure.
1887-
*
1888-
* This is particularly useful when used in conjuction with component-based UI
1889-
* libraries like [React](http://facebook.github.io/react/) or to simulate
1890-
* "state" throughout an application while maintaining a single flow of logic.
1891-
*
1892-
* Cursors provide a simple API for getting the value at that path
1893-
* (the equivalent of `this.getIn(keyPath)`), updating the value at that path
1894-
* (the equivalent of `this.updateIn(keyPath)`), and getting a sub-cursor
1895-
* starting from that path.
1896-
*
1897-
* When updated, a new root collection is created and provided to the `onChange`
1898-
* function provided to the first call to `map.cursor(...)`.
1899-
*
1900-
* @see Map.cursor
1901-
*/
1902-
1903-
export interface Cursor<T> extends Sequence<any, any> {
1904-
1905-
/**
1906-
* Returns a sub-cursor following the key-path starting from this cursor.
1907-
*/
1908-
cursor(subKeyPath: Array<any>): Cursor<any>;
1909-
cursor(subKey: any): Cursor<any>;
1910-
1911-
/**
1912-
* Returns the value at the cursor, if the cursor path does not yet exist,
1913-
* returns `notSetValue`.
1914-
*/
1915-
deref(notSetValue?: T): T;
1916-
1917-
/**
1918-
* Returns the value at the `key` in the cursor, or `notSetValue` if it
1919-
* does not exist.
1920-
*
1921-
* If the key would return a collection, a new Cursor is returned.
1922-
*/
1923-
get(key: any, notSetValue?: any): any;
1924-
1925-
/**
1926-
* Returns the value at the `keyPath` in the cursor, or `notSetValue` if it
1927-
* does not exist.
1928-
*
1929-
* If the keyPath would return a collection, a new Cursor is returned.
1930-
*/
1931-
getIn(keyPath: Array<any>, notSetValue?: any): any;
1932-
1933-
/**
1934-
* Sets `value` at `key` in the cursor, returning a new cursor to the same
1935-
* point in the new data.
1936-
*/
1937-
set(key: any, value: any): Cursor<T>;
1938-
1939-
/**
1940-
* Deletes `key` from the cursor, returning a new cursor to the same
1941-
* point in the new data.
1942-
*
1943-
* Note: `delete` cannot be safely used in IE8
1944-
* @alias delete
1945-
*/
1946-
remove(key: any): Cursor<T>;
1947-
delete(key: any): Cursor<T>;
1948-
1949-
/**
1950-
* Clears the value at this cursor, returning a new cursor to the same
1951-
* point in the new data.
1952-
*/
1953-
clear(): Cursor<T>;
1954-
1955-
/**
1956-
* Updates the value in the data this cursor points to, triggering the
1957-
* callback for the root cursor and returning a new cursor pointing to the
1958-
* new data.
1959-
*/
1960-
update(updater: (value: T) => T): Cursor<T>;
1961-
update(key: any, updater: (value: any) => any): Cursor<T>;
1962-
update(key: any, notSetValue: any, updater: (value: any) => any): Cursor<T>;
1963-
1964-
1965-
/**
1966-
* Every time you call one of the above functions, a new immutable value is
1967-
* created and the callback is triggered. If you need to apply a series of
1968-
* mutations to a Cursor without triggering the callback repeatedly,
1969-
* `withMutations()` creates a temporary mutable copy of the value which
1970-
* can apply mutations in a highly performant manner. Afterwards the
1971-
* callback is triggered with the final value.
1972-
*/
1973-
withMutations(mutator: (mutable: T) => T): Cursor<T>;
1974-
}
19751923

19761924
// ES6 Iterator
19771925
export interface Iterator<T> {

0 commit comments

Comments
 (0)