index.d.ts
9.0 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
/**
* 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
}