immutable.d.ts (188590B)
1 /** 2 * Immutable data encourages pure functions (data-in, data-out) and lends itself 3 * to much simpler application development and enabling techniques from 4 * functional programming such as lazy evaluation. 5 * 6 * While designed to bring these powerful functional concepts to JavaScript, it 7 * presents an Object-Oriented API familiar to Javascript engineers and closely 8 * mirroring that of Array, Map, and Set. It is easy and efficient to convert to 9 * and from plain Javascript types. 10 * 11 * ## How to read these docs 12 * 13 * In order to better explain what kinds of values the Immutable.js API expects 14 * and produces, this documentation is presented in a statically typed dialect of 15 * JavaScript (like [Flow][] or [TypeScript][]). You *don't need* to use these 16 * type checking tools in order to use Immutable.js, however becoming familiar 17 * with their syntax will help you get a deeper understanding of this API. 18 * 19 * **A few examples and how to read them.** 20 * 21 * All methods describe the kinds of data they accept and the kinds of data 22 * they return. For example a function which accepts two numbers and returns 23 * a number would look like this: 24 * 25 * ```js 26 * sum(first: number, second: number): number 27 * ``` 28 * 29 * Sometimes, methods can accept different kinds of data or return different 30 * kinds of data, and this is described with a *type variable*, which is 31 * typically in all-caps. For example, a function which always returns the same 32 * kind of data it was provided would look like this: 33 * 34 * ```js 35 * identity<T>(value: T): T 36 * ``` 37 * 38 * Type variables are defined with classes and referred to in methods. For 39 * example, a class that holds onto a value for you might look like this: 40 * 41 * ```js 42 * class Box<T> { 43 * constructor(value: T) 44 * getValue(): T 45 * } 46 * ``` 47 * 48 * In order to manipulate Immutable data, methods that we're used to affecting 49 * a Collection instead return a new Collection of the same type. The type 50 * `this` refers to the same kind of class. For example, a List which returns 51 * new Lists when you `push` a value onto it might look like: 52 * 53 * ```js 54 * class List<T> { 55 * push(value: T): this 56 * } 57 * ``` 58 * 59 * Many methods in Immutable.js accept values which implement the JavaScript 60 * [Iterable][] protocol, and might appear like `Iterable<string>` for something 61 * which represents sequence of strings. Typically in JavaScript we use plain 62 * Arrays (`[]`) when an Iterable is expected, but also all of the Immutable.js 63 * collections are iterable themselves! 64 * 65 * For example, to get a value deep within a structure of data, we might use 66 * `getIn` which expects an `Iterable` path: 67 * 68 * ``` 69 * getIn(path: Iterable<string | number>): unknown 70 * ``` 71 * 72 * To use this method, we could pass an array: `data.getIn([ "key", 2 ])`. 73 * 74 * 75 * Note: All examples are presented in the modern [ES2015][] version of 76 * JavaScript. Use tools like Babel to support older browsers. 77 * 78 * For example: 79 * 80 * ```js 81 * // ES2015 82 * const mappedFoo = foo.map(x => x * x); 83 * // ES5 84 * var mappedFoo = foo.map(function (x) { return x * x; }); 85 * ``` 86 * 87 * [ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla 88 * [TypeScript]: https://www.typescriptlang.org/ 89 * [Flow]: https://flowtype.org/ 90 * [Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols 91 */ 92 93 declare namespace Immutable { 94 /** @ignore */ 95 type OnlyObject<T> = Extract<T, object>; 96 97 /** @ignore */ 98 type ContainObject<T> = OnlyObject<T> extends object 99 ? OnlyObject<T> extends never 100 ? false 101 : true 102 : false; 103 104 /** 105 * @ignore 106 * 107 * Used to convert deeply all immutable types to a plain TS type. 108 * Using `unknown` on object instead of recursive call as we have a circular reference issue 109 */ 110 export type DeepCopy<T> = T extends Record<infer R> 111 ? // convert Record to DeepCopy plain JS object 112 { 113 [key in keyof R]: ContainObject<R[key]> extends true ? unknown : R[key]; 114 } 115 : T extends Collection.Keyed<infer KeyedKey, infer V> 116 ? // convert KeyedCollection to DeepCopy plain JS object 117 { 118 [key in KeyedKey extends string | number | symbol 119 ? KeyedKey 120 : string]: V extends object ? unknown : V; 121 } 122 : // convert IndexedCollection or Immutable.Set to DeepCopy plain JS array 123 T extends Collection<infer _, infer V> 124 ? Array<DeepCopy<V>> 125 : T extends string | number // Iterable scalar types : should be kept as is 126 ? T 127 : T extends Iterable<infer V> // Iterable are converted to plain JS array 128 ? Array<DeepCopy<V>> 129 : T extends object // plain JS object are converted deeply 130 ? { 131 [ObjectKey in keyof T]: ContainObject<T[ObjectKey]> extends true 132 ? unknown 133 : T[ObjectKey]; 134 } 135 : // other case : should be kept as is 136 T; 137 138 /** 139 * Describes which item in a pair should be placed first when sorting 140 * 141 * @ignore 142 */ 143 export enum PairSorting { 144 LeftThenRight = -1, 145 RightThenLeft = +1, 146 } 147 148 /** 149 * Function comparing two items of the same type. It can return: 150 * 151 * * a PairSorting value, to indicate whether the left-hand item or the right-hand item should be placed before the other 152 * 153 * * the traditional numeric return value - especially -1, 0, or 1 154 * 155 * @ignore 156 */ 157 export type Comparator<T> = (left: T, right: T) => PairSorting | number; 158 159 /** 160 * Lists are ordered indexed dense collections, much like a JavaScript 161 * Array. 162 * 163 * Lists are immutable and fully persistent with O(log32 N) gets and sets, 164 * and O(1) push and pop. 165 * 166 * Lists implement Deque, with efficient addition and removal from both the 167 * end (`push`, `pop`) and beginning (`unshift`, `shift`). 168 * 169 * Unlike a JavaScript Array, there is no distinction between an 170 * "unset" index and an index set to `undefined`. `List#forEach` visits all 171 * indices from 0 to size, regardless of whether they were explicitly defined. 172 */ 173 namespace List { 174 /** 175 * True if the provided value is a List 176 * 177 * <!-- runkit:activate --> 178 * ```js 179 * const { List } = require('immutable'); 180 * List.isList([]); // false 181 * List.isList(List()); // true 182 * ``` 183 */ 184 function isList(maybeList: unknown): maybeList is List<unknown>; 185 186 /** 187 * Creates a new List containing `values`. 188 * 189 * <!-- runkit:activate --> 190 * ```js 191 * const { List } = require('immutable'); 192 * List.of(1, 2, 3, 4) 193 * // List [ 1, 2, 3, 4 ] 194 * ``` 195 * 196 * Note: Values are not altered or converted in any way. 197 * 198 * <!-- runkit:activate --> 199 * ```js 200 * const { List } = require('immutable'); 201 * List.of({x:1}, 2, [3], 4) 202 * // List [ { x: 1 }, 2, [ 3 ], 4 ] 203 * ``` 204 */ 205 function of<T>(...values: Array<T>): List<T>; 206 } 207 208 /** 209 * Create a new immutable List containing the values of the provided 210 * collection-like. 211 * 212 * Note: `List` is a factory function and not a class, and does not use the 213 * `new` keyword during construction. 214 * 215 * <!-- runkit:activate --> 216 * ```js 217 * const { List, Set } = require('immutable') 218 * 219 * const emptyList = List() 220 * // List [] 221 * 222 * const plainArray = [ 1, 2, 3, 4 ] 223 * const listFromPlainArray = List(plainArray) 224 * // List [ 1, 2, 3, 4 ] 225 * 226 * const plainSet = Set([ 1, 2, 3, 4 ]) 227 * const listFromPlainSet = List(plainSet) 228 * // List [ 1, 2, 3, 4 ] 229 * 230 * const arrayIterator = plainArray[Symbol.iterator]() 231 * const listFromCollectionArray = List(arrayIterator) 232 * // List [ 1, 2, 3, 4 ] 233 * 234 * listFromPlainArray.equals(listFromCollectionArray) // true 235 * listFromPlainSet.equals(listFromCollectionArray) // true 236 * listFromPlainSet.equals(listFromPlainArray) // true 237 * ``` 238 */ 239 function List<T>(collection?: Iterable<T> | ArrayLike<T>): List<T>; 240 241 interface List<T> extends Collection.Indexed<T> { 242 /** 243 * The number of items in this List. 244 */ 245 readonly size: number; 246 247 // Persistent changes 248 249 /** 250 * Returns a new List which includes `value` at `index`. If `index` already 251 * exists in this List, it will be replaced. 252 * 253 * `index` may be a negative number, which indexes back from the end of the 254 * List. `v.set(-1, "value")` sets the last item in the List. 255 * 256 * If `index` larger than `size`, the returned List's `size` will be large 257 * enough to include the `index`. 258 * 259 * <!-- runkit:activate 260 * { "preamble": "const { List } = require('immutable');" } 261 * --> 262 * ```js 263 * const originalList = List([ 0 ]); 264 * // List [ 0 ] 265 * originalList.set(1, 1); 266 * // List [ 0, 1 ] 267 * originalList.set(0, 'overwritten'); 268 * // List [ "overwritten" ] 269 * originalList.set(2, 2); 270 * // List [ 0, undefined, 2 ] 271 * 272 * List().set(50000, 'value').size; 273 * // 50001 274 * ``` 275 * 276 * Note: `set` can be used in `withMutations`. 277 */ 278 set(index: number, value: T): List<T>; 279 280 /** 281 * Returns a new List which excludes this `index` and with a size 1 less 282 * than this List. Values at indices above `index` are shifted down by 1 to 283 * fill the position. 284 * 285 * This is synonymous with `list.splice(index, 1)`. 286 * 287 * `index` may be a negative number, which indexes back from the end of the 288 * List. `v.delete(-1)` deletes the last item in the List. 289 * 290 * Note: `delete` cannot be safely used in IE8 291 * 292 * <!-- runkit:activate 293 * { "preamble": "const { List } = require('immutable');" } 294 * --> 295 * ```js 296 * List([ 0, 1, 2, 3, 4 ]).delete(0); 297 * // List [ 1, 2, 3, 4 ] 298 * ``` 299 * 300 * Since `delete()` re-indexes values, it produces a complete copy, which 301 * has `O(N)` complexity. 302 * 303 * Note: `delete` *cannot* be used in `withMutations`. 304 * 305 * @alias remove 306 */ 307 delete(index: number): List<T>; 308 remove(index: number): List<T>; 309 310 /** 311 * Returns a new List with `value` at `index` with a size 1 more than this 312 * List. Values at indices above `index` are shifted over by 1. 313 * 314 * This is synonymous with `list.splice(index, 0, value)`. 315 * 316 * <!-- runkit:activate 317 * { "preamble": "const { List } = require('immutable');" } 318 * --> 319 * ```js 320 * List([ 0, 1, 2, 3, 4 ]).insert(6, 5) 321 * // List [ 0, 1, 2, 3, 4, 5 ] 322 * ``` 323 * 324 * Since `insert()` re-indexes values, it produces a complete copy, which 325 * has `O(N)` complexity. 326 * 327 * Note: `insert` *cannot* be used in `withMutations`. 328 */ 329 insert(index: number, value: T): List<T>; 330 331 /** 332 * Returns a new List with 0 size and no values in constant time. 333 * 334 * <!-- runkit:activate 335 * { "preamble": "const { List } = require('immutable');" } 336 * --> 337 * ```js 338 * List([ 1, 2, 3, 4 ]).clear() 339 * // List [] 340 * ``` 341 * 342 * Note: `clear` can be used in `withMutations`. 343 */ 344 clear(): List<T>; 345 346 /** 347 * Returns a new List with the provided `values` appended, starting at this 348 * List's `size`. 349 * 350 * <!-- runkit:activate 351 * { "preamble": "const { List } = require('immutable');" } 352 * --> 353 * ```js 354 * List([ 1, 2, 3, 4 ]).push(5) 355 * // List [ 1, 2, 3, 4, 5 ] 356 * ``` 357 * 358 * Note: `push` can be used in `withMutations`. 359 */ 360 push(...values: Array<T>): List<T>; 361 362 /** 363 * Returns a new List with a size ones less than this List, excluding 364 * the last index in this List. 365 * 366 * Note: this differs from `Array#pop` because it returns a new 367 * List rather than the removed value. Use `last()` to get the last value 368 * in this List. 369 * 370 * ```js 371 * List([ 1, 2, 3, 4 ]).pop() 372 * // List[ 1, 2, 3 ] 373 * ``` 374 * 375 * Note: `pop` can be used in `withMutations`. 376 */ 377 pop(): List<T>; 378 379 /** 380 * Returns a new List with the provided `values` prepended, shifting other 381 * values ahead to higher indices. 382 * 383 * <!-- runkit:activate 384 * { "preamble": "const { List } = require('immutable');" } 385 * --> 386 * ```js 387 * List([ 2, 3, 4]).unshift(1); 388 * // List [ 1, 2, 3, 4 ] 389 * ``` 390 * 391 * Note: `unshift` can be used in `withMutations`. 392 */ 393 unshift(...values: Array<T>): List<T>; 394 395 /** 396 * Returns a new List with a size ones less than this List, excluding 397 * the first index in this List, shifting all other values to a lower index. 398 * 399 * Note: this differs from `Array#shift` because it returns a new 400 * List rather than the removed value. Use `first()` to get the first 401 * value in this List. 402 * 403 * <!-- runkit:activate 404 * { "preamble": "const { List } = require('immutable');" } 405 * --> 406 * ```js 407 * List([ 0, 1, 2, 3, 4 ]).shift(); 408 * // List [ 1, 2, 3, 4 ] 409 * ``` 410 * 411 * Note: `shift` can be used in `withMutations`. 412 */ 413 shift(): List<T>; 414 415 /** 416 * Returns a new List with an updated value at `index` with the return 417 * value of calling `updater` with the existing value, or `notSetValue` if 418 * `index` was not set. If called with a single argument, `updater` is 419 * called with the List itself. 420 * 421 * `index` may be a negative number, which indexes back from the end of the 422 * List. `v.update(-1)` updates the last item in the List. 423 * 424 * <!-- runkit:activate 425 * { "preamble": "const { List } = require('immutable');" } 426 * --> 427 * ```js 428 * const list = List([ 'a', 'b', 'c' ]) 429 * const result = list.update(2, val => val.toUpperCase()) 430 * // List [ "a", "b", "C" ] 431 * ``` 432 * 433 * This can be very useful as a way to "chain" a normal function into a 434 * sequence of methods. RxJS calls this "let" and lodash calls it "thru". 435 * 436 * For example, to sum a List after mapping and filtering: 437 * 438 * <!-- runkit:activate 439 * { "preamble": "const { List } = require('immutable');" } 440 * --> 441 * ```js 442 * function sum(collection) { 443 * return collection.reduce((sum, x) => sum + x, 0) 444 * } 445 * 446 * List([ 1, 2, 3 ]) 447 * .map(x => x + 1) 448 * .filter(x => x % 2 === 0) 449 * .update(sum) 450 * // 6 451 * ``` 452 * 453 * Note: `update(index)` can be used in `withMutations`. 454 * 455 * @see `Map#update` 456 */ 457 update(index: number, notSetValue: T, updater: (value: T) => T): this; 458 update( 459 index: number, 460 updater: (value: T | undefined) => T | undefined 461 ): this; 462 update<R>(updater: (value: this) => R): R; 463 464 /** 465 * Returns a new List with size `size`. If `size` is less than this 466 * List's size, the new List will exclude values at the higher indices. 467 * If `size` is greater than this List's size, the new List will have 468 * undefined values for the newly available indices. 469 * 470 * When building a new List and the final size is known up front, `setSize` 471 * used in conjunction with `withMutations` may result in the more 472 * performant construction. 473 */ 474 setSize(size: number): List<T>; 475 476 // Deep persistent changes 477 478 /** 479 * Returns a new List having set `value` at this `keyPath`. If any keys in 480 * `keyPath` do not exist, a new immutable Map will be created at that key. 481 * 482 * Index numbers are used as keys to determine the path to follow in 483 * the List. 484 * 485 * <!-- runkit:activate --> 486 * ```js 487 * const { List } = require('immutable') 488 * const list = List([ 0, 1, 2, List([ 3, 4 ])]) 489 * list.setIn([3, 0], 999); 490 * // List [ 0, 1, 2, List [ 999, 4 ] ] 491 * ``` 492 * 493 * Plain JavaScript Object or Arrays may be nested within an Immutable.js 494 * Collection, and setIn() can update those values as well, treating them 495 * immutably by creating new copies of those values with the changes applied. 496 * 497 * <!-- runkit:activate --> 498 * ```js 499 * const { List } = require('immutable') 500 * const list = List([ 0, 1, 2, { plain: 'object' }]) 501 * list.setIn([3, 'plain'], 'value'); 502 * // List([ 0, 1, 2, { plain: 'value' }]) 503 * ``` 504 * 505 * Note: `setIn` can be used in `withMutations`. 506 */ 507 setIn(keyPath: Iterable<unknown>, value: unknown): this; 508 509 /** 510 * Returns a new List having removed the value at this `keyPath`. If any 511 * keys in `keyPath` do not exist, no change will occur. 512 * 513 * <!-- runkit:activate --> 514 * ```js 515 * const { List } = require('immutable') 516 * const list = List([ 0, 1, 2, List([ 3, 4 ])]) 517 * list.deleteIn([3, 0]); 518 * // List [ 0, 1, 2, List [ 4 ] ] 519 * ``` 520 * 521 * Plain JavaScript Object or Arrays may be nested within an Immutable.js 522 * Collection, and removeIn() can update those values as well, treating them 523 * immutably by creating new copies of those values with the changes applied. 524 * 525 * <!-- runkit:activate --> 526 * ```js 527 * const { List } = require('immutable') 528 * const list = List([ 0, 1, 2, { plain: 'object' }]) 529 * list.removeIn([3, 'plain']); 530 * // List([ 0, 1, 2, {}]) 531 * ``` 532 * 533 * Note: `deleteIn` *cannot* be safely used in `withMutations`. 534 * 535 * @alias removeIn 536 */ 537 deleteIn(keyPath: Iterable<unknown>): this; 538 removeIn(keyPath: Iterable<unknown>): this; 539 540 /** 541 * Note: `updateIn` can be used in `withMutations`. 542 * 543 * @see `Map#updateIn` 544 */ 545 updateIn( 546 keyPath: Iterable<unknown>, 547 notSetValue: unknown, 548 updater: (value: unknown) => unknown 549 ): this; 550 updateIn( 551 keyPath: Iterable<unknown>, 552 updater: (value: unknown) => unknown 553 ): this; 554 555 /** 556 * Note: `mergeIn` can be used in `withMutations`. 557 * 558 * @see `Map#mergeIn` 559 */ 560 mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this; 561 562 /** 563 * Note: `mergeDeepIn` can be used in `withMutations`. 564 * 565 * @see `Map#mergeDeepIn` 566 */ 567 mergeDeepIn( 568 keyPath: Iterable<unknown>, 569 ...collections: Array<unknown> 570 ): this; 571 572 // Transient changes 573 574 /** 575 * Note: Not all methods can be safely used on a mutable collection or within 576 * `withMutations`! Check the documentation for each method to see if it 577 * allows being used in `withMutations`. 578 * 579 * @see `Map#withMutations` 580 */ 581 withMutations(mutator: (mutable: this) => unknown): this; 582 583 /** 584 * An alternative API for withMutations() 585 * 586 * Note: Not all methods can be safely used on a mutable collection or within 587 * `withMutations`! Check the documentation for each method to see if it 588 * allows being used in `withMutations`. 589 * 590 * @see `Map#asMutable` 591 */ 592 asMutable(): this; 593 594 /** 595 * @see `Map#wasAltered` 596 */ 597 wasAltered(): boolean; 598 599 /** 600 * @see `Map#asImmutable` 601 */ 602 asImmutable(): this; 603 604 // Sequence algorithms 605 606 /** 607 * Returns a new List with other values or collections concatenated to this one. 608 * 609 * Note: `concat` can be used in `withMutations`. 610 * 611 * @alias merge 612 */ 613 concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>; 614 merge<C>(...collections: Array<Iterable<C>>): List<T | C>; 615 616 /** 617 * Returns a new List with values passed through a 618 * `mapper` function. 619 * 620 * <!-- runkit:activate 621 * { "preamble": "const { List } = require('immutable');" } 622 * --> 623 * ```js 624 * List([ 1, 2 ]).map(x => 10 * x) 625 * // List [ 10, 20 ] 626 * ``` 627 */ 628 map<M>( 629 mapper: (value: T, key: number, iter: this) => M, 630 context?: unknown 631 ): List<M>; 632 633 /** 634 * Flat-maps the List, returning a new List. 635 * 636 * Similar to `list.map(...).flatten(true)`. 637 */ 638 flatMap<M>( 639 mapper: (value: T, key: number, iter: this) => Iterable<M>, 640 context?: unknown 641 ): List<M>; 642 643 /** 644 * Returns a new List with only the values for which the `predicate` 645 * function returns true. 646 * 647 * Note: `filter()` always returns a new instance, even if it results in 648 * not filtering out any values. 649 */ 650 filter<F extends T>( 651 predicate: (value: T, index: number, iter: this) => value is F, 652 context?: unknown 653 ): List<F>; 654 filter( 655 predicate: (value: T, index: number, iter: this) => unknown, 656 context?: unknown 657 ): this; 658 659 /** 660 * Returns a new List with the values for which the `predicate` 661 * function returns false and another for which is returns true. 662 */ 663 partition<F extends T, C>( 664 predicate: (this: C, value: T, index: number, iter: this) => value is F, 665 context?: C 666 ): [List<T>, List<F>]; 667 partition<C>( 668 predicate: (this: C, value: T, index: number, iter: this) => unknown, 669 context?: C 670 ): [this, this]; 671 672 /** 673 * Returns a List "zipped" with the provided collection. 674 * 675 * Like `zipWith`, but using the default `zipper`: creating an `Array`. 676 * 677 * <!-- runkit:activate 678 * { "preamble": "const { List } = require('immutable');" } 679 * --> 680 * ```js 681 * const a = List([ 1, 2, 3 ]); 682 * const b = List([ 4, 5, 6 ]); 683 * const c = a.zip(b); // List [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] 684 * ``` 685 */ 686 zip<U>(other: Collection<unknown, U>): List<[T, U]>; 687 zip<U, V>( 688 other: Collection<unknown, U>, 689 other2: Collection<unknown, V> 690 ): List<[T, U, V]>; 691 zip(...collections: Array<Collection<unknown, unknown>>): List<unknown>; 692 693 /** 694 * Returns a List "zipped" with the provided collections. 695 * 696 * Unlike `zip`, `zipAll` continues zipping until the longest collection is 697 * exhausted. Missing values from shorter collections are filled with `undefined`. 698 * 699 * <!-- runkit:activate 700 * { "preamble": "const { List } = require('immutable');" } 701 * --> 702 * ```js 703 * const a = List([ 1, 2 ]); 704 * const b = List([ 3, 4, 5 ]); 705 * const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] 706 * ``` 707 * 708 * Note: Since zipAll will return a collection as large as the largest 709 * input, some results may contain undefined values. TypeScript cannot 710 * account for these without cases (as of v2.5). 711 */ 712 zipAll<U>(other: Collection<unknown, U>): List<[T, U]>; 713 zipAll<U, V>( 714 other: Collection<unknown, U>, 715 other2: Collection<unknown, V> 716 ): List<[T, U, V]>; 717 zipAll(...collections: Array<Collection<unknown, unknown>>): List<unknown>; 718 719 /** 720 * Returns a List "zipped" with the provided collections by using a 721 * custom `zipper` function. 722 * 723 * <!-- runkit:activate 724 * { "preamble": "const { List } = require('immutable');" } 725 * --> 726 * ```js 727 * const a = List([ 1, 2, 3 ]); 728 * const b = List([ 4, 5, 6 ]); 729 * const c = a.zipWith((a, b) => a + b, b); 730 * // List [ 5, 7, 9 ] 731 * ``` 732 */ 733 zipWith<U, Z>( 734 zipper: (value: T, otherValue: U) => Z, 735 otherCollection: Collection<unknown, U> 736 ): List<Z>; 737 zipWith<U, V, Z>( 738 zipper: (value: T, otherValue: U, thirdValue: V) => Z, 739 otherCollection: Collection<unknown, U>, 740 thirdCollection: Collection<unknown, V> 741 ): List<Z>; 742 zipWith<Z>( 743 zipper: (...values: Array<unknown>) => Z, 744 ...collections: Array<Collection<unknown, unknown>> 745 ): List<Z>; 746 } 747 748 /** 749 * Immutable Map is an unordered Collection.Keyed of (key, value) pairs with 750 * `O(log32 N)` gets and `O(log32 N)` persistent sets. 751 * 752 * Iteration order of a Map is undefined, however is stable. Multiple 753 * iterations of the same Map will iterate in the same order. 754 * 755 * Map's keys can be of any type, and use `Immutable.is` to determine key 756 * equality. This allows the use of any value (including NaN) as a key. 757 * 758 * Because `Immutable.is` returns equality based on value semantics, and 759 * Immutable collections are treated as values, any Immutable collection may 760 * be used as a key. 761 * 762 * <!-- runkit:activate --> 763 * ```js 764 * const { Map, List } = require('immutable'); 765 * Map().set(List([ 1 ]), 'listofone').get(List([ 1 ])); 766 * // 'listofone' 767 * ``` 768 * 769 * Any JavaScript object may be used as a key, however strict identity is used 770 * to evaluate key equality. Two similar looking objects will represent two 771 * different keys. 772 * 773 * Implemented by a hash-array mapped trie. 774 */ 775 namespace Map { 776 /** 777 * True if the provided value is a Map 778 * 779 * <!-- runkit:activate --> 780 * ```js 781 * const { Map } = require('immutable') 782 * Map.isMap({}) // false 783 * Map.isMap(Map()) // true 784 * ``` 785 */ 786 function isMap(maybeMap: unknown): maybeMap is Map<unknown, unknown>; 787 788 /** 789 * Creates a new Map from alternating keys and values 790 * 791 * <!-- runkit:activate --> 792 * ```js 793 * const { Map } = require('immutable') 794 * Map.of( 795 * 'key', 'value', 796 * 'numerical value', 3, 797 * 0, 'numerical key' 798 * ) 799 * // Map { 0: "numerical key", "key": "value", "numerical value": 3 } 800 * ``` 801 * 802 * @deprecated Use Map([ [ 'k', 'v' ] ]) or Map({ k: 'v' }) 803 */ 804 function of(...keyValues: Array<unknown>): Map<unknown, unknown>; 805 } 806 807 /** 808 * Creates a new Immutable Map. 809 * 810 * Created with the same key value pairs as the provided Collection.Keyed or 811 * JavaScript Object or expects a Collection of [K, V] tuple entries. 812 * 813 * Note: `Map` is a factory function and not a class, and does not use the 814 * `new` keyword during construction. 815 * 816 * <!-- runkit:activate --> 817 * ```js 818 * const { Map } = require('immutable') 819 * Map({ key: "value" }) 820 * Map([ [ "key", "value" ] ]) 821 * ``` 822 * 823 * Keep in mind, when using JS objects to construct Immutable Maps, that 824 * JavaScript Object properties are always strings, even if written in a 825 * quote-less shorthand, while Immutable Maps accept keys of any type. 826 * 827 * <!-- runkit:activate 828 * { "preamble": "const { Map } = require('immutable');" } 829 * --> 830 * ```js 831 * let obj = { 1: "one" } 832 * Object.keys(obj) // [ "1" ] 833 * assert.equal(obj["1"], obj[1]) // "one" === "one" 834 * 835 * let map = Map(obj) 836 * assert.notEqual(map.get("1"), map.get(1)) // "one" !== undefined 837 * ``` 838 * 839 * Property access for JavaScript Objects first converts the key to a string, 840 * but since Immutable Map keys can be of any type the argument to `get()` is 841 * not altered. 842 */ 843 function Map<K, V>(collection?: Iterable<[K, V]>): Map<K, V>; 844 function Map<V>(obj: { [key: string]: V }): Map<string, V>; 845 function Map<K extends string | symbol, V>(obj: { [P in K]?: V }): Map<K, V>; 846 847 interface Map<K, V> extends Collection.Keyed<K, V> { 848 /** 849 * The number of entries in this Map. 850 */ 851 readonly size: number; 852 853 // Persistent changes 854 855 /** 856 * Returns a new Map also containing the new key, value pair. If an equivalent 857 * key already exists in this Map, it will be replaced. 858 * 859 * <!-- runkit:activate --> 860 * ```js 861 * const { Map } = require('immutable') 862 * const originalMap = Map() 863 * const newerMap = originalMap.set('key', 'value') 864 * const newestMap = newerMap.set('key', 'newer value') 865 * 866 * originalMap 867 * // Map {} 868 * newerMap 869 * // Map { "key": "value" } 870 * newestMap 871 * // Map { "key": "newer value" } 872 * ``` 873 * 874 * Note: `set` can be used in `withMutations`. 875 */ 876 set(key: K, value: V): this; 877 878 /** 879 * Returns a new Map which excludes this `key`. 880 * 881 * Note: `delete` cannot be safely used in IE8, but is provided to mirror 882 * the ES6 collection API. 883 * 884 * <!-- runkit:activate --> 885 * ```js 886 * const { Map } = require('immutable') 887 * const originalMap = Map({ 888 * key: 'value', 889 * otherKey: 'other value' 890 * }) 891 * // Map { "key": "value", "otherKey": "other value" } 892 * originalMap.delete('otherKey') 893 * // Map { "key": "value" } 894 * ``` 895 * 896 * Note: `delete` can be used in `withMutations`. 897 * 898 * @alias remove 899 */ 900 delete(key: K): this; 901 remove(key: K): this; 902 903 /** 904 * Returns a new Map which excludes the provided `keys`. 905 * 906 * <!-- runkit:activate --> 907 * ```js 908 * const { Map } = require('immutable') 909 * const names = Map({ a: "Aaron", b: "Barry", c: "Connor" }) 910 * names.deleteAll([ 'a', 'c' ]) 911 * // Map { "b": "Barry" } 912 * ``` 913 * 914 * Note: `deleteAll` can be used in `withMutations`. 915 * 916 * @alias removeAll 917 */ 918 deleteAll(keys: Iterable<K>): this; 919 removeAll(keys: Iterable<K>): this; 920 921 /** 922 * Returns a new Map containing no keys or values. 923 * 924 * <!-- runkit:activate --> 925 * ```js 926 * const { Map } = require('immutable') 927 * Map({ key: 'value' }).clear() 928 * // Map {} 929 * ``` 930 * 931 * Note: `clear` can be used in `withMutations`. 932 */ 933 clear(): this; 934 935 /** 936 * Returns a new Map having updated the value at this `key` with the return 937 * value of calling `updater` with the existing value. 938 * 939 * Similar to: `map.set(key, updater(map.get(key)))`. 940 * 941 * <!-- runkit:activate --> 942 * ```js 943 * const { Map } = require('immutable') 944 * const aMap = Map({ key: 'value' }) 945 * const newMap = aMap.update('key', value => value + value) 946 * // Map { "key": "valuevalue" } 947 * ``` 948 * 949 * This is most commonly used to call methods on collections within a 950 * structure of data. For example, in order to `.push()` onto a nested `List`, 951 * `update` and `push` can be used together: 952 * 953 * <!-- runkit:activate 954 * { "preamble": "const { Map, List } = require('immutable');" } 955 * --> 956 * ```js 957 * const aMap = Map({ nestedList: List([ 1, 2, 3 ]) }) 958 * const newMap = aMap.update('nestedList', list => list.push(4)) 959 * // Map { "nestedList": List [ 1, 2, 3, 4 ] } 960 * ``` 961 * 962 * When a `notSetValue` is provided, it is provided to the `updater` 963 * function when the value at the key does not exist in the Map. 964 * 965 * <!-- runkit:activate 966 * { "preamble": "const { Map } = require('immutable');" } 967 * --> 968 * ```js 969 * const aMap = Map({ key: 'value' }) 970 * const newMap = aMap.update('noKey', 'no value', value => value + value) 971 * // Map { "key": "value", "noKey": "no valueno value" } 972 * ``` 973 * 974 * However, if the `updater` function returns the same value it was called 975 * with, then no change will occur. This is still true if `notSetValue` 976 * is provided. 977 * 978 * <!-- runkit:activate 979 * { "preamble": "const { Map } = require('immutable');" } 980 * --> 981 * ```js 982 * const aMap = Map({ apples: 10 }) 983 * const newMap = aMap.update('oranges', 0, val => val) 984 * // Map { "apples": 10 } 985 * assert.strictEqual(newMap, map); 986 * ``` 987 * 988 * For code using ES2015 or later, using `notSetValue` is discourged in 989 * favor of function parameter default values. This helps to avoid any 990 * potential confusion with identify functions as described above. 991 * 992 * The previous example behaves differently when written with default values: 993 * 994 * <!-- runkit:activate 995 * { "preamble": "const { Map } = require('immutable');" } 996 * --> 997 * ```js 998 * const aMap = Map({ apples: 10 }) 999 * const newMap = aMap.update('oranges', (val = 0) => val) 1000 * // Map { "apples": 10, "oranges": 0 } 1001 * ``` 1002 * 1003 * If no key is provided, then the `updater` function return value is 1004 * returned as well. 1005 * 1006 * <!-- runkit:activate 1007 * { "preamble": "const { Map } = require('immutable');" } 1008 * --> 1009 * ```js 1010 * const aMap = Map({ key: 'value' }) 1011 * const result = aMap.update(aMap => aMap.get('key')) 1012 * // "value" 1013 * ``` 1014 * 1015 * This can be very useful as a way to "chain" a normal function into a 1016 * sequence of methods. RxJS calls this "let" and lodash calls it "thru". 1017 * 1018 * For example, to sum the values in a Map 1019 * 1020 * <!-- runkit:activate 1021 * { "preamble": "const { Map } = require('immutable');" } 1022 * --> 1023 * ```js 1024 * function sum(collection) { 1025 * return collection.reduce((sum, x) => sum + x, 0) 1026 * } 1027 * 1028 * Map({ x: 1, y: 2, z: 3 }) 1029 * .map(x => x + 1) 1030 * .filter(x => x % 2 === 0) 1031 * .update(sum) 1032 * // 6 1033 * ``` 1034 * 1035 * Note: `update(key)` can be used in `withMutations`. 1036 */ 1037 update(key: K, notSetValue: V, updater: (value: V) => V): this; 1038 update(key: K, updater: (value: V | undefined) => V | undefined): this; 1039 update<R>(updater: (value: this) => R): R; 1040 1041 /** 1042 * Returns a new Map resulting from merging the provided Collections 1043 * (or JS objects) into this Map. In other words, this takes each entry of 1044 * each collection and sets it on this Map. 1045 * 1046 * Note: Values provided to `merge` are shallowly converted before being 1047 * merged. No nested values are altered. 1048 * 1049 * <!-- runkit:activate --> 1050 * ```js 1051 * const { Map } = require('immutable') 1052 * const one = Map({ a: 10, b: 20, c: 30 }) 1053 * const two = Map({ b: 40, a: 50, d: 60 }) 1054 * one.merge(two) // Map { "a": 50, "b": 40, "c": 30, "d": 60 } 1055 * two.merge(one) // Map { "b": 20, "a": 10, "d": 60, "c": 30 } 1056 * ``` 1057 * 1058 * Note: `merge` can be used in `withMutations`. 1059 * 1060 * @alias concat 1061 */ 1062 merge<KC, VC>( 1063 ...collections: Array<Iterable<[KC, VC]>> 1064 ): Map<K | KC, V | VC>; 1065 merge<C>( 1066 ...collections: Array<{ [key: string]: C }> 1067 ): Map<K | string, V | C>; 1068 concat<KC, VC>( 1069 ...collections: Array<Iterable<[KC, VC]>> 1070 ): Map<K | KC, V | VC>; 1071 concat<C>( 1072 ...collections: Array<{ [key: string]: C }> 1073 ): Map<K | string, V | C>; 1074 1075 /** 1076 * Like `merge()`, `mergeWith()` returns a new Map resulting from merging 1077 * the provided Collections (or JS objects) into this Map, but uses the 1078 * `merger` function for dealing with conflicts. 1079 * 1080 * <!-- runkit:activate --> 1081 * ```js 1082 * const { Map } = require('immutable') 1083 * const one = Map({ a: 10, b: 20, c: 30 }) 1084 * const two = Map({ b: 40, a: 50, d: 60 }) 1085 * one.mergeWith((oldVal, newVal) => oldVal / newVal, two) 1086 * // { "a": 0.2, "b": 0.5, "c": 30, "d": 60 } 1087 * two.mergeWith((oldVal, newVal) => oldVal / newVal, one) 1088 * // { "b": 2, "a": 5, "d": 60, "c": 30 } 1089 * ``` 1090 * 1091 * Note: `mergeWith` can be used in `withMutations`. 1092 */ 1093 mergeWith( 1094 merger: (oldVal: V, newVal: V, key: K) => V, 1095 ...collections: Array<Iterable<[K, V]> | { [key: string]: V }> 1096 ): this; 1097 1098 /** 1099 * Like `merge()`, but when two compatible collections are encountered with 1100 * the same key, it merges them as well, recursing deeply through the nested 1101 * data. Two collections are considered to be compatible (and thus will be 1102 * merged together) if they both fall into one of three categories: keyed 1103 * (e.g., `Map`s, `Record`s, and objects), indexed (e.g., `List`s and 1104 * arrays), or set-like (e.g., `Set`s). If they fall into separate 1105 * categories, `mergeDeep` will replace the existing collection with the 1106 * collection being merged in. This behavior can be customized by using 1107 * `mergeDeepWith()`. 1108 * 1109 * Note: Indexed and set-like collections are merged using 1110 * `concat()`/`union()` and therefore do not recurse. 1111 * 1112 * <!-- runkit:activate --> 1113 * ```js 1114 * const { Map } = require('immutable') 1115 * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) }) 1116 * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) }) 1117 * one.mergeDeep(two) 1118 * // Map { 1119 * // "a": Map { "x": 2, "y": 10 }, 1120 * // "b": Map { "x": 20, "y": 5 }, 1121 * // "c": Map { "z": 3 } 1122 * // } 1123 * ``` 1124 * 1125 * Note: `mergeDeep` can be used in `withMutations`. 1126 */ 1127 mergeDeep( 1128 ...collections: Array<Iterable<[K, V]> | { [key: string]: V }> 1129 ): this; 1130 1131 /** 1132 * Like `mergeDeep()`, but when two non-collections or incompatible 1133 * collections are encountered at the same key, it uses the `merger` 1134 * function to determine the resulting value. Collections are considered 1135 * incompatible if they fall into separate categories between keyed, 1136 * indexed, and set-like. 1137 * 1138 * <!-- runkit:activate --> 1139 * ```js 1140 * const { Map } = require('immutable') 1141 * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) }) 1142 * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) }) 1143 * one.mergeDeepWith((oldVal, newVal) => oldVal / newVal, two) 1144 * // Map { 1145 * // "a": Map { "x": 5, "y": 10 }, 1146 * // "b": Map { "x": 20, "y": 10 }, 1147 * // "c": Map { "z": 3 } 1148 * // } 1149 * ``` 1150 * 1151 * Note: `mergeDeepWith` can be used in `withMutations`. 1152 */ 1153 mergeDeepWith( 1154 merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown, 1155 ...collections: Array<Iterable<[K, V]> | { [key: string]: V }> 1156 ): this; 1157 1158 // Deep persistent changes 1159 1160 /** 1161 * Returns a new Map having set `value` at this `keyPath`. If any keys in 1162 * `keyPath` do not exist, a new immutable Map will be created at that key. 1163 * 1164 * <!-- runkit:activate --> 1165 * ```js 1166 * const { Map } = require('immutable') 1167 * const originalMap = Map({ 1168 * subObject: Map({ 1169 * subKey: 'subvalue', 1170 * subSubObject: Map({ 1171 * subSubKey: 'subSubValue' 1172 * }) 1173 * }) 1174 * }) 1175 * 1176 * const newMap = originalMap.setIn(['subObject', 'subKey'], 'ha ha!') 1177 * // Map { 1178 * // "subObject": Map { 1179 * // "subKey": "ha ha!", 1180 * // "subSubObject": Map { "subSubKey": "subSubValue" } 1181 * // } 1182 * // } 1183 * 1184 * const newerMap = originalMap.setIn( 1185 * ['subObject', 'subSubObject', 'subSubKey'], 1186 * 'ha ha ha!' 1187 * ) 1188 * // Map { 1189 * // "subObject": Map { 1190 * // "subKey": "subvalue", 1191 * // "subSubObject": Map { "subSubKey": "ha ha ha!" } 1192 * // } 1193 * // } 1194 * ``` 1195 * 1196 * Plain JavaScript Object or Arrays may be nested within an Immutable.js 1197 * Collection, and setIn() can update those values as well, treating them 1198 * immutably by creating new copies of those values with the changes applied. 1199 * 1200 * <!-- runkit:activate --> 1201 * ```js 1202 * const { Map } = require('immutable') 1203 * const originalMap = Map({ 1204 * subObject: { 1205 * subKey: 'subvalue', 1206 * subSubObject: { 1207 * subSubKey: 'subSubValue' 1208 * } 1209 * } 1210 * }) 1211 * 1212 * originalMap.setIn(['subObject', 'subKey'], 'ha ha!') 1213 * // Map { 1214 * // "subObject": { 1215 * // subKey: "ha ha!", 1216 * // subSubObject: { subSubKey: "subSubValue" } 1217 * // } 1218 * // } 1219 * ``` 1220 * 1221 * If any key in the path exists but cannot be updated (such as a primitive 1222 * like number or a custom Object like Date), an error will be thrown. 1223 * 1224 * Note: `setIn` can be used in `withMutations`. 1225 */ 1226 setIn(keyPath: Iterable<unknown>, value: unknown): this; 1227 1228 /** 1229 * Returns a new Map having removed the value at this `keyPath`. If any keys 1230 * in `keyPath` do not exist, no change will occur. 1231 * 1232 * Note: `deleteIn` can be used in `withMutations`. 1233 * 1234 * @alias removeIn 1235 */ 1236 deleteIn(keyPath: Iterable<unknown>): this; 1237 removeIn(keyPath: Iterable<unknown>): this; 1238 1239 /** 1240 * Returns a new Map having applied the `updater` to the entry found at the 1241 * keyPath. 1242 * 1243 * This is most commonly used to call methods on collections nested within a 1244 * structure of data. For example, in order to `.push()` onto a nested `List`, 1245 * `updateIn` and `push` can be used together: 1246 * 1247 * <!-- runkit:activate --> 1248 * ```js 1249 * const { Map, List } = require('immutable') 1250 * const map = Map({ inMap: Map({ inList: List([ 1, 2, 3 ]) }) }) 1251 * const newMap = map.updateIn(['inMap', 'inList'], list => list.push(4)) 1252 * // Map { "inMap": Map { "inList": List [ 1, 2, 3, 4 ] } } 1253 * ``` 1254 * 1255 * If any keys in `keyPath` do not exist, new Immutable `Map`s will 1256 * be created at those keys. If the `keyPath` does not already contain a 1257 * value, the `updater` function will be called with `notSetValue`, if 1258 * provided, otherwise `undefined`. 1259 * 1260 * <!-- runkit:activate 1261 * { "preamble": "const { Map } = require('immutable')" } 1262 * --> 1263 * ```js 1264 * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) 1265 * const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2) 1266 * // Map { "a": Map { "b": Map { "c": 20 } } } 1267 * ``` 1268 * 1269 * If the `updater` function returns the same value it was called with, then 1270 * no change will occur. This is still true if `notSetValue` is provided. 1271 * 1272 * <!-- runkit:activate 1273 * { "preamble": "const { Map } = require('immutable')" } 1274 * --> 1275 * ```js 1276 * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) 1277 * const newMap = map.updateIn(['a', 'b', 'x'], 100, val => val) 1278 * // Map { "a": Map { "b": Map { "c": 10 } } } 1279 * assert.strictEqual(newMap, aMap) 1280 * ``` 1281 * 1282 * For code using ES2015 or later, using `notSetValue` is discourged in 1283 * favor of function parameter default values. This helps to avoid any 1284 * potential confusion with identify functions as described above. 1285 * 1286 * The previous example behaves differently when written with default values: 1287 * 1288 * <!-- runkit:activate 1289 * { "preamble": "const { Map } = require('immutable')" } 1290 * --> 1291 * ```js 1292 * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) 1293 * const newMap = map.updateIn(['a', 'b', 'x'], (val = 100) => val) 1294 * // Map { "a": Map { "b": Map { "c": 10, "x": 100 } } } 1295 * ``` 1296 * 1297 * Plain JavaScript Object or Arrays may be nested within an Immutable.js 1298 * Collection, and updateIn() can update those values as well, treating them 1299 * immutably by creating new copies of those values with the changes applied. 1300 * 1301 * <!-- runkit:activate 1302 * { "preamble": "const { Map } = require('immutable')" } 1303 * --> 1304 * ```js 1305 * const map = Map({ a: { b: { c: 10 } } }) 1306 * const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2) 1307 * // Map { "a": { b: { c: 20 } } } 1308 * ``` 1309 * 1310 * If any key in the path exists but cannot be updated (such as a primitive 1311 * like number or a custom Object like Date), an error will be thrown. 1312 * 1313 * Note: `updateIn` can be used in `withMutations`. 1314 */ 1315 updateIn( 1316 keyPath: Iterable<unknown>, 1317 notSetValue: unknown, 1318 updater: (value: unknown) => unknown 1319 ): this; 1320 updateIn( 1321 keyPath: Iterable<unknown>, 1322 updater: (value: unknown) => unknown 1323 ): this; 1324 1325 /** 1326 * A combination of `updateIn` and `merge`, returning a new Map, but 1327 * performing the merge at a point arrived at by following the keyPath. 1328 * In other words, these two lines are equivalent: 1329 * 1330 * ```js 1331 * map.updateIn(['a', 'b', 'c'], abc => abc.merge(y)) 1332 * map.mergeIn(['a', 'b', 'c'], y) 1333 * ``` 1334 * 1335 * Note: `mergeIn` can be used in `withMutations`. 1336 */ 1337 mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this; 1338 1339 /** 1340 * A combination of `updateIn` and `mergeDeep`, returning a new Map, but 1341 * performing the deep merge at a point arrived at by following the keyPath. 1342 * In other words, these two lines are equivalent: 1343 * 1344 * ```js 1345 * map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y)) 1346 * map.mergeDeepIn(['a', 'b', 'c'], y) 1347 * ``` 1348 * 1349 * Note: `mergeDeepIn` can be used in `withMutations`. 1350 */ 1351 mergeDeepIn( 1352 keyPath: Iterable<unknown>, 1353 ...collections: Array<unknown> 1354 ): this; 1355 1356 // Transient changes 1357 1358 /** 1359 * Every time you call one of the above functions, a new immutable Map is 1360 * created. If a pure function calls a number of these to produce a final 1361 * return value, then a penalty on performance and memory has been paid by 1362 * creating all of the intermediate immutable Maps. 1363 * 1364 * If you need to apply a series of mutations to produce a new immutable 1365 * Map, `withMutations()` creates a temporary mutable copy of the Map which 1366 * can apply mutations in a highly performant manner. In fact, this is 1367 * exactly how complex mutations like `merge` are done. 1368 * 1369 * As an example, this results in the creation of 2, not 4, new Maps: 1370 * 1371 * <!-- runkit:activate --> 1372 * ```js 1373 * const { Map } = require('immutable') 1374 * const map1 = Map() 1375 * const map2 = map1.withMutations(map => { 1376 * map.set('a', 1).set('b', 2).set('c', 3) 1377 * }) 1378 * assert.equal(map1.size, 0) 1379 * assert.equal(map2.size, 3) 1380 * ``` 1381 * 1382 * Note: Not all methods can be used on a mutable collection or within 1383 * `withMutations`! Read the documentation for each method to see if it 1384 * is safe to use in `withMutations`. 1385 */ 1386 withMutations(mutator: (mutable: this) => unknown): this; 1387 1388 /** 1389 * Another way to avoid creation of intermediate Immutable maps is to create 1390 * a mutable copy of this collection. Mutable copies *always* return `this`, 1391 * and thus shouldn't be used for equality. Your function should never return 1392 * a mutable copy of a collection, only use it internally to create a new 1393 * collection. 1394 * 1395 * If possible, use `withMutations` to work with temporary mutable copies as 1396 * it provides an easier to use API and considers many common optimizations. 1397 * 1398 * Note: if the collection is already mutable, `asMutable` returns itself. 1399 * 1400 * Note: Not all methods can be used on a mutable collection or within 1401 * `withMutations`! Read the documentation for each method to see if it 1402 * is safe to use in `withMutations`. 1403 * 1404 * @see `Map#asImmutable` 1405 */ 1406 asMutable(): this; 1407 1408 /** 1409 * Returns true if this is a mutable copy (see `asMutable()`) and mutative 1410 * alterations have been applied. 1411 * 1412 * @see `Map#asMutable` 1413 */ 1414 wasAltered(): boolean; 1415 1416 /** 1417 * The yin to `asMutable`'s yang. Because it applies to mutable collections, 1418 * this operation is *mutable* and may return itself (though may not 1419 * return itself, i.e. if the result is an empty collection). Once 1420 * performed, the original mutable copy must no longer be mutated since it 1421 * may be the immutable result. 1422 * 1423 * If possible, use `withMutations` to work with temporary mutable copies as 1424 * it provides an easier to use API and considers many common optimizations. 1425 * 1426 * @see `Map#asMutable` 1427 */ 1428 asImmutable(): this; 1429 1430 // Sequence algorithms 1431 1432 /** 1433 * Returns a new Map with values passed through a 1434 * `mapper` function. 1435 * 1436 * Map({ a: 1, b: 2 }).map(x => 10 * x) 1437 * // Map { a: 10, b: 20 } 1438 */ 1439 map<M>( 1440 mapper: (value: V, key: K, iter: this) => M, 1441 context?: unknown 1442 ): Map<K, M>; 1443 1444 /** 1445 * @see Collection.Keyed.mapKeys 1446 */ 1447 mapKeys<M>( 1448 mapper: (key: K, value: V, iter: this) => M, 1449 context?: unknown 1450 ): Map<M, V>; 1451 1452 /** 1453 * @see Collection.Keyed.mapEntries 1454 */ 1455 mapEntries<KM, VM>( 1456 mapper: ( 1457 entry: [K, V], 1458 index: number, 1459 iter: this 1460 ) => [KM, VM] | undefined, 1461 context?: unknown 1462 ): Map<KM, VM>; 1463 1464 /** 1465 * Flat-maps the Map, returning a new Map. 1466 * 1467 * Similar to `data.map(...).flatten(true)`. 1468 */ 1469 flatMap<KM, VM>( 1470 mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, 1471 context?: unknown 1472 ): Map<KM, VM>; 1473 1474 /** 1475 * Returns a new Map with only the entries for which the `predicate` 1476 * function returns true. 1477 * 1478 * Note: `filter()` always returns a new instance, even if it results in 1479 * not filtering out any values. 1480 */ 1481 filter<F extends V>( 1482 predicate: (value: V, key: K, iter: this) => value is F, 1483 context?: unknown 1484 ): Map<K, F>; 1485 filter( 1486 predicate: (value: V, key: K, iter: this) => unknown, 1487 context?: unknown 1488 ): this; 1489 1490 /** 1491 * Returns a new Map with the values for which the `predicate` 1492 * function returns false and another for which is returns true. 1493 */ 1494 partition<F extends V, C>( 1495 predicate: (this: C, value: V, key: K, iter: this) => value is F, 1496 context?: C 1497 ): [Map<K, V>, Map<K, F>]; 1498 partition<C>( 1499 predicate: (this: C, value: V, key: K, iter: this) => unknown, 1500 context?: C 1501 ): [this, this]; 1502 1503 /** 1504 * @see Collection.Keyed.flip 1505 */ 1506 flip(): Map<V, K>; 1507 } 1508 1509 /** 1510 * A type of Map that has the additional guarantee that the iteration order of 1511 * entries will be the order in which they were set(). 1512 * 1513 * The iteration behavior of OrderedMap is the same as native ES6 Map and 1514 * JavaScript Object. 1515 * 1516 * Note that `OrderedMap` are more expensive than non-ordered `Map` and may 1517 * consume more memory. `OrderedMap#set` is amortized O(log32 N), but not 1518 * stable. 1519 */ 1520 namespace OrderedMap { 1521 /** 1522 * True if the provided value is an OrderedMap. 1523 */ 1524 function isOrderedMap( 1525 maybeOrderedMap: unknown 1526 ): maybeOrderedMap is OrderedMap<unknown, unknown>; 1527 } 1528 1529 /** 1530 * Creates a new Immutable OrderedMap. 1531 * 1532 * Created with the same key value pairs as the provided Collection.Keyed or 1533 * JavaScript Object or expects a Collection of [K, V] tuple entries. 1534 * 1535 * The iteration order of key-value pairs provided to this constructor will 1536 * be preserved in the OrderedMap. 1537 * 1538 * let newOrderedMap = OrderedMap({key: "value"}) 1539 * let newOrderedMap = OrderedMap([["key", "value"]]) 1540 * 1541 * Note: `OrderedMap` is a factory function and not a class, and does not use 1542 * the `new` keyword during construction. 1543 */ 1544 function OrderedMap<K, V>(collection?: Iterable<[K, V]>): OrderedMap<K, V>; 1545 function OrderedMap<V>(obj: { [key: string]: V }): OrderedMap<string, V>; 1546 1547 interface OrderedMap<K, V> extends Map<K, V> { 1548 /** 1549 * The number of entries in this OrderedMap. 1550 */ 1551 readonly size: number; 1552 1553 /** 1554 * Returns a new OrderedMap also containing the new key, value pair. If an 1555 * equivalent key already exists in this OrderedMap, it will be replaced 1556 * while maintaining the existing order. 1557 * 1558 * <!-- runkit:activate --> 1559 * ```js 1560 * const { OrderedMap } = require('immutable') 1561 * const originalMap = OrderedMap({a:1, b:1, c:1}) 1562 * const updatedMap = originalMap.set('b', 2) 1563 * 1564 * originalMap 1565 * // OrderedMap {a: 1, b: 1, c: 1} 1566 * updatedMap 1567 * // OrderedMap {a: 1, b: 2, c: 1} 1568 * ``` 1569 * 1570 * Note: `set` can be used in `withMutations`. 1571 */ 1572 set(key: K, value: V): this; 1573 1574 /** 1575 * Returns a new OrderedMap resulting from merging the provided Collections 1576 * (or JS objects) into this OrderedMap. In other words, this takes each 1577 * entry of each collection and sets it on this OrderedMap. 1578 * 1579 * Note: Values provided to `merge` are shallowly converted before being 1580 * merged. No nested values are altered. 1581 * 1582 * <!-- runkit:activate --> 1583 * ```js 1584 * const { OrderedMap } = require('immutable') 1585 * const one = OrderedMap({ a: 10, b: 20, c: 30 }) 1586 * const two = OrderedMap({ b: 40, a: 50, d: 60 }) 1587 * one.merge(two) // OrderedMap { "a": 50, "b": 40, "c": 30, "d": 60 } 1588 * two.merge(one) // OrderedMap { "b": 20, "a": 10, "d": 60, "c": 30 } 1589 * ``` 1590 * 1591 * Note: `merge` can be used in `withMutations`. 1592 * 1593 * @alias concat 1594 */ 1595 merge<KC, VC>( 1596 ...collections: Array<Iterable<[KC, VC]>> 1597 ): OrderedMap<K | KC, V | VC>; 1598 merge<C>( 1599 ...collections: Array<{ [key: string]: C }> 1600 ): OrderedMap<K | string, V | C>; 1601 concat<KC, VC>( 1602 ...collections: Array<Iterable<[KC, VC]>> 1603 ): OrderedMap<K | KC, V | VC>; 1604 concat<C>( 1605 ...collections: Array<{ [key: string]: C }> 1606 ): OrderedMap<K | string, V | C>; 1607 1608 // Sequence algorithms 1609 1610 /** 1611 * Returns a new OrderedMap with values passed through a 1612 * `mapper` function. 1613 * 1614 * OrderedMap({ a: 1, b: 2 }).map(x => 10 * x) 1615 * // OrderedMap { "a": 10, "b": 20 } 1616 * 1617 * Note: `map()` always returns a new instance, even if it produced the same 1618 * value at every step. 1619 */ 1620 map<M>( 1621 mapper: (value: V, key: K, iter: this) => M, 1622 context?: unknown 1623 ): OrderedMap<K, M>; 1624 1625 /** 1626 * @see Collection.Keyed.mapKeys 1627 */ 1628 mapKeys<M>( 1629 mapper: (key: K, value: V, iter: this) => M, 1630 context?: unknown 1631 ): OrderedMap<M, V>; 1632 1633 /** 1634 * @see Collection.Keyed.mapEntries 1635 */ 1636 mapEntries<KM, VM>( 1637 mapper: ( 1638 entry: [K, V], 1639 index: number, 1640 iter: this 1641 ) => [KM, VM] | undefined, 1642 context?: unknown 1643 ): OrderedMap<KM, VM>; 1644 1645 /** 1646 * Flat-maps the OrderedMap, returning a new OrderedMap. 1647 * 1648 * Similar to `data.map(...).flatten(true)`. 1649 */ 1650 flatMap<KM, VM>( 1651 mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, 1652 context?: unknown 1653 ): OrderedMap<KM, VM>; 1654 1655 /** 1656 * Returns a new OrderedMap with only the entries for which the `predicate` 1657 * function returns true. 1658 * 1659 * Note: `filter()` always returns a new instance, even if it results in 1660 * not filtering out any values. 1661 */ 1662 filter<F extends V>( 1663 predicate: (value: V, key: K, iter: this) => value is F, 1664 context?: unknown 1665 ): OrderedMap<K, F>; 1666 filter( 1667 predicate: (value: V, key: K, iter: this) => unknown, 1668 context?: unknown 1669 ): this; 1670 1671 /** 1672 * Returns a new OrderedMap with the values for which the `predicate` 1673 * function returns false and another for which is returns true. 1674 */ 1675 partition<F extends V, C>( 1676 predicate: (this: C, value: V, key: K, iter: this) => value is F, 1677 context?: C 1678 ): [OrderedMap<K, V>, OrderedMap<K, F>]; 1679 partition<C>( 1680 predicate: (this: C, value: V, key: K, iter: this) => unknown, 1681 context?: C 1682 ): [this, this]; 1683 1684 /** 1685 * @see Collection.Keyed.flip 1686 */ 1687 flip(): OrderedMap<V, K>; 1688 } 1689 1690 /** 1691 * A Collection of unique values with `O(log32 N)` adds and has. 1692 * 1693 * When iterating a Set, the entries will be (value, value) pairs. Iteration 1694 * order of a Set is undefined, however is stable. Multiple iterations of the 1695 * same Set will iterate in the same order. 1696 * 1697 * Set values, like Map keys, may be of any type. Equality is determined using 1698 * `Immutable.is`, enabling Sets to uniquely include other Immutable 1699 * collections, custom value types, and NaN. 1700 */ 1701 namespace Set { 1702 /** 1703 * True if the provided value is a Set 1704 */ 1705 function isSet(maybeSet: unknown): maybeSet is Set<unknown>; 1706 1707 /** 1708 * Creates a new Set containing `values`. 1709 */ 1710 function of<T>(...values: Array<T>): Set<T>; 1711 1712 /** 1713 * `Set.fromKeys()` creates a new immutable Set containing the keys from 1714 * this Collection or JavaScript Object. 1715 */ 1716 function fromKeys<T>(iter: Collection<T, unknown>): Set<T>; 1717 function fromKeys(obj: { [key: string]: unknown }): Set<string>; 1718 1719 /** 1720 * `Set.intersect()` creates a new immutable Set that is the intersection of 1721 * a collection of other sets. 1722 * 1723 * ```js 1724 * const { Set } = require('immutable') 1725 * const intersected = Set.intersect([ 1726 * Set([ 'a', 'b', 'c' ]) 1727 * Set([ 'c', 'a', 't' ]) 1728 * ]) 1729 * // Set [ "a", "c" ] 1730 * ``` 1731 */ 1732 function intersect<T>(sets: Iterable<Iterable<T>>): Set<T>; 1733 1734 /** 1735 * `Set.union()` creates a new immutable Set that is the union of a 1736 * collection of other sets. 1737 * 1738 * ```js 1739 * const { Set } = require('immutable') 1740 * const unioned = Set.union([ 1741 * Set([ 'a', 'b', 'c' ]) 1742 * Set([ 'c', 'a', 't' ]) 1743 * ]) 1744 * // Set [ "a", "b", "c", "t" ] 1745 * ``` 1746 */ 1747 function union<T>(sets: Iterable<Iterable<T>>): Set<T>; 1748 } 1749 1750 /** 1751 * Create a new immutable Set containing the values of the provided 1752 * collection-like. 1753 * 1754 * Note: `Set` is a factory function and not a class, and does not use the 1755 * `new` keyword during construction. 1756 */ 1757 function Set<T>(collection?: Iterable<T> | ArrayLike<T>): Set<T>; 1758 1759 interface Set<T> extends Collection.Set<T> { 1760 /** 1761 * The number of items in this Set. 1762 */ 1763 readonly size: number; 1764 1765 // Persistent changes 1766 1767 /** 1768 * Returns a new Set which also includes this value. 1769 * 1770 * Note: `add` can be used in `withMutations`. 1771 */ 1772 add(value: T): this; 1773 1774 /** 1775 * Returns a new Set which excludes this value. 1776 * 1777 * Note: `delete` can be used in `withMutations`. 1778 * 1779 * Note: `delete` **cannot** be safely used in IE8, use `remove` if 1780 * supporting old browsers. 1781 * 1782 * @alias remove 1783 */ 1784 delete(value: T): this; 1785 remove(value: T): this; 1786 1787 /** 1788 * Returns a new Set containing no values. 1789 * 1790 * Note: `clear` can be used in `withMutations`. 1791 */ 1792 clear(): this; 1793 1794 /** 1795 * Returns a Set including any value from `collections` that does not already 1796 * exist in this Set. 1797 * 1798 * Note: `union` can be used in `withMutations`. 1799 * @alias merge 1800 * @alias concat 1801 */ 1802 union<C>(...collections: Array<Iterable<C>>): Set<T | C>; 1803 merge<C>(...collections: Array<Iterable<C>>): Set<T | C>; 1804 concat<C>(...collections: Array<Iterable<C>>): Set<T | C>; 1805 1806 /** 1807 * Returns a Set which has removed any values not also contained 1808 * within `collections`. 1809 * 1810 * Note: `intersect` can be used in `withMutations`. 1811 */ 1812 intersect(...collections: Array<Iterable<T>>): this; 1813 1814 /** 1815 * Returns a Set excluding any values contained within `collections`. 1816 * 1817 * <!-- runkit:activate --> 1818 * ```js 1819 * const { OrderedSet } = require('immutable') 1820 * OrderedSet([ 1, 2, 3 ]).subtract([1, 3]) 1821 * // OrderedSet [2] 1822 * ``` 1823 * 1824 * Note: `subtract` can be used in `withMutations`. 1825 */ 1826 subtract(...collections: Array<Iterable<T>>): this; 1827 1828 // Transient changes 1829 1830 /** 1831 * Note: Not all methods can be used on a mutable collection or within 1832 * `withMutations`! Check the documentation for each method to see if it 1833 * mentions being safe to use in `withMutations`. 1834 * 1835 * @see `Map#withMutations` 1836 */ 1837 withMutations(mutator: (mutable: this) => unknown): this; 1838 1839 /** 1840 * Note: Not all methods can be used on a mutable collection or within 1841 * `withMutations`! Check the documentation for each method to see if it 1842 * mentions being safe to use in `withMutations`. 1843 * 1844 * @see `Map#asMutable` 1845 */ 1846 asMutable(): this; 1847 1848 /** 1849 * @see `Map#wasAltered` 1850 */ 1851 wasAltered(): boolean; 1852 1853 /** 1854 * @see `Map#asImmutable` 1855 */ 1856 asImmutable(): this; 1857 1858 // Sequence algorithms 1859 1860 /** 1861 * Returns a new Set with values passed through a 1862 * `mapper` function. 1863 * 1864 * Set([1,2]).map(x => 10 * x) 1865 * // Set [10,20] 1866 */ 1867 map<M>( 1868 mapper: (value: T, key: T, iter: this) => M, 1869 context?: unknown 1870 ): Set<M>; 1871 1872 /** 1873 * Flat-maps the Set, returning a new Set. 1874 * 1875 * Similar to `set.map(...).flatten(true)`. 1876 */ 1877 flatMap<M>( 1878 mapper: (value: T, key: T, iter: this) => Iterable<M>, 1879 context?: unknown 1880 ): Set<M>; 1881 1882 /** 1883 * Returns a new Set with only the values for which the `predicate` 1884 * function returns true. 1885 * 1886 * Note: `filter()` always returns a new instance, even if it results in 1887 * not filtering out any values. 1888 */ 1889 filter<F extends T>( 1890 predicate: (value: T, key: T, iter: this) => value is F, 1891 context?: unknown 1892 ): Set<F>; 1893 filter( 1894 predicate: (value: T, key: T, iter: this) => unknown, 1895 context?: unknown 1896 ): this; 1897 1898 /** 1899 * Returns a new Set with the values for which the `predicate` function 1900 * returns false and another for which is returns true. 1901 */ 1902 partition<F extends T, C>( 1903 predicate: (this: C, value: T, key: T, iter: this) => value is F, 1904 context?: C 1905 ): [Set<T>, Set<F>]; 1906 partition<C>( 1907 predicate: (this: C, value: T, key: T, iter: this) => unknown, 1908 context?: C 1909 ): [this, this]; 1910 } 1911 1912 /** 1913 * A type of Set that has the additional guarantee that the iteration order of 1914 * values will be the order in which they were `add`ed. 1915 * 1916 * The iteration behavior of OrderedSet is the same as native ES6 Set. 1917 * 1918 * Note that `OrderedSet` are more expensive than non-ordered `Set` and may 1919 * consume more memory. `OrderedSet#add` is amortized O(log32 N), but not 1920 * stable. 1921 */ 1922 namespace OrderedSet { 1923 /** 1924 * True if the provided value is an OrderedSet. 1925 */ 1926 function isOrderedSet( 1927 maybeOrderedSet: unknown 1928 ): maybeOrderedSet is OrderedSet<unknown>; 1929 1930 /** 1931 * Creates a new OrderedSet containing `values`. 1932 */ 1933 function of<T>(...values: Array<T>): OrderedSet<T>; 1934 1935 /** 1936 * `OrderedSet.fromKeys()` creates a new immutable OrderedSet containing 1937 * the keys from this Collection or JavaScript Object. 1938 */ 1939 function fromKeys<T>(iter: Collection<T, unknown>): OrderedSet<T>; 1940 function fromKeys(obj: { [key: string]: unknown }): OrderedSet<string>; 1941 } 1942 1943 /** 1944 * Create a new immutable OrderedSet containing the values of the provided 1945 * collection-like. 1946 * 1947 * Note: `OrderedSet` is a factory function and not a class, and does not use 1948 * the `new` keyword during construction. 1949 */ 1950 function OrderedSet<T>( 1951 collection?: Iterable<T> | ArrayLike<T> 1952 ): OrderedSet<T>; 1953 1954 interface OrderedSet<T> extends Set<T> { 1955 /** 1956 * The number of items in this OrderedSet. 1957 */ 1958 readonly size: number; 1959 1960 /** 1961 * Returns an OrderedSet including any value from `collections` that does 1962 * not already exist in this OrderedSet. 1963 * 1964 * Note: `union` can be used in `withMutations`. 1965 * @alias merge 1966 * @alias concat 1967 */ 1968 union<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>; 1969 merge<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>; 1970 concat<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>; 1971 1972 // Sequence algorithms 1973 1974 /** 1975 * Returns a new Set with values passed through a 1976 * `mapper` function. 1977 * 1978 * OrderedSet([ 1, 2 ]).map(x => 10 * x) 1979 * // OrderedSet [10, 20] 1980 */ 1981 map<M>( 1982 mapper: (value: T, key: T, iter: this) => M, 1983 context?: unknown 1984 ): OrderedSet<M>; 1985 1986 /** 1987 * Flat-maps the OrderedSet, returning a new OrderedSet. 1988 * 1989 * Similar to `set.map(...).flatten(true)`. 1990 */ 1991 flatMap<M>( 1992 mapper: (value: T, key: T, iter: this) => Iterable<M>, 1993 context?: unknown 1994 ): OrderedSet<M>; 1995 1996 /** 1997 * Returns a new OrderedSet with only the values for which the `predicate` 1998 * function returns true. 1999 * 2000 * Note: `filter()` always returns a new instance, even if it results in 2001 * not filtering out any values. 2002 */ 2003 filter<F extends T>( 2004 predicate: (value: T, key: T, iter: this) => value is F, 2005 context?: unknown 2006 ): OrderedSet<F>; 2007 filter( 2008 predicate: (value: T, key: T, iter: this) => unknown, 2009 context?: unknown 2010 ): this; 2011 2012 /** 2013 * Returns a new OrderedSet with the values for which the `predicate` 2014 * function returns false and another for which is returns true. 2015 */ 2016 partition<F extends T, C>( 2017 predicate: (this: C, value: T, key: T, iter: this) => value is F, 2018 context?: C 2019 ): [OrderedSet<T>, OrderedSet<F>]; 2020 partition<C>( 2021 predicate: (this: C, value: T, key: T, iter: this) => unknown, 2022 context?: C 2023 ): [this, this]; 2024 2025 /** 2026 * Returns an OrderedSet of the same type "zipped" with the provided 2027 * collections. 2028 * 2029 * Like `zipWith`, but using the default `zipper`: creating an `Array`. 2030 * 2031 * ```js 2032 * const a = OrderedSet([ 1, 2, 3 ]) 2033 * const b = OrderedSet([ 4, 5, 6 ]) 2034 * const c = a.zip(b) 2035 * // OrderedSet [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] 2036 * ``` 2037 */ 2038 zip<U>(other: Collection<unknown, U>): OrderedSet<[T, U]>; 2039 zip<U, V>( 2040 other1: Collection<unknown, U>, 2041 other2: Collection<unknown, V> 2042 ): OrderedSet<[T, U, V]>; 2043 zip( 2044 ...collections: Array<Collection<unknown, unknown>> 2045 ): OrderedSet<unknown>; 2046 2047 /** 2048 * Returns a OrderedSet of the same type "zipped" with the provided 2049 * collections. 2050 * 2051 * Unlike `zip`, `zipAll` continues zipping until the longest collection is 2052 * exhausted. Missing values from shorter collections are filled with `undefined`. 2053 * 2054 * ```js 2055 * const a = OrderedSet([ 1, 2 ]); 2056 * const b = OrderedSet([ 3, 4, 5 ]); 2057 * const c = a.zipAll(b); // OrderedSet [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] 2058 * ``` 2059 * 2060 * Note: Since zipAll will return a collection as large as the largest 2061 * input, some results may contain undefined values. TypeScript cannot 2062 * account for these without cases (as of v2.5). 2063 */ 2064 zipAll<U>(other: Collection<unknown, U>): OrderedSet<[T, U]>; 2065 zipAll<U, V>( 2066 other1: Collection<unknown, U>, 2067 other2: Collection<unknown, V> 2068 ): OrderedSet<[T, U, V]>; 2069 zipAll( 2070 ...collections: Array<Collection<unknown, unknown>> 2071 ): OrderedSet<unknown>; 2072 2073 /** 2074 * Returns an OrderedSet of the same type "zipped" with the provided 2075 * collections by using a custom `zipper` function. 2076 * 2077 * @see Seq.Indexed.zipWith 2078 */ 2079 zipWith<U, Z>( 2080 zipper: (value: T, otherValue: U) => Z, 2081 otherCollection: Collection<unknown, U> 2082 ): OrderedSet<Z>; 2083 zipWith<U, V, Z>( 2084 zipper: (value: T, otherValue: U, thirdValue: V) => Z, 2085 otherCollection: Collection<unknown, U>, 2086 thirdCollection: Collection<unknown, V> 2087 ): OrderedSet<Z>; 2088 zipWith<Z>( 2089 zipper: (...values: Array<unknown>) => Z, 2090 ...collections: Array<Collection<unknown, unknown>> 2091 ): OrderedSet<Z>; 2092 } 2093 2094 /** 2095 * Stacks are indexed collections which support very efficient O(1) addition 2096 * and removal from the front using `unshift(v)` and `shift()`. 2097 * 2098 * For familiarity, Stack also provides `push(v)`, `pop()`, and `peek()`, but 2099 * be aware that they also operate on the front of the list, unlike List or 2100 * a JavaScript Array. 2101 * 2102 * Note: `reverse()` or any inherent reverse traversal (`reduceRight`, 2103 * `lastIndexOf`, etc.) is not efficient with a Stack. 2104 * 2105 * Stack is implemented with a Single-Linked List. 2106 */ 2107 namespace Stack { 2108 /** 2109 * True if the provided value is a Stack 2110 */ 2111 function isStack(maybeStack: unknown): maybeStack is Stack<unknown>; 2112 2113 /** 2114 * Creates a new Stack containing `values`. 2115 */ 2116 function of<T>(...values: Array<T>): Stack<T>; 2117 } 2118 2119 /** 2120 * Create a new immutable Stack containing the values of the provided 2121 * collection-like. 2122 * 2123 * The iteration order of the provided collection is preserved in the 2124 * resulting `Stack`. 2125 * 2126 * Note: `Stack` is a factory function and not a class, and does not use the 2127 * `new` keyword during construction. 2128 */ 2129 function Stack<T>(collection?: Iterable<T> | ArrayLike<T>): Stack<T>; 2130 2131 interface Stack<T> extends Collection.Indexed<T> { 2132 /** 2133 * The number of items in this Stack. 2134 */ 2135 readonly size: number; 2136 2137 // Reading values 2138 2139 /** 2140 * Alias for `Stack.first()`. 2141 */ 2142 peek(): T | undefined; 2143 2144 // Persistent changes 2145 2146 /** 2147 * Returns a new Stack with 0 size and no values. 2148 * 2149 * Note: `clear` can be used in `withMutations`. 2150 */ 2151 clear(): Stack<T>; 2152 2153 /** 2154 * Returns a new Stack with the provided `values` prepended, shifting other 2155 * values ahead to higher indices. 2156 * 2157 * This is very efficient for Stack. 2158 * 2159 * Note: `unshift` can be used in `withMutations`. 2160 */ 2161 unshift(...values: Array<T>): Stack<T>; 2162 2163 /** 2164 * Like `Stack#unshift`, but accepts a collection rather than varargs. 2165 * 2166 * Note: `unshiftAll` can be used in `withMutations`. 2167 */ 2168 unshiftAll(iter: Iterable<T>): Stack<T>; 2169 2170 /** 2171 * Returns a new Stack with a size ones less than this Stack, excluding 2172 * the first item in this Stack, shifting all other values to a lower index. 2173 * 2174 * Note: this differs from `Array#shift` because it returns a new 2175 * Stack rather than the removed value. Use `first()` or `peek()` to get the 2176 * first value in this Stack. 2177 * 2178 * Note: `shift` can be used in `withMutations`. 2179 */ 2180 shift(): Stack<T>; 2181 2182 /** 2183 * Alias for `Stack#unshift` and is not equivalent to `List#push`. 2184 */ 2185 push(...values: Array<T>): Stack<T>; 2186 2187 /** 2188 * Alias for `Stack#unshiftAll`. 2189 */ 2190 pushAll(iter: Iterable<T>): Stack<T>; 2191 2192 /** 2193 * Alias for `Stack#shift` and is not equivalent to `List#pop`. 2194 */ 2195 pop(): Stack<T>; 2196 2197 // Transient changes 2198 2199 /** 2200 * Note: Not all methods can be used on a mutable collection or within 2201 * `withMutations`! Check the documentation for each method to see if it 2202 * mentions being safe to use in `withMutations`. 2203 * 2204 * @see `Map#withMutations` 2205 */ 2206 withMutations(mutator: (mutable: this) => unknown): this; 2207 2208 /** 2209 * Note: Not all methods can be used on a mutable collection or within 2210 * `withMutations`! Check the documentation for each method to see if it 2211 * mentions being safe to use in `withMutations`. 2212 * 2213 * @see `Map#asMutable` 2214 */ 2215 asMutable(): this; 2216 2217 /** 2218 * @see `Map#wasAltered` 2219 */ 2220 wasAltered(): boolean; 2221 2222 /** 2223 * @see `Map#asImmutable` 2224 */ 2225 asImmutable(): this; 2226 2227 // Sequence algorithms 2228 2229 /** 2230 * Returns a new Stack with other collections concatenated to this one. 2231 */ 2232 concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Stack<T | C>; 2233 2234 /** 2235 * Returns a new Stack with values passed through a 2236 * `mapper` function. 2237 * 2238 * Stack([ 1, 2 ]).map(x => 10 * x) 2239 * // Stack [ 10, 20 ] 2240 * 2241 * Note: `map()` always returns a new instance, even if it produced the same 2242 * value at every step. 2243 */ 2244 map<M>( 2245 mapper: (value: T, key: number, iter: this) => M, 2246 context?: unknown 2247 ): Stack<M>; 2248 2249 /** 2250 * Flat-maps the Stack, returning a new Stack. 2251 * 2252 * Similar to `stack.map(...).flatten(true)`. 2253 */ 2254 flatMap<M>( 2255 mapper: (value: T, key: number, iter: this) => Iterable<M>, 2256 context?: unknown 2257 ): Stack<M>; 2258 2259 /** 2260 * Returns a new Set with only the values for which the `predicate` 2261 * function returns true. 2262 * 2263 * Note: `filter()` always returns a new instance, even if it results in 2264 * not filtering out any values. 2265 */ 2266 filter<F extends T>( 2267 predicate: (value: T, index: number, iter: this) => value is F, 2268 context?: unknown 2269 ): Set<F>; 2270 filter( 2271 predicate: (value: T, index: number, iter: this) => unknown, 2272 context?: unknown 2273 ): this; 2274 2275 /** 2276 * Returns a Stack "zipped" with the provided collections. 2277 * 2278 * Like `zipWith`, but using the default `zipper`: creating an `Array`. 2279 * 2280 * ```js 2281 * const a = Stack([ 1, 2, 3 ]); 2282 * const b = Stack([ 4, 5, 6 ]); 2283 * const c = a.zip(b); // Stack [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] 2284 * ``` 2285 */ 2286 zip<U>(other: Collection<unknown, U>): Stack<[T, U]>; 2287 zip<U, V>( 2288 other: Collection<unknown, U>, 2289 other2: Collection<unknown, V> 2290 ): Stack<[T, U, V]>; 2291 zip(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>; 2292 2293 /** 2294 * Returns a Stack "zipped" with the provided collections. 2295 * 2296 * Unlike `zip`, `zipAll` continues zipping until the longest collection is 2297 * exhausted. Missing values from shorter collections are filled with `undefined`. 2298 * 2299 * ```js 2300 * const a = Stack([ 1, 2 ]); 2301 * const b = Stack([ 3, 4, 5 ]); 2302 * const c = a.zipAll(b); // Stack [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] 2303 * ``` 2304 * 2305 * Note: Since zipAll will return a collection as large as the largest 2306 * input, some results may contain undefined values. TypeScript cannot 2307 * account for these without cases (as of v2.5). 2308 */ 2309 zipAll<U>(other: Collection<unknown, U>): Stack<[T, U]>; 2310 zipAll<U, V>( 2311 other: Collection<unknown, U>, 2312 other2: Collection<unknown, V> 2313 ): Stack<[T, U, V]>; 2314 zipAll(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>; 2315 2316 /** 2317 * Returns a Stack "zipped" with the provided collections by using a 2318 * custom `zipper` function. 2319 * 2320 * ```js 2321 * const a = Stack([ 1, 2, 3 ]); 2322 * const b = Stack([ 4, 5, 6 ]); 2323 * const c = a.zipWith((a, b) => a + b, b); 2324 * // Stack [ 5, 7, 9 ] 2325 * ``` 2326 */ 2327 zipWith<U, Z>( 2328 zipper: (value: T, otherValue: U) => Z, 2329 otherCollection: Collection<unknown, U> 2330 ): Stack<Z>; 2331 zipWith<U, V, Z>( 2332 zipper: (value: T, otherValue: U, thirdValue: V) => Z, 2333 otherCollection: Collection<unknown, U>, 2334 thirdCollection: Collection<unknown, V> 2335 ): Stack<Z>; 2336 zipWith<Z>( 2337 zipper: (...values: Array<unknown>) => Z, 2338 ...collections: Array<Collection<unknown, unknown>> 2339 ): Stack<Z>; 2340 } 2341 2342 /** 2343 * Returns a Seq.Indexed of numbers from `start` (inclusive) to `end` 2344 * (exclusive), by `step`, where `start` defaults to 0, `step` to 1, and `end` to 2345 * infinity. When `start` is equal to `end`, returns empty range. 2346 * 2347 * Note: `Range` is a factory function and not a class, and does not use the 2348 * `new` keyword during construction. 2349 * 2350 * ```js 2351 * const { Range } = require('immutable') 2352 * Range() // [ 0, 1, 2, 3, ... ] 2353 * Range(10) // [ 10, 11, 12, 13, ... ] 2354 * Range(10, 15) // [ 10, 11, 12, 13, 14 ] 2355 * Range(10, 30, 5) // [ 10, 15, 20, 25 ] 2356 * Range(30, 10, 5) // [ 30, 25, 20, 15 ] 2357 * Range(30, 30, 5) // [] 2358 * ``` 2359 */ 2360 function Range( 2361 start?: number, 2362 end?: number, 2363 step?: number 2364 ): Seq.Indexed<number>; 2365 2366 /** 2367 * Returns a Seq.Indexed of `value` repeated `times` times. When `times` is 2368 * not defined, returns an infinite `Seq` of `value`. 2369 * 2370 * Note: `Repeat` is a factory function and not a class, and does not use the 2371 * `new` keyword during construction. 2372 * 2373 * ```js 2374 * const { Repeat } = require('immutable') 2375 * Repeat('foo') // [ 'foo', 'foo', 'foo', ... ] 2376 * Repeat('bar', 4) // [ 'bar', 'bar', 'bar', 'bar' ] 2377 * ``` 2378 */ 2379 function Repeat<T>(value: T, times?: number): Seq.Indexed<T>; 2380 2381 /** 2382 * A record is similar to a JS object, but enforces a specific set of allowed 2383 * string keys, and has default values. 2384 * 2385 * The `Record()` function produces new Record Factories, which when called 2386 * create Record instances. 2387 * 2388 * ```js 2389 * const { Record } = require('immutable') 2390 * const ABRecord = Record({ a: 1, b: 2 }) 2391 * const myRecord = ABRecord({ b: 3 }) 2392 * ``` 2393 * 2394 * Records always have a value for the keys they define. `remove`ing a key 2395 * from a record simply resets it to the default value for that key. 2396 * 2397 * ```js 2398 * myRecord.get('a') // 1 2399 * myRecord.get('b') // 3 2400 * const myRecordWithoutB = myRecord.remove('b') 2401 * myRecordWithoutB.get('b') // 2 2402 * ``` 2403 * 2404 * Values provided to the constructor not found in the Record type will 2405 * be ignored. For example, in this case, ABRecord is provided a key "x" even 2406 * though only "a" and "b" have been defined. The value for "x" will be 2407 * ignored for this record. 2408 * 2409 * ```js 2410 * const myRecord = ABRecord({ b: 3, x: 10 }) 2411 * myRecord.get('x') // undefined 2412 * ``` 2413 * 2414 * Because Records have a known set of string keys, property get access works 2415 * as expected, however property sets will throw an Error. 2416 * 2417 * Note: IE8 does not support property access. Only use `get()` when 2418 * supporting IE8. 2419 * 2420 * ```js 2421 * myRecord.b // 3 2422 * myRecord.b = 5 // throws Error 2423 * ``` 2424 * 2425 * Record Types can be extended as well, allowing for custom methods on your 2426 * Record. This is not a common pattern in functional environments, but is in 2427 * many JS programs. 2428 * 2429 * However Record Types are more restricted than typical JavaScript classes. 2430 * They do not use a class constructor, which also means they cannot use 2431 * class properties (since those are technically part of a constructor). 2432 * 2433 * While Record Types can be syntactically created with the JavaScript `class` 2434 * form, the resulting Record function is actually a factory function, not a 2435 * class constructor. Even though Record Types are not classes, JavaScript 2436 * currently requires the use of `new` when creating new Record instances if 2437 * they are defined as a `class`. 2438 * 2439 * ``` 2440 * class ABRecord extends Record({ a: 1, b: 2 }) { 2441 * getAB() { 2442 * return this.a + this.b; 2443 * } 2444 * } 2445 * 2446 * var myRecord = new ABRecord({b: 3}) 2447 * myRecord.getAB() // 4 2448 * ``` 2449 * 2450 * 2451 * **Flow Typing Records:** 2452 * 2453 * Immutable.js exports two Flow types designed to make it easier to use 2454 * Records with flow typed code, `RecordOf<TProps>` and `RecordFactory<TProps>`. 2455 * 2456 * When defining a new kind of Record factory function, use a flow type that 2457 * describes the values the record contains along with `RecordFactory<TProps>`. 2458 * To type instances of the Record (which the factory function returns), 2459 * use `RecordOf<TProps>`. 2460 * 2461 * Typically, new Record definitions will export both the Record factory 2462 * function as well as the Record instance type for use in other code. 2463 * 2464 * ```js 2465 * import type { RecordFactory, RecordOf } from 'immutable'; 2466 * 2467 * // Use RecordFactory<TProps> for defining new Record factory functions. 2468 * type Point3DProps = { x: number, y: number, z: number }; 2469 * const defaultValues: Point3DProps = { x: 0, y: 0, z: 0 }; 2470 * const makePoint3D: RecordFactory<Point3DProps> = Record(defaultValues); 2471 * export makePoint3D; 2472 * 2473 * // Use RecordOf<T> for defining new instances of that Record. 2474 * export type Point3D = RecordOf<Point3DProps>; 2475 * const some3DPoint: Point3D = makePoint3D({ x: 10, y: 20, z: 30 }); 2476 * ``` 2477 * 2478 * **Flow Typing Record Subclasses:** 2479 * 2480 * Records can be subclassed as a means to add additional methods to Record 2481 * instances. This is generally discouraged in favor of a more functional API, 2482 * since Subclasses have some minor overhead. However the ability to create 2483 * a rich API on Record types can be quite valuable. 2484 * 2485 * When using Flow to type Subclasses, do not use `RecordFactory<TProps>`, 2486 * instead apply the props type when subclassing: 2487 * 2488 * ```js 2489 * type PersonProps = {name: string, age: number}; 2490 * const defaultValues: PersonProps = {name: 'Aristotle', age: 2400}; 2491 * const PersonRecord = Record(defaultValues); 2492 * class Person extends PersonRecord<PersonProps> { 2493 * getName(): string { 2494 * return this.get('name') 2495 * } 2496 * 2497 * setName(name: string): this { 2498 * return this.set('name', name); 2499 * } 2500 * } 2501 * ``` 2502 * 2503 * **Choosing Records vs plain JavaScript objects** 2504 * 2505 * Records offer a persistently immutable alternative to plain JavaScript 2506 * objects, however they're not required to be used within Immutable.js 2507 * collections. In fact, the deep-access and deep-updating functions 2508 * like `getIn()` and `setIn()` work with plain JavaScript Objects as well. 2509 * 2510 * Deciding to use Records or Objects in your application should be informed 2511 * by the tradeoffs and relative benefits of each: 2512 * 2513 * - *Runtime immutability*: plain JS objects may be carefully treated as 2514 * immutable, however Record instances will *throw* if attempted to be 2515 * mutated directly. Records provide this additional guarantee, however at 2516 * some marginal runtime cost. While JS objects are mutable by nature, the 2517 * use of type-checking tools like [Flow](https://medium.com/@gcanti/immutability-with-flow-faa050a1aef4) 2518 * can help gain confidence in code written to favor immutability. 2519 * 2520 * - *Value equality*: Records use value equality when compared with `is()` 2521 * or `record.equals()`. That is, two Records with the same keys and values 2522 * are equal. Plain objects use *reference equality*. Two objects with the 2523 * same keys and values are not equal since they are different objects. 2524 * This is important to consider when using objects as keys in a `Map` or 2525 * values in a `Set`, which use equality when retrieving values. 2526 * 2527 * - *API methods*: Records have a full featured API, with methods like 2528 * `.getIn()`, and `.equals()`. These can make working with these values 2529 * easier, but comes at the cost of not allowing keys with those names. 2530 * 2531 * - *Default values*: Records provide default values for every key, which 2532 * can be useful when constructing Records with often unchanging values. 2533 * However default values can make using Flow and TypeScript more laborious. 2534 * 2535 * - *Serialization*: Records use a custom internal representation to 2536 * efficiently store and update their values. Converting to and from this 2537 * form isn't free. If converting Records to plain objects is common, 2538 * consider sticking with plain objects to begin with. 2539 */ 2540 namespace Record { 2541 /** 2542 * True if `maybeRecord` is an instance of a Record. 2543 */ 2544 function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>; 2545 2546 /** 2547 * Records allow passing a second parameter to supply a descriptive name 2548 * that appears when converting a Record to a string or in any error 2549 * messages. A descriptive name for any record can be accessed by using this 2550 * method. If one was not provided, the string "Record" is returned. 2551 * 2552 * ```js 2553 * const { Record } = require('immutable') 2554 * const Person = Record({ 2555 * name: null 2556 * }, 'Person') 2557 * 2558 * var me = Person({ name: 'My Name' }) 2559 * me.toString() // "Person { "name": "My Name" }" 2560 * Record.getDescriptiveName(me) // "Person" 2561 * ``` 2562 */ 2563 function getDescriptiveName(record: Record<any>): string; 2564 2565 /** 2566 * A Record.Factory is created by the `Record()` function. Record instances 2567 * are created by passing it some of the accepted values for that Record 2568 * type: 2569 * 2570 * <!-- runkit:activate 2571 * { "preamble": "const { Record } = require('immutable')" } 2572 * --> 2573 * ```js 2574 * // makePerson is a Record Factory function 2575 * const makePerson = Record({ name: null, favoriteColor: 'unknown' }); 2576 * 2577 * // alan is a Record instance 2578 * const alan = makePerson({ name: 'Alan' }); 2579 * ``` 2580 * 2581 * Note that Record Factories return `Record<TProps> & Readonly<TProps>`, 2582 * this allows use of both the Record instance API, and direct property 2583 * access on the resulting instances: 2584 * 2585 * <!-- runkit:activate 2586 * { "preamble": "const { Record } = require('immutable');const makePerson = Record({ name: null, favoriteColor: 'unknown' });const alan = makePerson({ name: 'Alan' });" } 2587 * --> 2588 * ```js 2589 * // Use the Record API 2590 * console.log('Record API: ' + alan.get('name')) 2591 * 2592 * // Or direct property access (Readonly) 2593 * console.log('property access: ' + alan.name) 2594 * ``` 2595 * 2596 * **Flow Typing Records:** 2597 * 2598 * Use the `RecordFactory<TProps>` Flow type to get high quality type checking of 2599 * Records: 2600 * 2601 * ```js 2602 * import type { RecordFactory, RecordOf } from 'immutable'; 2603 * 2604 * // Use RecordFactory<TProps> for defining new Record factory functions. 2605 * type PersonProps = { name: ?string, favoriteColor: string }; 2606 * const makePerson: RecordFactory<PersonProps> = Record({ name: null, favoriteColor: 'unknown' }); 2607 * 2608 * // Use RecordOf<T> for defining new instances of that Record. 2609 * type Person = RecordOf<PersonProps>; 2610 * const alan: Person = makePerson({ name: 'Alan' }); 2611 * ``` 2612 */ 2613 namespace Factory {} 2614 2615 interface Factory<TProps extends object> { 2616 (values?: Partial<TProps> | Iterable<[string, unknown]>): Record<TProps> & 2617 Readonly<TProps>; 2618 new ( 2619 values?: Partial<TProps> | Iterable<[string, unknown]> 2620 ): Record<TProps> & Readonly<TProps>; 2621 2622 /** 2623 * The name provided to `Record(values, name)` can be accessed with 2624 * `displayName`. 2625 */ 2626 displayName: string; 2627 } 2628 2629 function Factory<TProps extends object>( 2630 values?: Partial<TProps> | Iterable<[string, unknown]> 2631 ): Record<TProps> & Readonly<TProps>; 2632 } 2633 2634 /** 2635 * Unlike other types in Immutable.js, the `Record()` function creates a new 2636 * Record Factory, which is a function that creates Record instances. 2637 * 2638 * See above for examples of using `Record()`. 2639 * 2640 * Note: `Record` is a factory function and not a class, and does not use the 2641 * `new` keyword during construction. 2642 */ 2643 function Record<TProps extends object>( 2644 defaultValues: TProps, 2645 name?: string 2646 ): Record.Factory<TProps>; 2647 2648 interface Record<TProps extends object> { 2649 // Reading values 2650 2651 has(key: string): key is keyof TProps & string; 2652 2653 /** 2654 * Returns the value associated with the provided key, which may be the 2655 * default value defined when creating the Record factory function. 2656 * 2657 * If the requested key is not defined by this Record type, then 2658 * notSetValue will be returned if provided. Note that this scenario would 2659 * produce an error when using Flow or TypeScript. 2660 */ 2661 get<K extends keyof TProps>(key: K, notSetValue?: unknown): TProps[K]; 2662 get<T>(key: string, notSetValue: T): T; 2663 2664 // Reading deep values 2665 2666 hasIn(keyPath: Iterable<unknown>): boolean; 2667 getIn(keyPath: Iterable<unknown>): unknown; 2668 2669 // Value equality 2670 2671 equals(other: unknown): boolean; 2672 hashCode(): number; 2673 2674 // Persistent changes 2675 2676 set<K extends keyof TProps>(key: K, value: TProps[K]): this; 2677 update<K extends keyof TProps>( 2678 key: K, 2679 updater: (value: TProps[K]) => TProps[K] 2680 ): this; 2681 merge( 2682 ...collections: Array<Partial<TProps> | Iterable<[string, unknown]>> 2683 ): this; 2684 mergeDeep( 2685 ...collections: Array<Partial<TProps> | Iterable<[string, unknown]>> 2686 ): this; 2687 2688 mergeWith( 2689 merger: (oldVal: unknown, newVal: unknown, key: keyof TProps) => unknown, 2690 ...collections: Array<Partial<TProps> | Iterable<[string, unknown]>> 2691 ): this; 2692 mergeDeepWith( 2693 merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown, 2694 ...collections: Array<Partial<TProps> | Iterable<[string, unknown]>> 2695 ): this; 2696 2697 /** 2698 * Returns a new instance of this Record type with the value for the 2699 * specific key set to its default value. 2700 * 2701 * @alias remove 2702 */ 2703 delete<K extends keyof TProps>(key: K): this; 2704 remove<K extends keyof TProps>(key: K): this; 2705 2706 /** 2707 * Returns a new instance of this Record type with all values set 2708 * to their default values. 2709 */ 2710 clear(): this; 2711 2712 // Deep persistent changes 2713 2714 setIn(keyPath: Iterable<unknown>, value: unknown): this; 2715 updateIn( 2716 keyPath: Iterable<unknown>, 2717 updater: (value: unknown) => unknown 2718 ): this; 2719 mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this; 2720 mergeDeepIn( 2721 keyPath: Iterable<unknown>, 2722 ...collections: Array<unknown> 2723 ): this; 2724 2725 /** 2726 * @alias removeIn 2727 */ 2728 deleteIn(keyPath: Iterable<unknown>): this; 2729 removeIn(keyPath: Iterable<unknown>): this; 2730 2731 // Conversion to JavaScript types 2732 2733 /** 2734 * Deeply converts this Record to equivalent native JavaScript Object. 2735 * 2736 * Note: This method may not be overridden. Objects with custom 2737 * serialization to plain JS may override toJSON() instead. 2738 */ 2739 toJS(): DeepCopy<TProps>; 2740 2741 /** 2742 * Shallowly converts this Record to equivalent native JavaScript Object. 2743 */ 2744 toJSON(): TProps; 2745 2746 /** 2747 * Shallowly converts this Record to equivalent JavaScript Object. 2748 */ 2749 toObject(): TProps; 2750 2751 // Transient changes 2752 2753 /** 2754 * Note: Not all methods can be used on a mutable collection or within 2755 * `withMutations`! Only `set` may be used mutatively. 2756 * 2757 * @see `Map#withMutations` 2758 */ 2759 withMutations(mutator: (mutable: this) => unknown): this; 2760 2761 /** 2762 * @see `Map#asMutable` 2763 */ 2764 asMutable(): this; 2765 2766 /** 2767 * @see `Map#wasAltered` 2768 */ 2769 wasAltered(): boolean; 2770 2771 /** 2772 * @see `Map#asImmutable` 2773 */ 2774 asImmutable(): this; 2775 2776 // Sequence algorithms 2777 2778 toSeq(): Seq.Keyed<keyof TProps, TProps[keyof TProps]>; 2779 2780 [Symbol.iterator](): IterableIterator<[keyof TProps, TProps[keyof TProps]]>; 2781 } 2782 2783 /** 2784 * RecordOf<T> is used in TypeScript to define interfaces expecting an 2785 * instance of record with type T. 2786 * 2787 * This is equivalent to an instance of a record created by a Record Factory. 2788 */ 2789 type RecordOf<TProps extends object> = Record<TProps> & Readonly<TProps>; 2790 2791 /** 2792 * `Seq` describes a lazy operation, allowing them to efficiently chain 2793 * use of all the higher-order collection methods (such as `map` and `filter`) 2794 * by not creating intermediate collections. 2795 * 2796 * **Seq is immutable** — Once a Seq is created, it cannot be 2797 * changed, appended to, rearranged or otherwise modified. Instead, any 2798 * mutative method called on a `Seq` will return a new `Seq`. 2799 * 2800 * **Seq is lazy** — `Seq` does as little work as necessary to respond to any 2801 * method call. Values are often created during iteration, including implicit 2802 * iteration when reducing or converting to a concrete data structure such as 2803 * a `List` or JavaScript `Array`. 2804 * 2805 * For example, the following performs no work, because the resulting 2806 * `Seq`'s values are never iterated: 2807 * 2808 * ```js 2809 * const { Seq } = require('immutable') 2810 * const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ]) 2811 * .filter(x => x % 2 !== 0) 2812 * .map(x => x * x) 2813 * ``` 2814 * 2815 * Once the `Seq` is used, it performs only the work necessary. In this 2816 * example, no intermediate arrays are ever created, filter is called three 2817 * times, and map is only called once: 2818 * 2819 * ```js 2820 * oddSquares.get(1); // 9 2821 * ``` 2822 * 2823 * Any collection can be converted to a lazy Seq with `Seq()`. 2824 * 2825 * <!-- runkit:activate --> 2826 * ```js 2827 * const { Map } = require('immutable') 2828 * const map = Map({ a: 1, b: 2, c: 3 }) 2829 * const lazySeq = Seq(map) 2830 * ``` 2831 * 2832 * `Seq` allows for the efficient chaining of operations, allowing for the 2833 * expression of logic that can otherwise be very tedious: 2834 * 2835 * ```js 2836 * lazySeq 2837 * .flip() 2838 * .map(key => key.toUpperCase()) 2839 * .flip() 2840 * // Seq { A: 1, B: 1, C: 1 } 2841 * ``` 2842 * 2843 * As well as expressing logic that would otherwise seem memory or time 2844 * limited, for example `Range` is a special kind of Lazy sequence. 2845 * 2846 * <!-- runkit:activate --> 2847 * ```js 2848 * const { Range } = require('immutable') 2849 * Range(1, Infinity) 2850 * .skip(1000) 2851 * .map(n => -n) 2852 * .filter(n => n % 2 === 0) 2853 * .take(2) 2854 * .reduce((r, n) => r * n, 1) 2855 * // 1006008 2856 * ``` 2857 * 2858 * Seq is often used to provide a rich collection API to JavaScript Object. 2859 * 2860 * ```js 2861 * Seq({ x: 0, y: 1, z: 2 }).map(v => v * 2).toObject(); 2862 * // { x: 0, y: 2, z: 4 } 2863 * ``` 2864 */ 2865 2866 namespace Seq { 2867 /** 2868 * True if `maybeSeq` is a Seq, it is not backed by a concrete 2869 * structure such as Map, List, or Set. 2870 */ 2871 function isSeq( 2872 maybeSeq: unknown 2873 ): maybeSeq is 2874 | Seq.Indexed<unknown> 2875 | Seq.Keyed<unknown, unknown> 2876 | Seq.Set<unknown>; 2877 2878 /** 2879 * `Seq` which represents key-value pairs. 2880 */ 2881 namespace Keyed {} 2882 2883 /** 2884 * Always returns a Seq.Keyed, if input is not keyed, expects an 2885 * collection of [K, V] tuples. 2886 * 2887 * Note: `Seq.Keyed` is a conversion function and not a class, and does not 2888 * use the `new` keyword during construction. 2889 */ 2890 function Keyed<K, V>(collection?: Iterable<[K, V]>): Seq.Keyed<K, V>; 2891 function Keyed<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>; 2892 2893 interface Keyed<K, V> extends Seq<K, V>, Collection.Keyed<K, V> { 2894 /** 2895 * Deeply converts this Keyed Seq to equivalent native JavaScript Object. 2896 * 2897 * Converts keys to Strings. 2898 */ 2899 toJS(): { [key in string | number | symbol]: DeepCopy<V> }; 2900 2901 /** 2902 * Shallowly converts this Keyed Seq to equivalent native JavaScript Object. 2903 * 2904 * Converts keys to Strings. 2905 */ 2906 toJSON(): { [key in string | number | symbol]: V }; 2907 2908 /** 2909 * Shallowly converts this collection to an Array. 2910 */ 2911 toArray(): Array<[K, V]>; 2912 2913 /** 2914 * Returns itself 2915 */ 2916 toSeq(): this; 2917 2918 /** 2919 * Returns a new Seq with other collections concatenated to this one. 2920 * 2921 * All entries will be present in the resulting Seq, even if they 2922 * have the same key. 2923 */ 2924 concat<KC, VC>( 2925 ...collections: Array<Iterable<[KC, VC]>> 2926 ): Seq.Keyed<K | KC, V | VC>; 2927 concat<C>( 2928 ...collections: Array<{ [key: string]: C }> 2929 ): Seq.Keyed<K | string, V | C>; 2930 2931 /** 2932 * Returns a new Seq.Keyed with values passed through a 2933 * `mapper` function. 2934 * 2935 * ```js 2936 * const { Seq } = require('immutable') 2937 * Seq.Keyed({ a: 1, b: 2 }).map(x => 10 * x) 2938 * // Seq { "a": 10, "b": 20 } 2939 * ``` 2940 * 2941 * Note: `map()` always returns a new instance, even if it produced the 2942 * same value at every step. 2943 */ 2944 map<M>( 2945 mapper: (value: V, key: K, iter: this) => M, 2946 context?: unknown 2947 ): Seq.Keyed<K, M>; 2948 2949 /** 2950 * @see Collection.Keyed.mapKeys 2951 */ 2952 mapKeys<M>( 2953 mapper: (key: K, value: V, iter: this) => M, 2954 context?: unknown 2955 ): Seq.Keyed<M, V>; 2956 2957 /** 2958 * @see Collection.Keyed.mapEntries 2959 */ 2960 mapEntries<KM, VM>( 2961 mapper: ( 2962 entry: [K, V], 2963 index: number, 2964 iter: this 2965 ) => [KM, VM] | undefined, 2966 context?: unknown 2967 ): Seq.Keyed<KM, VM>; 2968 2969 /** 2970 * Flat-maps the Seq, returning a Seq of the same type. 2971 * 2972 * Similar to `seq.map(...).flatten(true)`. 2973 */ 2974 flatMap<KM, VM>( 2975 mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, 2976 context?: unknown 2977 ): Seq.Keyed<KM, VM>; 2978 2979 /** 2980 * Returns a new Seq with only the entries for which the `predicate` 2981 * function returns true. 2982 * 2983 * Note: `filter()` always returns a new instance, even if it results in 2984 * not filtering out any values. 2985 */ 2986 filter<F extends V>( 2987 predicate: (value: V, key: K, iter: this) => value is F, 2988 context?: unknown 2989 ): Seq.Keyed<K, F>; 2990 filter( 2991 predicate: (value: V, key: K, iter: this) => unknown, 2992 context?: unknown 2993 ): this; 2994 2995 /** 2996 * Returns a new keyed Seq with the values for which the `predicate` 2997 * function returns false and another for which is returns true. 2998 */ 2999 partition<F extends V, C>( 3000 predicate: (this: C, value: V, key: K, iter: this) => value is F, 3001 context?: C 3002 ): [Seq.Keyed<K, V>, Seq.Keyed<K, F>]; 3003 partition<C>( 3004 predicate: (this: C, value: V, key: K, iter: this) => unknown, 3005 context?: C 3006 ): [this, this]; 3007 3008 /** 3009 * @see Collection.Keyed.flip 3010 */ 3011 flip(): Seq.Keyed<V, K>; 3012 3013 [Symbol.iterator](): IterableIterator<[K, V]>; 3014 } 3015 3016 /** 3017 * `Seq` which represents an ordered indexed list of values. 3018 */ 3019 namespace Indexed { 3020 /** 3021 * Provides an Seq.Indexed of the values provided. 3022 */ 3023 function of<T>(...values: Array<T>): Seq.Indexed<T>; 3024 } 3025 3026 /** 3027 * Always returns Seq.Indexed, discarding associated keys and 3028 * supplying incrementing indices. 3029 * 3030 * Note: `Seq.Indexed` is a conversion function and not a class, and does 3031 * not use the `new` keyword during construction. 3032 */ 3033 function Indexed<T>( 3034 collection?: Iterable<T> | ArrayLike<T> 3035 ): Seq.Indexed<T>; 3036 3037 interface Indexed<T> extends Seq<number, T>, Collection.Indexed<T> { 3038 /** 3039 * Deeply converts this Indexed Seq to equivalent native JavaScript Array. 3040 */ 3041 toJS(): Array<DeepCopy<T>>; 3042 3043 /** 3044 * Shallowly converts this Indexed Seq to equivalent native JavaScript Array. 3045 */ 3046 toJSON(): Array<T>; 3047 3048 /** 3049 * Shallowly converts this collection to an Array. 3050 */ 3051 toArray(): Array<T>; 3052 3053 /** 3054 * Returns itself 3055 */ 3056 toSeq(): this; 3057 3058 /** 3059 * Returns a new Seq with other collections concatenated to this one. 3060 */ 3061 concat<C>( 3062 ...valuesOrCollections: Array<Iterable<C> | C> 3063 ): Seq.Indexed<T | C>; 3064 3065 /** 3066 * Returns a new Seq.Indexed with values passed through a 3067 * `mapper` function. 3068 * 3069 * ```js 3070 * const { Seq } = require('immutable') 3071 * Seq.Indexed([ 1, 2 ]).map(x => 10 * x) 3072 * // Seq [ 10, 20 ] 3073 * ``` 3074 * 3075 * Note: `map()` always returns a new instance, even if it produced the 3076 * same value at every step. 3077 */ 3078 map<M>( 3079 mapper: (value: T, key: number, iter: this) => M, 3080 context?: unknown 3081 ): Seq.Indexed<M>; 3082 3083 /** 3084 * Flat-maps the Seq, returning a a Seq of the same type. 3085 * 3086 * Similar to `seq.map(...).flatten(true)`. 3087 */ 3088 flatMap<M>( 3089 mapper: (value: T, key: number, iter: this) => Iterable<M>, 3090 context?: unknown 3091 ): Seq.Indexed<M>; 3092 3093 /** 3094 * Returns a new Seq with only the values for which the `predicate` 3095 * function returns true. 3096 * 3097 * Note: `filter()` always returns a new instance, even if it results in 3098 * not filtering out any values. 3099 */ 3100 filter<F extends T>( 3101 predicate: (value: T, index: number, iter: this) => value is F, 3102 context?: unknown 3103 ): Seq.Indexed<F>; 3104 filter( 3105 predicate: (value: T, index: number, iter: this) => unknown, 3106 context?: unknown 3107 ): this; 3108 3109 /** 3110 * Returns a new indexed Seq with the values for which the `predicate` 3111 * function returns false and another for which is returns true. 3112 */ 3113 partition<F extends T, C>( 3114 predicate: (this: C, value: T, index: number, iter: this) => value is F, 3115 context?: C 3116 ): [Seq.Indexed<T>, Seq.Indexed<F>]; 3117 partition<C>( 3118 predicate: (this: C, value: T, index: number, iter: this) => unknown, 3119 context?: C 3120 ): [this, this]; 3121 3122 /** 3123 * Returns a Seq "zipped" with the provided collections. 3124 * 3125 * Like `zipWith`, but using the default `zipper`: creating an `Array`. 3126 * 3127 * ```js 3128 * const a = Seq([ 1, 2, 3 ]); 3129 * const b = Seq([ 4, 5, 6 ]); 3130 * const c = a.zip(b); // Seq [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] 3131 * ``` 3132 */ 3133 zip<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>; 3134 zip<U, V>( 3135 other: Collection<unknown, U>, 3136 other2: Collection<unknown, V> 3137 ): Seq.Indexed<[T, U, V]>; 3138 zip( 3139 ...collections: Array<Collection<unknown, unknown>> 3140 ): Seq.Indexed<unknown>; 3141 3142 /** 3143 * Returns a Seq "zipped" with the provided collections. 3144 * 3145 * Unlike `zip`, `zipAll` continues zipping until the longest collection is 3146 * exhausted. Missing values from shorter collections are filled with `undefined`. 3147 * 3148 * ```js 3149 * const a = Seq([ 1, 2 ]); 3150 * const b = Seq([ 3, 4, 5 ]); 3151 * const c = a.zipAll(b); // Seq [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] 3152 * ``` 3153 */ 3154 zipAll<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>; 3155 zipAll<U, V>( 3156 other: Collection<unknown, U>, 3157 other2: Collection<unknown, V> 3158 ): Seq.Indexed<[T, U, V]>; 3159 zipAll( 3160 ...collections: Array<Collection<unknown, unknown>> 3161 ): Seq.Indexed<unknown>; 3162 3163 /** 3164 * Returns a Seq "zipped" with the provided collections by using a 3165 * custom `zipper` function. 3166 * 3167 * ```js 3168 * const a = Seq([ 1, 2, 3 ]); 3169 * const b = Seq([ 4, 5, 6 ]); 3170 * const c = a.zipWith((a, b) => a + b, b); 3171 * // Seq [ 5, 7, 9 ] 3172 * ``` 3173 */ 3174 zipWith<U, Z>( 3175 zipper: (value: T, otherValue: U) => Z, 3176 otherCollection: Collection<unknown, U> 3177 ): Seq.Indexed<Z>; 3178 zipWith<U, V, Z>( 3179 zipper: (value: T, otherValue: U, thirdValue: V) => Z, 3180 otherCollection: Collection<unknown, U>, 3181 thirdCollection: Collection<unknown, V> 3182 ): Seq.Indexed<Z>; 3183 zipWith<Z>( 3184 zipper: (...values: Array<unknown>) => Z, 3185 ...collections: Array<Collection<unknown, unknown>> 3186 ): Seq.Indexed<Z>; 3187 3188 [Symbol.iterator](): IterableIterator<T>; 3189 } 3190 3191 /** 3192 * `Seq` which represents a set of values. 3193 * 3194 * Because `Seq` are often lazy, `Seq.Set` does not provide the same guarantee 3195 * of value uniqueness as the concrete `Set`. 3196 */ 3197 namespace Set { 3198 /** 3199 * Returns a Seq.Set of the provided values 3200 */ 3201 function of<T>(...values: Array<T>): Seq.Set<T>; 3202 } 3203 3204 /** 3205 * Always returns a Seq.Set, discarding associated indices or keys. 3206 * 3207 * Note: `Seq.Set` is a conversion function and not a class, and does not 3208 * use the `new` keyword during construction. 3209 */ 3210 function Set<T>(collection?: Iterable<T> | ArrayLike<T>): Seq.Set<T>; 3211 3212 interface Set<T> extends Seq<T, T>, Collection.Set<T> { 3213 /** 3214 * Deeply converts this Set Seq to equivalent native JavaScript Array. 3215 */ 3216 toJS(): Array<DeepCopy<T>>; 3217 3218 /** 3219 * Shallowly converts this Set Seq to equivalent native JavaScript Array. 3220 */ 3221 toJSON(): Array<T>; 3222 3223 /** 3224 * Shallowly converts this collection to an Array. 3225 */ 3226 toArray(): Array<T>; 3227 3228 /** 3229 * Returns itself 3230 */ 3231 toSeq(): this; 3232 3233 /** 3234 * Returns a new Seq with other collections concatenated to this one. 3235 * 3236 * All entries will be present in the resulting Seq, even if they 3237 * are duplicates. 3238 */ 3239 concat<U>(...collections: Array<Iterable<U>>): Seq.Set<T | U>; 3240 3241 /** 3242 * Returns a new Seq.Set with values passed through a 3243 * `mapper` function. 3244 * 3245 * ```js 3246 * Seq.Set([ 1, 2 ]).map(x => 10 * x) 3247 * // Seq { 10, 20 } 3248 * ``` 3249 * 3250 * Note: `map()` always returns a new instance, even if it produced the 3251 * same value at every step. 3252 */ 3253 map<M>( 3254 mapper: (value: T, key: T, iter: this) => M, 3255 context?: unknown 3256 ): Seq.Set<M>; 3257 3258 /** 3259 * Flat-maps the Seq, returning a Seq of the same type. 3260 * 3261 * Similar to `seq.map(...).flatten(true)`. 3262 */ 3263 flatMap<M>( 3264 mapper: (value: T, key: T, iter: this) => Iterable<M>, 3265 context?: unknown 3266 ): Seq.Set<M>; 3267 3268 /** 3269 * Returns a new Seq with only the values for which the `predicate` 3270 * function returns true. 3271 * 3272 * Note: `filter()` always returns a new instance, even if it results in 3273 * not filtering out any values. 3274 */ 3275 filter<F extends T>( 3276 predicate: (value: T, key: T, iter: this) => value is F, 3277 context?: unknown 3278 ): Seq.Set<F>; 3279 filter( 3280 predicate: (value: T, key: T, iter: this) => unknown, 3281 context?: unknown 3282 ): this; 3283 3284 /** 3285 * Returns a new set Seq with the values for which the `predicate` 3286 * function returns false and another for which is returns true. 3287 */ 3288 partition<F extends T, C>( 3289 predicate: (this: C, value: T, key: T, iter: this) => value is F, 3290 context?: C 3291 ): [Seq.Set<T>, Seq.Set<F>]; 3292 partition<C>( 3293 predicate: (this: C, value: T, key: T, iter: this) => unknown, 3294 context?: C 3295 ): [this, this]; 3296 3297 [Symbol.iterator](): IterableIterator<T>; 3298 } 3299 } 3300 3301 /** 3302 * Creates a Seq. 3303 * 3304 * Returns a particular kind of `Seq` based on the input. 3305 * 3306 * * If a `Seq`, that same `Seq`. 3307 * * If an `Collection`, a `Seq` of the same kind (Keyed, Indexed, or Set). 3308 * * If an Array-like, an `Seq.Indexed`. 3309 * * If an Iterable Object, an `Seq.Indexed`. 3310 * * If an Object, a `Seq.Keyed`. 3311 * 3312 * Note: An Iterator itself will be treated as an object, becoming a `Seq.Keyed`, 3313 * which is usually not what you want. You should turn your Iterator Object into 3314 * an iterable object by defining a Symbol.iterator (or @@iterator) method which 3315 * returns `this`. 3316 * 3317 * Note: `Seq` is a conversion function and not a class, and does not use the 3318 * `new` keyword during construction. 3319 */ 3320 function Seq<S extends Seq<unknown, unknown>>(seq: S): S; 3321 function Seq<K, V>(collection: Collection.Keyed<K, V>): Seq.Keyed<K, V>; 3322 function Seq<T>(collection: Collection.Set<T>): Seq.Set<T>; 3323 function Seq<T>( 3324 collection: Collection.Indexed<T> | Iterable<T> | ArrayLike<T> 3325 ): Seq.Indexed<T>; 3326 function Seq<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>; 3327 function Seq<K = unknown, V = unknown>(): Seq<K, V>; 3328 3329 interface Seq<K, V> extends Collection<K, V> { 3330 /** 3331 * Some Seqs can describe their size lazily. When this is the case, 3332 * size will be an integer. Otherwise it will be undefined. 3333 * 3334 * For example, Seqs returned from `map()` or `reverse()` 3335 * preserve the size of the original `Seq` while `filter()` does not. 3336 * 3337 * Note: `Range`, `Repeat` and `Seq`s made from `Array`s and `Object`s will 3338 * always have a size. 3339 */ 3340 readonly size: number | undefined; 3341 3342 // Force evaluation 3343 3344 /** 3345 * Because Sequences are lazy and designed to be chained together, they do 3346 * not cache their results. For example, this map function is called a total 3347 * of 6 times, as each `join` iterates the Seq of three values. 3348 * 3349 * var squares = Seq([ 1, 2, 3 ]).map(x => x * x) 3350 * squares.join() + squares.join() 3351 * 3352 * If you know a `Seq` will be used multiple times, it may be more 3353 * efficient to first cache it in memory. Here, the map function is called 3354 * only 3 times. 3355 * 3356 * var squares = Seq([ 1, 2, 3 ]).map(x => x * x).cacheResult() 3357 * squares.join() + squares.join() 3358 * 3359 * Use this method judiciously, as it must fully evaluate a Seq which can be 3360 * a burden on memory and possibly performance. 3361 * 3362 * Note: after calling `cacheResult`, a Seq will always have a `size`. 3363 */ 3364 cacheResult(): this; 3365 3366 // Sequence algorithms 3367 3368 /** 3369 * Returns a new Seq with values passed through a 3370 * `mapper` function. 3371 * 3372 * ```js 3373 * const { Seq } = require('immutable') 3374 * Seq([ 1, 2 ]).map(x => 10 * x) 3375 * // Seq [ 10, 20 ] 3376 * ``` 3377 * 3378 * Note: `map()` always returns a new instance, even if it produced the same 3379 * value at every step. 3380 */ 3381 map<M>( 3382 mapper: (value: V, key: K, iter: this) => M, 3383 context?: unknown 3384 ): Seq<K, M>; 3385 3386 /** 3387 * Returns a new Seq with values passed through a 3388 * `mapper` function. 3389 * 3390 * ```js 3391 * const { Seq } = require('immutable') 3392 * Seq([ 1, 2 ]).map(x => 10 * x) 3393 * // Seq [ 10, 20 ] 3394 * ``` 3395 * 3396 * Note: `map()` always returns a new instance, even if it produced the same 3397 * value at every step. 3398 * Note: used only for sets. 3399 */ 3400 map<M>( 3401 mapper: (value: V, key: K, iter: this) => M, 3402 context?: unknown 3403 ): Seq<M, M>; 3404 3405 /** 3406 * Flat-maps the Seq, returning a Seq of the same type. 3407 * 3408 * Similar to `seq.map(...).flatten(true)`. 3409 */ 3410 flatMap<M>( 3411 mapper: (value: V, key: K, iter: this) => Iterable<M>, 3412 context?: unknown 3413 ): Seq<K, M>; 3414 3415 /** 3416 * Flat-maps the Seq, returning a Seq of the same type. 3417 * 3418 * Similar to `seq.map(...).flatten(true)`. 3419 * Note: Used only for sets. 3420 */ 3421 flatMap<M>( 3422 mapper: (value: V, key: K, iter: this) => Iterable<M>, 3423 context?: unknown 3424 ): Seq<M, M>; 3425 3426 /** 3427 * Returns a new Seq with only the values for which the `predicate` 3428 * function returns true. 3429 * 3430 * Note: `filter()` always returns a new instance, even if it results in 3431 * not filtering out any values. 3432 */ 3433 filter<F extends V>( 3434 predicate: (value: V, key: K, iter: this) => value is F, 3435 context?: unknown 3436 ): Seq<K, F>; 3437 filter( 3438 predicate: (value: V, key: K, iter: this) => unknown, 3439 context?: unknown 3440 ): this; 3441 3442 /** 3443 * Returns a new Seq with the values for which the `predicate` function 3444 * returns false and another for which is returns true. 3445 */ 3446 partition<F extends V, C>( 3447 predicate: (this: C, value: V, key: K, iter: this) => value is F, 3448 context?: C 3449 ): [Seq<K, V>, Seq<K, F>]; 3450 partition<C>( 3451 predicate: (this: C, value: V, key: K, iter: this) => unknown, 3452 context?: C 3453 ): [this, this]; 3454 } 3455 3456 /** 3457 * The `Collection` is a set of (key, value) entries which can be iterated, and 3458 * is the base class for all collections in `immutable`, allowing them to 3459 * make use of all the Collection methods (such as `map` and `filter`). 3460 * 3461 * Note: A collection is always iterated in the same order, however that order 3462 * may not always be well defined, as is the case for the `Map` and `Set`. 3463 * 3464 * Collection is the abstract base class for concrete data structures. It 3465 * cannot be constructed directly. 3466 * 3467 * Implementations should extend one of the subclasses, `Collection.Keyed`, 3468 * `Collection.Indexed`, or `Collection.Set`. 3469 */ 3470 namespace Collection { 3471 /** 3472 * @deprecated use `const { isKeyed } = require('immutable')` 3473 */ 3474 function isKeyed( 3475 maybeKeyed: unknown 3476 ): maybeKeyed is Collection.Keyed<unknown, unknown>; 3477 3478 /** 3479 * @deprecated use `const { isIndexed } = require('immutable')` 3480 */ 3481 function isIndexed( 3482 maybeIndexed: unknown 3483 ): maybeIndexed is Collection.Indexed<unknown>; 3484 3485 /** 3486 * @deprecated use `const { isAssociative } = require('immutable')` 3487 */ 3488 function isAssociative( 3489 maybeAssociative: unknown 3490 ): maybeAssociative is 3491 | Collection.Keyed<unknown, unknown> 3492 | Collection.Indexed<unknown>; 3493 3494 /** 3495 * @deprecated use `const { isOrdered } = require('immutable')` 3496 */ 3497 function isOrdered(maybeOrdered: unknown): boolean; 3498 3499 /** 3500 * Keyed Collections have discrete keys tied to each value. 3501 * 3502 * When iterating `Collection.Keyed`, each iteration will yield a `[K, V]` 3503 * tuple, in other words, `Collection#entries` is the default iterator for 3504 * Keyed Collections. 3505 */ 3506 namespace Keyed {} 3507 3508 /** 3509 * Creates a Collection.Keyed 3510 * 3511 * Similar to `Collection()`, however it expects collection-likes of [K, V] 3512 * tuples if not constructed from a Collection.Keyed or JS Object. 3513 * 3514 * Note: `Collection.Keyed` is a conversion function and not a class, and 3515 * does not use the `new` keyword during construction. 3516 */ 3517 function Keyed<K, V>(collection?: Iterable<[K, V]>): Collection.Keyed<K, V>; 3518 function Keyed<V>(obj: { [key: string]: V }): Collection.Keyed<string, V>; 3519 3520 interface Keyed<K, V> extends Collection<K, V> { 3521 /** 3522 * Deeply converts this Keyed collection to equivalent native JavaScript Object. 3523 * 3524 * Converts keys to Strings. 3525 */ 3526 toJS(): { [key in string | number | symbol]: DeepCopy<V> }; 3527 3528 /** 3529 * Shallowly converts this Keyed collection to equivalent native JavaScript Object. 3530 * 3531 * Converts keys to Strings. 3532 */ 3533 toJSON(): { [key in string | number | symbol]: V }; 3534 3535 /** 3536 * Shallowly converts this collection to an Array. 3537 */ 3538 toArray(): Array<[K, V]>; 3539 3540 /** 3541 * Returns Seq.Keyed. 3542 * @override 3543 */ 3544 toSeq(): Seq.Keyed<K, V>; 3545 3546 // Sequence functions 3547 3548 /** 3549 * Returns a new Collection.Keyed of the same type where the keys and values 3550 * have been flipped. 3551 * 3552 * <!-- runkit:activate --> 3553 * ```js 3554 * const { Map } = require('immutable') 3555 * Map({ a: 'z', b: 'y' }).flip() 3556 * // Map { "z": "a", "y": "b" } 3557 * ``` 3558 */ 3559 flip(): Collection.Keyed<V, K>; 3560 3561 /** 3562 * Returns a new Collection with other collections concatenated to this one. 3563 */ 3564 concat<KC, VC>( 3565 ...collections: Array<Iterable<[KC, VC]>> 3566 ): Collection.Keyed<K | KC, V | VC>; 3567 concat<C>( 3568 ...collections: Array<{ [key: string]: C }> 3569 ): Collection.Keyed<K | string, V | C>; 3570 3571 /** 3572 * Returns a new Collection.Keyed with values passed through a 3573 * `mapper` function. 3574 * 3575 * ```js 3576 * const { Collection } = require('immutable') 3577 * Collection.Keyed({ a: 1, b: 2 }).map(x => 10 * x) 3578 * // Seq { "a": 10, "b": 20 } 3579 * ``` 3580 * 3581 * Note: `map()` always returns a new instance, even if it produced the 3582 * same value at every step. 3583 */ 3584 map<M>( 3585 mapper: (value: V, key: K, iter: this) => M, 3586 context?: unknown 3587 ): Collection.Keyed<K, M>; 3588 3589 /** 3590 * Returns a new Collection.Keyed of the same type with keys passed through 3591 * a `mapper` function. 3592 * 3593 * <!-- runkit:activate --> 3594 * ```js 3595 * const { Map } = require('immutable') 3596 * Map({ a: 1, b: 2 }).mapKeys(x => x.toUpperCase()) 3597 * // Map { "A": 1, "B": 2 } 3598 * ``` 3599 * 3600 * Note: `mapKeys()` always returns a new instance, even if it produced 3601 * the same key at every step. 3602 */ 3603 mapKeys<M>( 3604 mapper: (key: K, value: V, iter: this) => M, 3605 context?: unknown 3606 ): Collection.Keyed<M, V>; 3607 3608 /** 3609 * Returns a new Collection.Keyed of the same type with entries 3610 * ([key, value] tuples) passed through a `mapper` function. 3611 * 3612 * <!-- runkit:activate --> 3613 * ```js 3614 * const { Map } = require('immutable') 3615 * Map({ a: 1, b: 2 }) 3616 * .mapEntries(([ k, v ]) => [ k.toUpperCase(), v * 2 ]) 3617 * // Map { "A": 2, "B": 4 } 3618 * ``` 3619 * 3620 * Note: `mapEntries()` always returns a new instance, even if it produced 3621 * the same entry at every step. 3622 * 3623 * If the mapper function returns `undefined`, then the entry will be filtered 3624 */ 3625 mapEntries<KM, VM>( 3626 mapper: ( 3627 entry: [K, V], 3628 index: number, 3629 iter: this 3630 ) => [KM, VM] | undefined, 3631 context?: unknown 3632 ): Collection.Keyed<KM, VM>; 3633 3634 /** 3635 * Flat-maps the Collection, returning a Collection of the same type. 3636 * 3637 * Similar to `collection.map(...).flatten(true)`. 3638 */ 3639 flatMap<KM, VM>( 3640 mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, 3641 context?: unknown 3642 ): Collection.Keyed<KM, VM>; 3643 3644 /** 3645 * Returns a new Collection with only the values for which the `predicate` 3646 * function returns true. 3647 * 3648 * Note: `filter()` always returns a new instance, even if it results in 3649 * not filtering out any values. 3650 */ 3651 filter<F extends V>( 3652 predicate: (value: V, key: K, iter: this) => value is F, 3653 context?: unknown 3654 ): Collection.Keyed<K, F>; 3655 filter( 3656 predicate: (value: V, key: K, iter: this) => unknown, 3657 context?: unknown 3658 ): this; 3659 3660 /** 3661 * Returns a new keyed Collection with the values for which the 3662 * `predicate` function returns false and another for which is returns 3663 * true. 3664 */ 3665 partition<F extends V, C>( 3666 predicate: (this: C, value: V, key: K, iter: this) => value is F, 3667 context?: C 3668 ): [Collection.Keyed<K, V>, Collection.Keyed<K, F>]; 3669 partition<C>( 3670 predicate: (this: C, value: V, key: K, iter: this) => unknown, 3671 context?: C 3672 ): [this, this]; 3673 3674 [Symbol.iterator](): IterableIterator<[K, V]>; 3675 } 3676 3677 /** 3678 * Indexed Collections have incrementing numeric keys. They exhibit 3679 * slightly different behavior than `Collection.Keyed` for some methods in order 3680 * to better mirror the behavior of JavaScript's `Array`, and add methods 3681 * which do not make sense on non-indexed Collections such as `indexOf`. 3682 * 3683 * Unlike JavaScript arrays, `Collection.Indexed`s are always dense. "Unset" 3684 * indices and `undefined` indices are indistinguishable, and all indices from 3685 * 0 to `size` are visited when iterated. 3686 * 3687 * All Collection.Indexed methods return re-indexed Collections. In other words, 3688 * indices always start at 0 and increment until size. If you wish to 3689 * preserve indices, using them as keys, convert to a Collection.Keyed by 3690 * calling `toKeyedSeq`. 3691 */ 3692 namespace Indexed {} 3693 3694 /** 3695 * Creates a new Collection.Indexed. 3696 * 3697 * Note: `Collection.Indexed` is a conversion function and not a class, and 3698 * does not use the `new` keyword during construction. 3699 */ 3700 function Indexed<T>( 3701 collection?: Iterable<T> | ArrayLike<T> 3702 ): Collection.Indexed<T>; 3703 3704 interface Indexed<T> extends Collection<number, T> { 3705 /** 3706 * Deeply converts this Indexed collection to equivalent native JavaScript Array. 3707 */ 3708 toJS(): Array<DeepCopy<T>>; 3709 3710 /** 3711 * Shallowly converts this Indexed collection to equivalent native JavaScript Array. 3712 */ 3713 toJSON(): Array<T>; 3714 3715 /** 3716 * Shallowly converts this collection to an Array. 3717 */ 3718 toArray(): Array<T>; 3719 3720 // Reading values 3721 3722 /** 3723 * Returns the value associated with the provided index, or notSetValue if 3724 * the index is beyond the bounds of the Collection. 3725 * 3726 * `index` may be a negative number, which indexes back from the end of the 3727 * Collection. `s.get(-1)` gets the last item in the Collection. 3728 */ 3729 get<NSV>(index: number, notSetValue: NSV): T | NSV; 3730 get(index: number): T | undefined; 3731 3732 // Conversion to Seq 3733 3734 /** 3735 * Returns Seq.Indexed. 3736 * @override 3737 */ 3738 toSeq(): Seq.Indexed<T>; 3739 3740 /** 3741 * If this is a collection of [key, value] entry tuples, it will return a 3742 * Seq.Keyed of those entries. 3743 */ 3744 fromEntrySeq(): Seq.Keyed<unknown, unknown>; 3745 3746 // Combination 3747 3748 /** 3749 * Returns a Collection of the same type with `separator` between each item 3750 * in this Collection. 3751 */ 3752 interpose(separator: T): this; 3753 3754 /** 3755 * Returns a Collection of the same type with the provided `collections` 3756 * interleaved into this collection. 3757 * 3758 * The resulting Collection includes the first item from each, then the 3759 * second from each, etc. 3760 * 3761 * <!-- runkit:activate 3762 * { "preamble": "require('immutable')"} 3763 * --> 3764 * ```js 3765 * const { List } = require('immutable') 3766 * List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ])) 3767 * // List [ 1, "A", 2, "B", 3, "C" ] 3768 * ``` 3769 * 3770 * The shortest Collection stops interleave. 3771 * 3772 * <!-- runkit:activate 3773 * { "preamble": "const { List } = require('immutable')" } 3774 * --> 3775 * ```js 3776 * List([ 1, 2, 3 ]).interleave( 3777 * List([ 'A', 'B' ]), 3778 * List([ 'X', 'Y', 'Z' ]) 3779 * ) 3780 * // List [ 1, "A", "X", 2, "B", "Y" ] 3781 * ``` 3782 * 3783 * Since `interleave()` re-indexes values, it produces a complete copy, 3784 * which has `O(N)` complexity. 3785 * 3786 * Note: `interleave` *cannot* be used in `withMutations`. 3787 */ 3788 interleave(...collections: Array<Collection<unknown, T>>): this; 3789 3790 /** 3791 * Splice returns a new indexed Collection by replacing a region of this 3792 * Collection with new values. If values are not provided, it only skips the 3793 * region to be removed. 3794 * 3795 * `index` may be a negative number, which indexes back from the end of the 3796 * Collection. `s.splice(-2)` splices after the second to last item. 3797 * 3798 * <!-- runkit:activate --> 3799 * ```js 3800 * const { List } = require('immutable') 3801 * List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's') 3802 * // List [ "a", "q", "r", "s", "d" ] 3803 * ``` 3804 * 3805 * Since `splice()` re-indexes values, it produces a complete copy, which 3806 * has `O(N)` complexity. 3807 * 3808 * Note: `splice` *cannot* be used in `withMutations`. 3809 */ 3810 splice(index: number, removeNum: number, ...values: Array<T>): this; 3811 3812 /** 3813 * Returns a Collection of the same type "zipped" with the provided 3814 * collections. 3815 * 3816 * Like `zipWith`, but using the default `zipper`: creating an `Array`. 3817 * 3818 * 3819 * <!-- runkit:activate 3820 * { "preamble": "const { List } = require('immutable')" } 3821 * --> 3822 * ```js 3823 * const a = List([ 1, 2, 3 ]); 3824 * const b = List([ 4, 5, 6 ]); 3825 * const c = a.zip(b); // List [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] 3826 * ``` 3827 */ 3828 zip<U>(other: Collection<unknown, U>): Collection.Indexed<[T, U]>; 3829 zip<U, V>( 3830 other: Collection<unknown, U>, 3831 other2: Collection<unknown, V> 3832 ): Collection.Indexed<[T, U, V]>; 3833 zip( 3834 ...collections: Array<Collection<unknown, unknown>> 3835 ): Collection.Indexed<unknown>; 3836 3837 /** 3838 * Returns a Collection "zipped" with the provided collections. 3839 * 3840 * Unlike `zip`, `zipAll` continues zipping until the longest collection is 3841 * exhausted. Missing values from shorter collections are filled with `undefined`. 3842 * 3843 * ```js 3844 * const a = List([ 1, 2 ]); 3845 * const b = List([ 3, 4, 5 ]); 3846 * const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] 3847 * ``` 3848 */ 3849 zipAll<U>(other: Collection<unknown, U>): Collection.Indexed<[T, U]>; 3850 zipAll<U, V>( 3851 other: Collection<unknown, U>, 3852 other2: Collection<unknown, V> 3853 ): Collection.Indexed<[T, U, V]>; 3854 zipAll( 3855 ...collections: Array<Collection<unknown, unknown>> 3856 ): Collection.Indexed<unknown>; 3857 3858 /** 3859 * Returns a Collection of the same type "zipped" with the provided 3860 * collections by using a custom `zipper` function. 3861 * 3862 * <!-- runkit:activate 3863 * { "preamble": "const { List } = require('immutable')" } 3864 * --> 3865 * ```js 3866 * const a = List([ 1, 2, 3 ]); 3867 * const b = List([ 4, 5, 6 ]); 3868 * const c = a.zipWith((a, b) => a + b, b); 3869 * // List [ 5, 7, 9 ] 3870 * ``` 3871 */ 3872 zipWith<U, Z>( 3873 zipper: (value: T, otherValue: U) => Z, 3874 otherCollection: Collection<unknown, U> 3875 ): Collection.Indexed<Z>; 3876 zipWith<U, V, Z>( 3877 zipper: (value: T, otherValue: U, thirdValue: V) => Z, 3878 otherCollection: Collection<unknown, U>, 3879 thirdCollection: Collection<unknown, V> 3880 ): Collection.Indexed<Z>; 3881 zipWith<Z>( 3882 zipper: (...values: Array<unknown>) => Z, 3883 ...collections: Array<Collection<unknown, unknown>> 3884 ): Collection.Indexed<Z>; 3885 3886 // Search for value 3887 3888 /** 3889 * Returns the first index at which a given value can be found in the 3890 * Collection, or -1 if it is not present. 3891 */ 3892 indexOf(searchValue: T): number; 3893 3894 /** 3895 * Returns the last index at which a given value can be found in the 3896 * Collection, or -1 if it is not present. 3897 */ 3898 lastIndexOf(searchValue: T): number; 3899 3900 /** 3901 * Returns the first index in the Collection where a value satisfies the 3902 * provided predicate function. Otherwise -1 is returned. 3903 */ 3904 findIndex( 3905 predicate: (value: T, index: number, iter: this) => boolean, 3906 context?: unknown 3907 ): number; 3908 3909 /** 3910 * Returns the last index in the Collection where a value satisfies the 3911 * provided predicate function. Otherwise -1 is returned. 3912 */ 3913 findLastIndex( 3914 predicate: (value: T, index: number, iter: this) => boolean, 3915 context?: unknown 3916 ): number; 3917 3918 // Sequence algorithms 3919 3920 /** 3921 * Returns a new Collection with other collections concatenated to this one. 3922 */ 3923 concat<C>( 3924 ...valuesOrCollections: Array<Iterable<C> | C> 3925 ): Collection.Indexed<T | C>; 3926 3927 /** 3928 * Returns a new Collection.Indexed with values passed through a 3929 * `mapper` function. 3930 * 3931 * ```js 3932 * const { Collection } = require('immutable') 3933 * Collection.Indexed([1,2]).map(x => 10 * x) 3934 * // Seq [ 1, 2 ] 3935 * ``` 3936 * 3937 * Note: `map()` always returns a new instance, even if it produced the 3938 * same value at every step. 3939 */ 3940 map<M>( 3941 mapper: (value: T, key: number, iter: this) => M, 3942 context?: unknown 3943 ): Collection.Indexed<M>; 3944 3945 /** 3946 * Flat-maps the Collection, returning a Collection of the same type. 3947 * 3948 * Similar to `collection.map(...).flatten(true)`. 3949 */ 3950 flatMap<M>( 3951 mapper: (value: T, key: number, iter: this) => Iterable<M>, 3952 context?: unknown 3953 ): Collection.Indexed<M>; 3954 3955 /** 3956 * Returns a new Collection with only the values for which the `predicate` 3957 * function returns true. 3958 * 3959 * Note: `filter()` always returns a new instance, even if it results in 3960 * not filtering out any values. 3961 */ 3962 filter<F extends T>( 3963 predicate: (value: T, index: number, iter: this) => value is F, 3964 context?: unknown 3965 ): Collection.Indexed<F>; 3966 filter( 3967 predicate: (value: T, index: number, iter: this) => unknown, 3968 context?: unknown 3969 ): this; 3970 3971 /** 3972 * Returns a new indexed Collection with the values for which the 3973 * `predicate` function returns false and another for which is returns 3974 * true. 3975 */ 3976 partition<F extends T, C>( 3977 predicate: (this: C, value: T, index: number, iter: this) => value is F, 3978 context?: C 3979 ): [Collection.Indexed<T>, Collection.Indexed<F>]; 3980 partition<C>( 3981 predicate: (this: C, value: T, index: number, iter: this) => unknown, 3982 context?: C 3983 ): [this, this]; 3984 3985 [Symbol.iterator](): IterableIterator<T>; 3986 } 3987 3988 /** 3989 * Set Collections only represent values. They have no associated keys or 3990 * indices. Duplicate values are possible in the lazy `Seq.Set`s, however 3991 * the concrete `Set` Collection does not allow duplicate values. 3992 * 3993 * Collection methods on Collection.Set such as `map` and `forEach` will provide 3994 * the value as both the first and second arguments to the provided function. 3995 * 3996 * ```js 3997 * const { Collection } = require('immutable') 3998 * const seq = Collection.Set([ 'A', 'B', 'C' ]) 3999 * // Seq { "A", "B", "C" } 4000 * seq.forEach((v, k) => 4001 * assert.equal(v, k) 4002 * ) 4003 * ``` 4004 */ 4005 namespace Set {} 4006 4007 /** 4008 * Similar to `Collection()`, but always returns a Collection.Set. 4009 * 4010 * Note: `Collection.Set` is a factory function and not a class, and does 4011 * not use the `new` keyword during construction. 4012 */ 4013 function Set<T>(collection?: Iterable<T> | ArrayLike<T>): Collection.Set<T>; 4014 4015 interface Set<T> extends Collection<T, T> { 4016 /** 4017 * Deeply converts this Set collection to equivalent native JavaScript Array. 4018 */ 4019 toJS(): Array<DeepCopy<T>>; 4020 4021 /** 4022 * Shallowly converts this Set collection to equivalent native JavaScript Array. 4023 */ 4024 toJSON(): Array<T>; 4025 4026 /** 4027 * Shallowly converts this collection to an Array. 4028 */ 4029 toArray(): Array<T>; 4030 4031 /** 4032 * Returns Seq.Set. 4033 * @override 4034 */ 4035 toSeq(): Seq.Set<T>; 4036 4037 // Sequence algorithms 4038 4039 /** 4040 * Returns a new Collection with other collections concatenated to this one. 4041 */ 4042 concat<U>(...collections: Array<Iterable<U>>): Collection.Set<T | U>; 4043 4044 /** 4045 * Returns a new Collection.Set with values passed through a 4046 * `mapper` function. 4047 * 4048 * ``` 4049 * Collection.Set([ 1, 2 ]).map(x => 10 * x) 4050 * // Seq { 1, 2 } 4051 * ``` 4052 * 4053 * Note: `map()` always returns a new instance, even if it produced the 4054 * same value at every step. 4055 */ 4056 map<M>( 4057 mapper: (value: T, key: T, iter: this) => M, 4058 context?: unknown 4059 ): Collection.Set<M>; 4060 4061 /** 4062 * Flat-maps the Collection, returning a Collection of the same type. 4063 * 4064 * Similar to `collection.map(...).flatten(true)`. 4065 */ 4066 flatMap<M>( 4067 mapper: (value: T, key: T, iter: this) => Iterable<M>, 4068 context?: unknown 4069 ): Collection.Set<M>; 4070 4071 /** 4072 * Returns a new Collection with only the values for which the `predicate` 4073 * function returns true. 4074 * 4075 * Note: `filter()` always returns a new instance, even if it results in 4076 * not filtering out any values. 4077 */ 4078 filter<F extends T>( 4079 predicate: (value: T, key: T, iter: this) => value is F, 4080 context?: unknown 4081 ): Collection.Set<F>; 4082 filter( 4083 predicate: (value: T, key: T, iter: this) => unknown, 4084 context?: unknown 4085 ): this; 4086 4087 /** 4088 * Returns a new set Collection with the values for which the 4089 * `predicate` function returns false and another for which is returns 4090 * true. 4091 */ 4092 partition<F extends T, C>( 4093 predicate: (this: C, value: T, key: T, iter: this) => value is F, 4094 context?: C 4095 ): [Collection.Set<T>, Collection.Set<F>]; 4096 partition<C>( 4097 predicate: (this: C, value: T, key: T, iter: this) => unknown, 4098 context?: C 4099 ): [this, this]; 4100 4101 [Symbol.iterator](): IterableIterator<T>; 4102 } 4103 } 4104 4105 /** 4106 * Creates a Collection. 4107 * 4108 * The type of Collection created is based on the input. 4109 * 4110 * * If an `Collection`, that same `Collection`. 4111 * * If an Array-like, an `Collection.Indexed`. 4112 * * If an Object with an Iterator defined, an `Collection.Indexed`. 4113 * * If an Object, an `Collection.Keyed`. 4114 * 4115 * This methods forces the conversion of Objects and Strings to Collections. 4116 * If you want to ensure that a Collection of one item is returned, use 4117 * `Seq.of`. 4118 * 4119 * Note: An Iterator itself will be treated as an object, becoming a `Seq.Keyed`, 4120 * which is usually not what you want. You should turn your Iterator Object into 4121 * an iterable object by defining a Symbol.iterator (or @@iterator) method which 4122 * returns `this`. 4123 * 4124 * Note: `Collection` is a conversion function and not a class, and does not 4125 * use the `new` keyword during construction. 4126 */ 4127 function Collection<I extends Collection<unknown, unknown>>(collection: I): I; 4128 function Collection<T>( 4129 collection: Iterable<T> | ArrayLike<T> 4130 ): Collection.Indexed<T>; 4131 function Collection<V>(obj: { 4132 [key: string]: V; 4133 }): Collection.Keyed<string, V>; 4134 function Collection<K = unknown, V = unknown>(): Collection<K, V>; 4135 4136 interface Collection<K, V> extends ValueObject { 4137 // Value equality 4138 4139 /** 4140 * True if this and the other Collection have value equality, as defined 4141 * by `Immutable.is()`. 4142 * 4143 * Note: This is equivalent to `Immutable.is(this, other)`, but provided to 4144 * allow for chained expressions. 4145 */ 4146 equals(other: unknown): boolean; 4147 4148 /** 4149 * Computes and returns the hashed identity for this Collection. 4150 * 4151 * The `hashCode` of a Collection is used to determine potential equality, 4152 * and is used when adding this to a `Set` or as a key in a `Map`, enabling 4153 * lookup via a different instance. 4154 * 4155 * <!-- runkit:activate 4156 * { "preamble": "const { Set, List } = require('immutable')" } 4157 * --> 4158 * ```js 4159 * const a = List([ 1, 2, 3 ]); 4160 * const b = List([ 1, 2, 3 ]); 4161 * assert.notStrictEqual(a, b); // different instances 4162 * const set = Set([ a ]); 4163 * assert.equal(set.has(b), true); 4164 * ``` 4165 * 4166 * If two values have the same `hashCode`, they are [not guaranteed 4167 * to be equal][Hash Collision]. If two values have different `hashCode`s, 4168 * they must not be equal. 4169 * 4170 * [Hash Collision]: https://en.wikipedia.org/wiki/Collision_(computer_science) 4171 */ 4172 hashCode(): number; 4173 4174 // Reading values 4175 4176 /** 4177 * Returns the value associated with the provided key, or notSetValue if 4178 * the Collection does not contain this key. 4179 * 4180 * Note: it is possible a key may be associated with an `undefined` value, 4181 * so if `notSetValue` is not provided and this method returns `undefined`, 4182 * that does not guarantee the key was not found. 4183 */ 4184 get<NSV>(key: K, notSetValue: NSV): V | NSV; 4185 get(key: K): V | undefined; 4186 4187 /** 4188 * True if a key exists within this `Collection`, using `Immutable.is` 4189 * to determine equality 4190 */ 4191 has(key: K): boolean; 4192 4193 /** 4194 * True if a value exists within this `Collection`, using `Immutable.is` 4195 * to determine equality 4196 * @alias contains 4197 */ 4198 includes(value: V): boolean; 4199 contains(value: V): boolean; 4200 4201 /** 4202 * In case the `Collection` is not empty returns the first element of the 4203 * `Collection`. 4204 * In case the `Collection` is empty returns the optional default 4205 * value if provided, if no default value is provided returns undefined. 4206 */ 4207 first<NSV = undefined>(notSetValue?: NSV): V | NSV; 4208 4209 /** 4210 * In case the `Collection` is not empty returns the last element of the 4211 * `Collection`. 4212 * In case the `Collection` is empty returns the optional default 4213 * value if provided, if no default value is provided returns undefined. 4214 */ 4215 last<NSV = undefined>(notSetValue?: NSV): V | NSV; 4216 4217 // Reading deep values 4218 4219 /** 4220 * Returns the value found by following a path of keys or indices through 4221 * nested Collections. 4222 * 4223 * <!-- runkit:activate --> 4224 * ```js 4225 * const { Map, List } = require('immutable') 4226 * const deepData = Map({ x: List([ Map({ y: 123 }) ]) }); 4227 * deepData.getIn(['x', 0, 'y']) // 123 4228 * ``` 4229 * 4230 * Plain JavaScript Object or Arrays may be nested within an Immutable.js 4231 * Collection, and getIn() can access those values as well: 4232 * 4233 * <!-- runkit:activate --> 4234 * ```js 4235 * const { Map, List } = require('immutable') 4236 * const deepData = Map({ x: [ { y: 123 } ] }); 4237 * deepData.getIn(['x', 0, 'y']) // 123 4238 * ``` 4239 */ 4240 getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown; 4241 4242 /** 4243 * True if the result of following a path of keys or indices through nested 4244 * Collections results in a set value. 4245 */ 4246 hasIn(searchKeyPath: Iterable<unknown>): boolean; 4247 4248 // Persistent changes 4249 4250 /** 4251 * This can be very useful as a way to "chain" a normal function into a 4252 * sequence of methods. RxJS calls this "let" and lodash calls it "thru". 4253 * 4254 * For example, to sum a Seq after mapping and filtering: 4255 * 4256 * <!-- runkit:activate --> 4257 * ```js 4258 * const { Seq } = require('immutable') 4259 * 4260 * function sum(collection) { 4261 * return collection.reduce((sum, x) => sum + x, 0) 4262 * } 4263 * 4264 * Seq([ 1, 2, 3 ]) 4265 * .map(x => x + 1) 4266 * .filter(x => x % 2 === 0) 4267 * .update(sum) 4268 * // 6 4269 * ``` 4270 */ 4271 update<R>(updater: (value: this) => R): R; 4272 4273 // Conversion to JavaScript types 4274 4275 /** 4276 * Deeply converts this Collection to equivalent native JavaScript Array or Object. 4277 * 4278 * `Collection.Indexed`, and `Collection.Set` become `Array`, while 4279 * `Collection.Keyed` become `Object`, converting keys to Strings. 4280 */ 4281 toJS(): 4282 | Array<DeepCopy<V>> 4283 | { [key in string | number | symbol]: DeepCopy<V> }; 4284 4285 /** 4286 * Shallowly converts this Collection to equivalent native JavaScript Array or Object. 4287 * 4288 * `Collection.Indexed`, and `Collection.Set` become `Array`, while 4289 * `Collection.Keyed` become `Object`, converting keys to Strings. 4290 */ 4291 toJSON(): Array<V> | { [key in string | number | symbol]: V }; 4292 4293 /** 4294 * Shallowly converts this collection to an Array. 4295 * 4296 * `Collection.Indexed`, and `Collection.Set` produce an Array of values. 4297 * `Collection.Keyed` produce an Array of [key, value] tuples. 4298 */ 4299 toArray(): Array<V> | Array<[K, V]>; 4300 4301 /** 4302 * Shallowly converts this Collection to an Object. 4303 * 4304 * Converts keys to Strings. 4305 */ 4306 toObject(): { [key: string]: V }; 4307 4308 // Conversion to Collections 4309 4310 /** 4311 * Converts this Collection to a Map, Throws if keys are not hashable. 4312 * 4313 * Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided 4314 * for convenience and to allow for chained expressions. 4315 */ 4316 toMap(): Map<K, V>; 4317 4318 /** 4319 * Converts this Collection to a Map, maintaining the order of iteration. 4320 * 4321 * Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but 4322 * provided for convenience and to allow for chained expressions. 4323 */ 4324 toOrderedMap(): OrderedMap<K, V>; 4325 4326 /** 4327 * Converts this Collection to a Set, discarding keys. Throws if values 4328 * are not hashable. 4329 * 4330 * Note: This is equivalent to `Set(this)`, but provided to allow for 4331 * chained expressions. 4332 */ 4333 toSet(): Set<V>; 4334 4335 /** 4336 * Converts this Collection to a Set, maintaining the order of iteration and 4337 * discarding keys. 4338 * 4339 * Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided 4340 * for convenience and to allow for chained expressions. 4341 */ 4342 toOrderedSet(): OrderedSet<V>; 4343 4344 /** 4345 * Converts this Collection to a List, discarding keys. 4346 * 4347 * This is similar to `List(collection)`, but provided to allow for chained 4348 * expressions. However, when called on `Map` or other keyed collections, 4349 * `collection.toList()` discards the keys and creates a list of only the 4350 * values, whereas `List(collection)` creates a list of entry tuples. 4351 * 4352 * <!-- runkit:activate --> 4353 * ```js 4354 * const { Map, List } = require('immutable') 4355 * var myMap = Map({ a: 'Apple', b: 'Banana' }) 4356 * List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ] 4357 * myMap.toList() // List [ "Apple", "Banana" ] 4358 * ``` 4359 */ 4360 toList(): List<V>; 4361 4362 /** 4363 * Converts this Collection to a Stack, discarding keys. Throws if values 4364 * are not hashable. 4365 * 4366 * Note: This is equivalent to `Stack(this)`, but provided to allow for 4367 * chained expressions. 4368 */ 4369 toStack(): Stack<V>; 4370 4371 // Conversion to Seq 4372 4373 /** 4374 * Converts this Collection to a Seq of the same kind (indexed, 4375 * keyed, or set). 4376 */ 4377 toSeq(): Seq<K, V>; 4378 4379 /** 4380 * Returns a Seq.Keyed from this Collection where indices are treated as keys. 4381 * 4382 * This is useful if you want to operate on an 4383 * Collection.Indexed and preserve the [index, value] pairs. 4384 * 4385 * The returned Seq will have identical iteration order as 4386 * this Collection. 4387 * 4388 * <!-- runkit:activate --> 4389 * ```js 4390 * const { Seq } = require('immutable') 4391 * const indexedSeq = Seq([ 'A', 'B', 'C' ]) 4392 * // Seq [ "A", "B", "C" ] 4393 * indexedSeq.filter(v => v === 'B') 4394 * // Seq [ "B" ] 4395 * const keyedSeq = indexedSeq.toKeyedSeq() 4396 * // Seq { 0: "A", 1: "B", 2: "C" } 4397 * keyedSeq.filter(v => v === 'B') 4398 * // Seq { 1: "B" } 4399 * ``` 4400 */ 4401 toKeyedSeq(): Seq.Keyed<K, V>; 4402 4403 /** 4404 * Returns an Seq.Indexed of the values of this Collection, discarding keys. 4405 */ 4406 toIndexedSeq(): Seq.Indexed<V>; 4407 4408 /** 4409 * Returns a Seq.Set of the values of this Collection, discarding keys. 4410 */ 4411 toSetSeq(): Seq.Set<V>; 4412 4413 // Iterators 4414 4415 /** 4416 * An iterator of this `Collection`'s keys. 4417 * 4418 * Note: this will return an ES6 iterator which does not support 4419 * Immutable.js sequence algorithms. Use `keySeq` instead, if this is 4420 * what you want. 4421 */ 4422 keys(): IterableIterator<K>; 4423 4424 /** 4425 * An iterator of this `Collection`'s values. 4426 * 4427 * Note: this will return an ES6 iterator which does not support 4428 * Immutable.js sequence algorithms. Use `valueSeq` instead, if this is 4429 * what you want. 4430 */ 4431 values(): IterableIterator<V>; 4432 4433 /** 4434 * An iterator of this `Collection`'s entries as `[ key, value ]` tuples. 4435 * 4436 * Note: this will return an ES6 iterator which does not support 4437 * Immutable.js sequence algorithms. Use `entrySeq` instead, if this is 4438 * what you want. 4439 */ 4440 entries(): IterableIterator<[K, V]>; 4441 4442 [Symbol.iterator](): IterableIterator<unknown>; 4443 4444 // Collections (Seq) 4445 4446 /** 4447 * Returns a new Seq.Indexed of the keys of this Collection, 4448 * discarding values. 4449 */ 4450 keySeq(): Seq.Indexed<K>; 4451 4452 /** 4453 * Returns an Seq.Indexed of the values of this Collection, discarding keys. 4454 */ 4455 valueSeq(): Seq.Indexed<V>; 4456 4457 /** 4458 * Returns a new Seq.Indexed of [key, value] tuples. 4459 */ 4460 entrySeq(): Seq.Indexed<[K, V]>; 4461 4462 // Sequence algorithms 4463 4464 /** 4465 * Returns a new Collection of the same type with values passed through a 4466 * `mapper` function. 4467 * 4468 * <!-- runkit:activate --> 4469 * ```js 4470 * const { Collection } = require('immutable') 4471 * Collection({ a: 1, b: 2 }).map(x => 10 * x) 4472 * // Seq { "a": 10, "b": 20 } 4473 * ``` 4474 * 4475 * Note: `map()` always returns a new instance, even if it produced the same 4476 * value at every step. 4477 */ 4478 map<M>( 4479 mapper: (value: V, key: K, iter: this) => M, 4480 context?: unknown 4481 ): Collection<K, M>; 4482 4483 /** 4484 * Note: used only for sets, which return Collection<M, M> but are otherwise 4485 * identical to normal `map()`. 4486 * 4487 * @ignore 4488 */ 4489 map(...args: Array<never>): unknown; 4490 4491 /** 4492 * Returns a new Collection of the same type with only the entries for which 4493 * the `predicate` function returns true. 4494 * 4495 * <!-- runkit:activate --> 4496 * ```js 4497 * const { Map } = require('immutable') 4498 * Map({ a: 1, b: 2, c: 3, d: 4}).filter(x => x % 2 === 0) 4499 * // Map { "b": 2, "d": 4 } 4500 * ``` 4501 * 4502 * Note: `filter()` always returns a new instance, even if it results in 4503 * not filtering out any values. 4504 */ 4505 filter<F extends V>( 4506 predicate: (value: V, key: K, iter: this) => value is F, 4507 context?: unknown 4508 ): Collection<K, F>; 4509 filter( 4510 predicate: (value: V, key: K, iter: this) => unknown, 4511 context?: unknown 4512 ): this; 4513 4514 /** 4515 * Returns a new Collection of the same type with only the entries for which 4516 * the `predicate` function returns false. 4517 * 4518 * <!-- runkit:activate --> 4519 * ```js 4520 * const { Map } = require('immutable') 4521 * Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0) 4522 * // Map { "a": 1, "c": 3 } 4523 * ``` 4524 * 4525 * Note: `filterNot()` always returns a new instance, even if it results in 4526 * not filtering out any values. 4527 */ 4528 filterNot( 4529 predicate: (value: V, key: K, iter: this) => boolean, 4530 context?: unknown 4531 ): this; 4532 4533 /** 4534 * Returns a new Collection with the values for which the `predicate` 4535 * function returns false and another for which is returns true. 4536 */ 4537 partition<F extends V, C>( 4538 predicate: (this: C, value: V, key: K, iter: this) => value is F, 4539 context?: C 4540 ): [Collection<K, V>, Collection<K, F>]; 4541 partition<C>( 4542 predicate: (this: C, value: V, key: K, iter: this) => unknown, 4543 context?: C 4544 ): [this, this]; 4545 4546 /** 4547 * Returns a new Collection of the same type in reverse order. 4548 */ 4549 reverse(): this; 4550 4551 /** 4552 * Returns a new Collection of the same type which includes the same entries, 4553 * stably sorted by using a `comparator`. 4554 * 4555 * If a `comparator` is not provided, a default comparator uses `<` and `>`. 4556 * 4557 * `comparator(valueA, valueB)`: 4558 * 4559 * * Returns `0` if the elements should not be swapped. 4560 * * Returns `-1` (or any negative number) if `valueA` comes before `valueB` 4561 * * Returns `1` (or any positive number) if `valueA` comes after `valueB` 4562 * * Alternatively, can return a value of the `PairSorting` enum type 4563 * * Is pure, i.e. it must always return the same value for the same pair 4564 * of values. 4565 * 4566 * When sorting collections which have no defined order, their ordered 4567 * equivalents will be returned. e.g. `map.sort()` returns OrderedMap. 4568 * 4569 * <!-- runkit:activate --> 4570 * ```js 4571 * const { Map } = require('immutable') 4572 * Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => { 4573 * if (a < b) { return -1; } 4574 * if (a > b) { return 1; } 4575 * if (a === b) { return 0; } 4576 * }); 4577 * // OrderedMap { "a": 1, "b": 2, "c": 3 } 4578 * ``` 4579 * 4580 * Note: `sort()` Always returns a new instance, even if the original was 4581 * already sorted. 4582 * 4583 * Note: This is always an eager operation. 4584 */ 4585 sort(comparator?: Comparator<V>): this; 4586 4587 /** 4588 * Like `sort`, but also accepts a `comparatorValueMapper` which allows for 4589 * sorting by more sophisticated means: 4590 * 4591 * <!-- runkit:activate --> 4592 * ```js 4593 * const { Map } = require('immutable') 4594 * const beattles = Map({ 4595 * John: { name: "Lennon" }, 4596 * Paul: { name: "McCartney" }, 4597 * George: { name: "Harrison" }, 4598 * Ringo: { name: "Starr" }, 4599 * }); 4600 * beattles.sortBy(member => member.name); 4601 * ``` 4602 * 4603 * Note: `sortBy()` Always returns a new instance, even if the original was 4604 * already sorted. 4605 * 4606 * Note: This is always an eager operation. 4607 */ 4608 sortBy<C>( 4609 comparatorValueMapper: (value: V, key: K, iter: this) => C, 4610 comparator?: Comparator<C> 4611 ): this; 4612 4613 /** 4614 * Returns a `Map` of `Collection`, grouped by the return 4615 * value of the `grouper` function. 4616 * 4617 * Note: This is always an eager operation. 4618 * 4619 * <!-- runkit:activate --> 4620 * ```js 4621 * const { List, Map } = require('immutable') 4622 * const listOfMaps = List([ 4623 * Map({ v: 0 }), 4624 * Map({ v: 1 }), 4625 * Map({ v: 1 }), 4626 * Map({ v: 0 }), 4627 * Map({ v: 2 }) 4628 * ]) 4629 * const groupsOfMaps = listOfMaps.groupBy(x => x.get('v')) 4630 * // Map { 4631 * // 0: List [ Map{ "v": 0 }, Map { "v": 0 } ], 4632 * // 1: List [ Map{ "v": 1 }, Map { "v": 1 } ], 4633 * // 2: List [ Map{ "v": 2 } ], 4634 * // } 4635 * ``` 4636 */ 4637 groupBy<G>( 4638 grouper: (value: V, key: K, iter: this) => G, 4639 context?: unknown 4640 ): Map<G, this>; 4641 4642 // Side effects 4643 4644 /** 4645 * The `sideEffect` is executed for every entry in the Collection. 4646 * 4647 * Unlike `Array#forEach`, if any call of `sideEffect` returns 4648 * `false`, the iteration will stop. Returns the number of entries iterated 4649 * (including the last iteration which returned false). 4650 */ 4651 forEach( 4652 sideEffect: (value: V, key: K, iter: this) => unknown, 4653 context?: unknown 4654 ): number; 4655 4656 // Creating subsets 4657 4658 /** 4659 * Returns a new Collection of the same type representing a portion of this 4660 * Collection from start up to but not including end. 4661 * 4662 * If begin is negative, it is offset from the end of the Collection. e.g. 4663 * `slice(-2)` returns a Collection of the last two entries. If it is not 4664 * provided the new Collection will begin at the beginning of this Collection. 4665 * 4666 * If end is negative, it is offset from the end of the Collection. e.g. 4667 * `slice(0, -1)` returns a Collection of everything but the last entry. If 4668 * it is not provided, the new Collection will continue through the end of 4669 * this Collection. 4670 * 4671 * If the requested slice is equivalent to the current Collection, then it 4672 * will return itself. 4673 */ 4674 slice(begin?: number, end?: number): this; 4675 4676 /** 4677 * Returns a new Collection of the same type containing all entries except 4678 * the first. 4679 */ 4680 rest(): this; 4681 4682 /** 4683 * Returns a new Collection of the same type containing all entries except 4684 * the last. 4685 */ 4686 butLast(): this; 4687 4688 /** 4689 * Returns a new Collection of the same type which excludes the first `amount` 4690 * entries from this Collection. 4691 */ 4692 skip(amount: number): this; 4693 4694 /** 4695 * Returns a new Collection of the same type which excludes the last `amount` 4696 * entries from this Collection. 4697 */ 4698 skipLast(amount: number): this; 4699 4700 /** 4701 * Returns a new Collection of the same type which includes entries starting 4702 * from when `predicate` first returns false. 4703 * 4704 * <!-- runkit:activate --> 4705 * ```js 4706 * const { List } = require('immutable') 4707 * List([ 'dog', 'frog', 'cat', 'hat', 'god' ]) 4708 * .skipWhile(x => x.match(/g/)) 4709 * // List [ "cat", "hat", "god" ] 4710 * ``` 4711 */ 4712 skipWhile( 4713 predicate: (value: V, key: K, iter: this) => boolean, 4714 context?: unknown 4715 ): this; 4716 4717 /** 4718 * Returns a new Collection of the same type which includes entries starting 4719 * from when `predicate` first returns true. 4720 * 4721 * <!-- runkit:activate --> 4722 * ```js 4723 * const { List } = require('immutable') 4724 * List([ 'dog', 'frog', 'cat', 'hat', 'god' ]) 4725 * .skipUntil(x => x.match(/hat/)) 4726 * // List [ "hat", "god" ] 4727 * ``` 4728 */ 4729 skipUntil( 4730 predicate: (value: V, key: K, iter: this) => boolean, 4731 context?: unknown 4732 ): this; 4733 4734 /** 4735 * Returns a new Collection of the same type which includes the first `amount` 4736 * entries from this Collection. 4737 */ 4738 take(amount: number): this; 4739 4740 /** 4741 * Returns a new Collection of the same type which includes the last `amount` 4742 * entries from this Collection. 4743 */ 4744 takeLast(amount: number): this; 4745 4746 /** 4747 * Returns a new Collection of the same type which includes entries from this 4748 * Collection as long as the `predicate` returns true. 4749 * 4750 * <!-- runkit:activate --> 4751 * ```js 4752 * const { List } = require('immutable') 4753 * List([ 'dog', 'frog', 'cat', 'hat', 'god' ]) 4754 * .takeWhile(x => x.match(/o/)) 4755 * // List [ "dog", "frog" ] 4756 * ``` 4757 */ 4758 takeWhile( 4759 predicate: (value: V, key: K, iter: this) => boolean, 4760 context?: unknown 4761 ): this; 4762 4763 /** 4764 * Returns a new Collection of the same type which includes entries from this 4765 * Collection as long as the `predicate` returns false. 4766 * 4767 * <!-- runkit:activate --> 4768 * ```js 4769 * const { List } = require('immutable') 4770 * List([ 'dog', 'frog', 'cat', 'hat', 'god' ]) 4771 * .takeUntil(x => x.match(/at/)) 4772 * // List [ "dog", "frog" ] 4773 * ``` 4774 */ 4775 takeUntil( 4776 predicate: (value: V, key: K, iter: this) => boolean, 4777 context?: unknown 4778 ): this; 4779 4780 // Combination 4781 4782 /** 4783 * Returns a new Collection of the same type with other values and 4784 * collection-like concatenated to this one. 4785 * 4786 * For Seqs, all entries will be present in the resulting Seq, even if they 4787 * have the same key. 4788 */ 4789 concat( 4790 ...valuesOrCollections: Array<unknown> 4791 ): Collection<unknown, unknown>; 4792 4793 /** 4794 * Flattens nested Collections. 4795 * 4796 * Will deeply flatten the Collection by default, returning a Collection of the 4797 * same type, but a `depth` can be provided in the form of a number or 4798 * boolean (where true means to shallowly flatten one level). A depth of 0 4799 * (or shallow: false) will deeply flatten. 4800 * 4801 * Flattens only others Collection, not Arrays or Objects. 4802 * 4803 * Note: `flatten(true)` operates on Collection<unknown, Collection<K, V>> and 4804 * returns Collection<K, V> 4805 */ 4806 flatten(depth?: number): Collection<unknown, unknown>; 4807 // tslint:disable-next-line unified-signatures 4808 flatten(shallow?: boolean): Collection<unknown, unknown>; 4809 4810 /** 4811 * Flat-maps the Collection, returning a Collection of the same type. 4812 * 4813 * Similar to `collection.map(...).flatten(true)`. 4814 */ 4815 flatMap<M>( 4816 mapper: (value: V, key: K, iter: this) => Iterable<M>, 4817 context?: unknown 4818 ): Collection<K, M>; 4819 4820 /** 4821 * Flat-maps the Collection, returning a Collection of the same type. 4822 * 4823 * Similar to `collection.map(...).flatten(true)`. 4824 * Used for Dictionaries only. 4825 */ 4826 flatMap<KM, VM>( 4827 mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, 4828 context?: unknown 4829 ): Collection<KM, VM>; 4830 4831 // Reducing a value 4832 4833 /** 4834 * Reduces the Collection to a value by calling the `reducer` for every entry 4835 * in the Collection and passing along the reduced value. 4836 * 4837 * If `initialReduction` is not provided, the first item in the 4838 * Collection will be used. 4839 * 4840 * @see `Array#reduce`. 4841 */ 4842 reduce<R>( 4843 reducer: (reduction: R, value: V, key: K, iter: this) => R, 4844 initialReduction: R, 4845 context?: unknown 4846 ): R; 4847 reduce<R>( 4848 reducer: (reduction: V | R, value: V, key: K, iter: this) => R 4849 ): R; 4850 4851 /** 4852 * Reduces the Collection in reverse (from the right side). 4853 * 4854 * Note: Similar to this.reverse().reduce(), and provided for parity 4855 * with `Array#reduceRight`. 4856 */ 4857 reduceRight<R>( 4858 reducer: (reduction: R, value: V, key: K, iter: this) => R, 4859 initialReduction: R, 4860 context?: unknown 4861 ): R; 4862 reduceRight<R>( 4863 reducer: (reduction: V | R, value: V, key: K, iter: this) => R 4864 ): R; 4865 4866 /** 4867 * True if `predicate` returns true for all entries in the Collection. 4868 */ 4869 every( 4870 predicate: (value: V, key: K, iter: this) => boolean, 4871 context?: unknown 4872 ): boolean; 4873 4874 /** 4875 * True if `predicate` returns true for any entry in the Collection. 4876 */ 4877 some( 4878 predicate: (value: V, key: K, iter: this) => boolean, 4879 context?: unknown 4880 ): boolean; 4881 4882 /** 4883 * Joins values together as a string, inserting a separator between each. 4884 * The default separator is `","`. 4885 */ 4886 join(separator?: string): string; 4887 4888 /** 4889 * Returns true if this Collection includes no values. 4890 * 4891 * For some lazy `Seq`, `isEmpty` might need to iterate to determine 4892 * emptiness. At most one iteration will occur. 4893 */ 4894 isEmpty(): boolean; 4895 4896 /** 4897 * Returns the size of this Collection. 4898 * 4899 * Regardless of if this Collection can describe its size lazily (some Seqs 4900 * cannot), this method will always return the correct size. E.g. it 4901 * evaluates a lazy `Seq` if necessary. 4902 * 4903 * If `predicate` is provided, then this returns the count of entries in the 4904 * Collection for which the `predicate` returns true. 4905 */ 4906 count(): number; 4907 count( 4908 predicate: (value: V, key: K, iter: this) => boolean, 4909 context?: unknown 4910 ): number; 4911 4912 /** 4913 * Returns a `Seq.Keyed` of counts, grouped by the return value of 4914 * the `grouper` function. 4915 * 4916 * Note: This is not a lazy operation. 4917 */ 4918 countBy<G>( 4919 grouper: (value: V, key: K, iter: this) => G, 4920 context?: unknown 4921 ): Map<G, number>; 4922 4923 // Search for value 4924 4925 /** 4926 * Returns the first value for which the `predicate` returns true. 4927 */ 4928 find( 4929 predicate: (value: V, key: K, iter: this) => boolean, 4930 context?: unknown, 4931 notSetValue?: V 4932 ): V | undefined; 4933 4934 /** 4935 * Returns the last value for which the `predicate` returns true. 4936 * 4937 * Note: `predicate` will be called for each entry in reverse. 4938 */ 4939 findLast( 4940 predicate: (value: V, key: K, iter: this) => boolean, 4941 context?: unknown, 4942 notSetValue?: V 4943 ): V | undefined; 4944 4945 /** 4946 * Returns the first [key, value] entry for which the `predicate` returns true. 4947 */ 4948 findEntry( 4949 predicate: (value: V, key: K, iter: this) => boolean, 4950 context?: unknown, 4951 notSetValue?: V 4952 ): [K, V] | undefined; 4953 4954 /** 4955 * Returns the last [key, value] entry for which the `predicate` 4956 * returns true. 4957 * 4958 * Note: `predicate` will be called for each entry in reverse. 4959 */ 4960 findLastEntry( 4961 predicate: (value: V, key: K, iter: this) => boolean, 4962 context?: unknown, 4963 notSetValue?: V 4964 ): [K, V] | undefined; 4965 4966 /** 4967 * Returns the key for which the `predicate` returns true. 4968 */ 4969 findKey( 4970 predicate: (value: V, key: K, iter: this) => boolean, 4971 context?: unknown 4972 ): K | undefined; 4973 4974 /** 4975 * Returns the last key for which the `predicate` returns true. 4976 * 4977 * Note: `predicate` will be called for each entry in reverse. 4978 */ 4979 findLastKey( 4980 predicate: (value: V, key: K, iter: this) => boolean, 4981 context?: unknown 4982 ): K | undefined; 4983 4984 /** 4985 * Returns the key associated with the search value, or undefined. 4986 */ 4987 keyOf(searchValue: V): K | undefined; 4988 4989 /** 4990 * Returns the last key associated with the search value, or undefined. 4991 */ 4992 lastKeyOf(searchValue: V): K | undefined; 4993 4994 /** 4995 * Returns the maximum value in this collection. If any values are 4996 * comparatively equivalent, the first one found will be returned. 4997 * 4998 * The `comparator` is used in the same way as `Collection#sort`. If it is not 4999 * provided, the default comparator is `>`. 5000 * 5001 * When two values are considered equivalent, the first encountered will be 5002 * returned. Otherwise, `max` will operate independent of the order of input 5003 * as long as the comparator is commutative. The default comparator `>` is 5004 * commutative *only* when types do not differ. 5005 * 5006 * If `comparator` returns 0 and either value is NaN, undefined, or null, 5007 * that value will be returned. 5008 */ 5009 max(comparator?: Comparator<V>): V | undefined; 5010 5011 /** 5012 * Like `max`, but also accepts a `comparatorValueMapper` which allows for 5013 * comparing by more sophisticated means: 5014 * 5015 * <!-- runkit:activate --> 5016 * ```js 5017 * const { List, } = require('immutable'); 5018 * const l = List([ 5019 * { name: 'Bob', avgHit: 1 }, 5020 * { name: 'Max', avgHit: 3 }, 5021 * { name: 'Lili', avgHit: 2 } , 5022 * ]); 5023 * l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 } 5024 * ``` 5025 */ 5026 maxBy<C>( 5027 comparatorValueMapper: (value: V, key: K, iter: this) => C, 5028 comparator?: Comparator<C> 5029 ): V | undefined; 5030 5031 /** 5032 * Returns the minimum value in this collection. If any values are 5033 * comparatively equivalent, the first one found will be returned. 5034 * 5035 * The `comparator` is used in the same way as `Collection#sort`. If it is not 5036 * provided, the default comparator is `<`. 5037 * 5038 * When two values are considered equivalent, the first encountered will be 5039 * returned. Otherwise, `min` will operate independent of the order of input 5040 * as long as the comparator is commutative. The default comparator `<` is 5041 * commutative *only* when types do not differ. 5042 * 5043 * If `comparator` returns 0 and either value is NaN, undefined, or null, 5044 * that value will be returned. 5045 */ 5046 min(comparator?: Comparator<V>): V | undefined; 5047 5048 /** 5049 * Like `min`, but also accepts a `comparatorValueMapper` which allows for 5050 * comparing by more sophisticated means: 5051 * 5052 * <!-- runkit:activate --> 5053 * ```js 5054 * const { List, } = require('immutable'); 5055 * const l = List([ 5056 * { name: 'Bob', avgHit: 1 }, 5057 * { name: 'Max', avgHit: 3 }, 5058 * { name: 'Lili', avgHit: 2 } , 5059 * ]); 5060 * l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 } 5061 * ``` 5062 */ 5063 minBy<C>( 5064 comparatorValueMapper: (value: V, key: K, iter: this) => C, 5065 comparator?: Comparator<C> 5066 ): V | undefined; 5067 5068 // Comparison 5069 5070 /** 5071 * True if `iter` includes every value in this Collection. 5072 */ 5073 isSubset(iter: Iterable<V>): boolean; 5074 5075 /** 5076 * True if this Collection includes every value in `iter`. 5077 */ 5078 isSuperset(iter: Iterable<V>): boolean; 5079 } 5080 5081 /** 5082 * The interface to fulfill to qualify as a Value Object. 5083 */ 5084 interface ValueObject { 5085 /** 5086 * True if this and the other Collection have value equality, as defined 5087 * by `Immutable.is()`. 5088 * 5089 * Note: This is equivalent to `Immutable.is(this, other)`, but provided to 5090 * allow for chained expressions. 5091 */ 5092 equals(other: unknown): boolean; 5093 5094 /** 5095 * Computes and returns the hashed identity for this Collection. 5096 * 5097 * The `hashCode` of a Collection is used to determine potential equality, 5098 * and is used when adding this to a `Set` or as a key in a `Map`, enabling 5099 * lookup via a different instance. 5100 * 5101 * <!-- runkit:activate --> 5102 * ```js 5103 * const { List, Set } = require('immutable'); 5104 * const a = List([ 1, 2, 3 ]); 5105 * const b = List([ 1, 2, 3 ]); 5106 * assert.notStrictEqual(a, b); // different instances 5107 * const set = Set([ a ]); 5108 * assert.equal(set.has(b), true); 5109 * ``` 5110 * 5111 * Note: hashCode() MUST return a Uint32 number. The easiest way to 5112 * guarantee this is to return `myHash | 0` from a custom implementation. 5113 * 5114 * If two values have the same `hashCode`, they are [not guaranteed 5115 * to be equal][Hash Collision]. If two values have different `hashCode`s, 5116 * they must not be equal. 5117 * 5118 * Note: `hashCode()` is not guaranteed to always be called before 5119 * `equals()`. Most but not all Immutable.js collections use hash codes to 5120 * organize their internal data structures, while all Immutable.js 5121 * collections use equality during lookups. 5122 * 5123 * [Hash Collision]: https://en.wikipedia.org/wiki/Collision_(computer_science) 5124 */ 5125 hashCode(): number; 5126 } 5127 5128 /** 5129 * Deeply converts plain JS objects and arrays to Immutable Maps and Lists. 5130 * 5131 * `fromJS` will convert Arrays and [array-like objects][2] to a List, and 5132 * plain objects (without a custom prototype) to a Map. [Iterable objects][3] 5133 * may be converted to List, Map, or Set. 5134 * 5135 * If a `reviver` is optionally provided, it will be called with every 5136 * collection as a Seq (beginning with the most nested collections 5137 * and proceeding to the top-level collection itself), along with the key 5138 * referring to each collection and the parent JS object provided as `this`. 5139 * For the top level, object, the key will be `""`. This `reviver` is expected 5140 * to return a new Immutable Collection, allowing for custom conversions from 5141 * deep JS objects. Finally, a `path` is provided which is the sequence of 5142 * keys to this value from the starting value. 5143 * 5144 * `reviver` acts similarly to the [same parameter in `JSON.parse`][1]. 5145 * 5146 * If `reviver` is not provided, the default behavior will convert Objects 5147 * into Maps and Arrays into Lists like so: 5148 * 5149 * <!-- runkit:activate --> 5150 * ```js 5151 * const { fromJS, isKeyed } = require('immutable') 5152 * function (key, value) { 5153 * return isKeyed(value) ? value.toMap() : value.toList() 5154 * } 5155 * ``` 5156 * 5157 * Accordingly, this example converts native JS data to OrderedMap and List: 5158 * 5159 * <!-- runkit:activate --> 5160 * ```js 5161 * const { fromJS, isKeyed } = require('immutable') 5162 * fromJS({ a: {b: [10, 20, 30]}, c: 40}, function (key, value, path) { 5163 * console.log(key, value, path) 5164 * return isKeyed(value) ? value.toOrderedMap() : value.toList() 5165 * }) 5166 * 5167 * > "b", [ 10, 20, 30 ], [ "a", "b" ] 5168 * > "a", {b: [10, 20, 30]}, [ "a" ] 5169 * > "", {a: {b: [10, 20, 30]}, c: 40}, [] 5170 * ``` 5171 * 5172 * Keep in mind, when using JS objects to construct Immutable Maps, that 5173 * JavaScript Object properties are always strings, even if written in a 5174 * quote-less shorthand, while Immutable Maps accept keys of any type. 5175 * 5176 * <!-- runkit:activate --> 5177 * ```js 5178 * const { Map } = require('immutable') 5179 * let obj = { 1: "one" }; 5180 * Object.keys(obj); // [ "1" ] 5181 * assert.equal(obj["1"], obj[1]); // "one" === "one" 5182 * 5183 * let map = Map(obj); 5184 * assert.notEqual(map.get("1"), map.get(1)); // "one" !== undefined 5185 * ``` 5186 * 5187 * Property access for JavaScript Objects first converts the key to a string, 5188 * but since Immutable Map keys can be of any type the argument to `get()` is 5189 * not altered. 5190 * 5191 * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter 5192 * "Using the reviver parameter" 5193 * [2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#working_with_array-like_objects 5194 * "Working with array-like objects" 5195 * [3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol 5196 * "The iterable protocol" 5197 */ 5198 function fromJS<JSValue>( 5199 jsValue: JSValue, 5200 reviver?: undefined 5201 ): FromJS<JSValue>; 5202 function fromJS( 5203 jsValue: unknown, 5204 reviver?: ( 5205 key: string | number, 5206 sequence: Collection.Keyed<string, unknown> | Collection.Indexed<unknown>, 5207 path?: Array<string | number> 5208 ) => unknown 5209 ): Collection<unknown, unknown>; 5210 5211 type FromJS<JSValue> = JSValue extends FromJSNoTransform 5212 ? JSValue 5213 : JSValue extends Array<any> 5214 ? FromJSArray<JSValue> 5215 : JSValue extends {} 5216 ? FromJSObject<JSValue> 5217 : any; 5218 5219 type FromJSNoTransform = 5220 | Collection<any, any> 5221 | number 5222 | string 5223 | null 5224 | undefined; 5225 5226 type FromJSArray<JSValue> = JSValue extends Array<infer T> 5227 ? List<FromJS<T>> 5228 : never; 5229 5230 type FromJSObject<JSValue> = JSValue extends {} 5231 ? Map<keyof JSValue, FromJS<JSValue[keyof JSValue]>> 5232 : never; 5233 5234 /** 5235 * Value equality check with semantics similar to `Object.is`, but treats 5236 * Immutable `Collection`s as values, equal if the second `Collection` includes 5237 * equivalent values. 5238 * 5239 * It's used throughout Immutable when checking for equality, including `Map` 5240 * key equality and `Set` membership. 5241 * 5242 * <!-- runkit:activate --> 5243 * ```js 5244 * const { Map, is } = require('immutable') 5245 * const map1 = Map({ a: 1, b: 1, c: 1 }) 5246 * const map2 = Map({ a: 1, b: 1, c: 1 }) 5247 * assert.equal(map1 !== map2, true) 5248 * assert.equal(Object.is(map1, map2), false) 5249 * assert.equal(is(map1, map2), true) 5250 * ``` 5251 * 5252 * `is()` compares primitive types like strings and numbers, Immutable.js 5253 * collections like `Map` and `List`, but also any custom object which 5254 * implements `ValueObject` by providing `equals()` and `hashCode()` methods. 5255 * 5256 * Note: Unlike `Object.is`, `Immutable.is` assumes `0` and `-0` are the same 5257 * value, matching the behavior of ES6 Map key equality. 5258 */ 5259 function is(first: unknown, second: unknown): boolean; 5260 5261 /** 5262 * The `hash()` function is an important part of how Immutable determines if 5263 * two values are equivalent and is used to determine how to store those 5264 * values. Provided with any value, `hash()` will return a 31-bit integer. 5265 * 5266 * When designing Objects which may be equal, it's important that when a 5267 * `.equals()` method returns true, that both values `.hashCode()` method 5268 * return the same value. `hash()` may be used to produce those values. 5269 * 5270 * For non-Immutable Objects that do not provide a `.hashCode()` functions 5271 * (including plain Objects, plain Arrays, Date objects, etc), a unique hash 5272 * value will be created for each *instance*. That is, the create hash 5273 * represents referential equality, and not value equality for Objects. This 5274 * ensures that if that Object is mutated over time that its hash code will 5275 * remain consistent, allowing Objects to be used as keys and values in 5276 * Immutable.js collections. 5277 * 5278 * Note that `hash()` attempts to balance between speed and avoiding 5279 * collisions, however it makes no attempt to produce secure hashes. 5280 * 5281 * *New in Version 4.0* 5282 */ 5283 function hash(value: unknown): number; 5284 5285 /** 5286 * True if `maybeImmutable` is an Immutable Collection or Record. 5287 * 5288 * Note: Still returns true even if the collections is within a `withMutations()`. 5289 * 5290 * <!-- runkit:activate --> 5291 * ```js 5292 * const { isImmutable, Map, List, Stack } = require('immutable'); 5293 * isImmutable([]); // false 5294 * isImmutable({}); // false 5295 * isImmutable(Map()); // true 5296 * isImmutable(List()); // true 5297 * isImmutable(Stack()); // true 5298 * isImmutable(Map().asMutable()); // true 5299 * ``` 5300 */ 5301 function isImmutable( 5302 maybeImmutable: unknown 5303 ): maybeImmutable is Collection<unknown, unknown>; 5304 5305 /** 5306 * True if `maybeCollection` is a Collection, or any of its subclasses. 5307 * 5308 * <!-- runkit:activate --> 5309 * ```js 5310 * const { isCollection, Map, List, Stack } = require('immutable'); 5311 * isCollection([]); // false 5312 * isCollection({}); // false 5313 * isCollection(Map()); // true 5314 * isCollection(List()); // true 5315 * isCollection(Stack()); // true 5316 * ``` 5317 */ 5318 function isCollection( 5319 maybeCollection: unknown 5320 ): maybeCollection is Collection<unknown, unknown>; 5321 5322 /** 5323 * True if `maybeKeyed` is a Collection.Keyed, or any of its subclasses. 5324 * 5325 * <!-- runkit:activate --> 5326 * ```js 5327 * const { isKeyed, Map, List, Stack } = require('immutable'); 5328 * isKeyed([]); // false 5329 * isKeyed({}); // false 5330 * isKeyed(Map()); // true 5331 * isKeyed(List()); // false 5332 * isKeyed(Stack()); // false 5333 * ``` 5334 */ 5335 function isKeyed( 5336 maybeKeyed: unknown 5337 ): maybeKeyed is Collection.Keyed<unknown, unknown>; 5338 5339 /** 5340 * True if `maybeIndexed` is a Collection.Indexed, or any of its subclasses. 5341 * 5342 * <!-- runkit:activate --> 5343 * ```js 5344 * const { isIndexed, Map, List, Stack, Set } = require('immutable'); 5345 * isIndexed([]); // false 5346 * isIndexed({}); // false 5347 * isIndexed(Map()); // false 5348 * isIndexed(List()); // true 5349 * isIndexed(Stack()); // true 5350 * isIndexed(Set()); // false 5351 * ``` 5352 */ 5353 function isIndexed( 5354 maybeIndexed: unknown 5355 ): maybeIndexed is Collection.Indexed<unknown>; 5356 5357 /** 5358 * True if `maybeAssociative` is either a Keyed or Indexed Collection. 5359 * 5360 * <!-- runkit:activate --> 5361 * ```js 5362 * const { isAssociative, Map, List, Stack, Set } = require('immutable'); 5363 * isAssociative([]); // false 5364 * isAssociative({}); // false 5365 * isAssociative(Map()); // true 5366 * isAssociative(List()); // true 5367 * isAssociative(Stack()); // true 5368 * isAssociative(Set()); // false 5369 * ``` 5370 */ 5371 function isAssociative( 5372 maybeAssociative: unknown 5373 ): maybeAssociative is 5374 | Collection.Keyed<unknown, unknown> 5375 | Collection.Indexed<unknown>; 5376 5377 /** 5378 * True if `maybeOrdered` is a Collection where iteration order is well 5379 * defined. True for Collection.Indexed as well as OrderedMap and OrderedSet. 5380 * 5381 * <!-- runkit:activate --> 5382 * ```js 5383 * const { isOrdered, Map, OrderedMap, List, Set } = require('immutable'); 5384 * isOrdered([]); // false 5385 * isOrdered({}); // false 5386 * isOrdered(Map()); // false 5387 * isOrdered(OrderedMap()); // true 5388 * isOrdered(List()); // true 5389 * isOrdered(Set()); // false 5390 * ``` 5391 */ 5392 function isOrdered(maybeOrdered: unknown): boolean; 5393 5394 /** 5395 * True if `maybeValue` is a JavaScript Object which has *both* `equals()` 5396 * and `hashCode()` methods. 5397 * 5398 * Any two instances of *value objects* can be compared for value equality with 5399 * `Immutable.is()` and can be used as keys in a `Map` or members in a `Set`. 5400 */ 5401 function isValueObject(maybeValue: unknown): maybeValue is ValueObject; 5402 5403 /** 5404 * True if `maybeSeq` is a Seq. 5405 */ 5406 function isSeq( 5407 maybeSeq: unknown 5408 ): maybeSeq is 5409 | Seq.Indexed<unknown> 5410 | Seq.Keyed<unknown, unknown> 5411 | Seq.Set<unknown>; 5412 5413 /** 5414 * True if `maybeList` is a List. 5415 */ 5416 function isList(maybeList: unknown): maybeList is List<unknown>; 5417 5418 /** 5419 * True if `maybeMap` is a Map. 5420 * 5421 * Also true for OrderedMaps. 5422 */ 5423 function isMap(maybeMap: unknown): maybeMap is Map<unknown, unknown>; 5424 5425 /** 5426 * True if `maybeOrderedMap` is an OrderedMap. 5427 */ 5428 function isOrderedMap( 5429 maybeOrderedMap: unknown 5430 ): maybeOrderedMap is OrderedMap<unknown, unknown>; 5431 5432 /** 5433 * True if `maybeStack` is a Stack. 5434 */ 5435 function isStack(maybeStack: unknown): maybeStack is Stack<unknown>; 5436 5437 /** 5438 * True if `maybeSet` is a Set. 5439 * 5440 * Also true for OrderedSets. 5441 */ 5442 function isSet(maybeSet: unknown): maybeSet is Set<unknown>; 5443 5444 /** 5445 * True if `maybeOrderedSet` is an OrderedSet. 5446 */ 5447 function isOrderedSet( 5448 maybeOrderedSet: unknown 5449 ): maybeOrderedSet is OrderedSet<unknown>; 5450 5451 /** 5452 * True if `maybeRecord` is a Record. 5453 */ 5454 function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>; 5455 5456 /** 5457 * Returns the value within the provided collection associated with the 5458 * provided key, or notSetValue if the key is not defined in the collection. 5459 * 5460 * A functional alternative to `collection.get(key)` which will also work on 5461 * plain Objects and Arrays as an alternative for `collection[key]`. 5462 * 5463 * <!-- runkit:activate --> 5464 * ```js 5465 * const { get } = require('immutable') 5466 * get([ 'dog', 'frog', 'cat' ], 2) // 'frog' 5467 * get({ x: 123, y: 456 }, 'x') // 123 5468 * get({ x: 123, y: 456 }, 'z', 'ifNotSet') // 'ifNotSet' 5469 * ``` 5470 */ 5471 function get<K, V>(collection: Collection<K, V>, key: K): V | undefined; 5472 function get<K, V, NSV>( 5473 collection: Collection<K, V>, 5474 key: K, 5475 notSetValue: NSV 5476 ): V | NSV; 5477 function get<TProps extends object, K extends keyof TProps>( 5478 record: Record<TProps>, 5479 key: K, 5480 notSetValue: unknown 5481 ): TProps[K]; 5482 function get<V>(collection: Array<V>, key: number): V | undefined; 5483 function get<V, NSV>( 5484 collection: Array<V>, 5485 key: number, 5486 notSetValue: NSV 5487 ): V | NSV; 5488 function get<C extends object, K extends keyof C>( 5489 object: C, 5490 key: K, 5491 notSetValue: unknown 5492 ): C[K]; 5493 function get<V>(collection: { [key: string]: V }, key: string): V | undefined; 5494 function get<V, NSV>( 5495 collection: { [key: string]: V }, 5496 key: string, 5497 notSetValue: NSV 5498 ): V | NSV; 5499 5500 /** 5501 * Returns true if the key is defined in the provided collection. 5502 * 5503 * A functional alternative to `collection.has(key)` which will also work with 5504 * plain Objects and Arrays as an alternative for 5505 * `collection.hasOwnProperty(key)`. 5506 * 5507 * <!-- runkit:activate --> 5508 * ```js 5509 * const { has } = require('immutable') 5510 * has([ 'dog', 'frog', 'cat' ], 2) // true 5511 * has([ 'dog', 'frog', 'cat' ], 5) // false 5512 * has({ x: 123, y: 456 }, 'x') // true 5513 * has({ x: 123, y: 456 }, 'z') // false 5514 * ``` 5515 */ 5516 function has(collection: object, key: unknown): boolean; 5517 5518 /** 5519 * Returns a copy of the collection with the value at key removed. 5520 * 5521 * A functional alternative to `collection.remove(key)` which will also work 5522 * with plain Objects and Arrays as an alternative for 5523 * `delete collectionCopy[key]`. 5524 * 5525 * <!-- runkit:activate --> 5526 * ```js 5527 * const { remove } = require('immutable') 5528 * const originalArray = [ 'dog', 'frog', 'cat' ] 5529 * remove(originalArray, 1) // [ 'dog', 'cat' ] 5530 * console.log(originalArray) // [ 'dog', 'frog', 'cat' ] 5531 * const originalObject = { x: 123, y: 456 } 5532 * remove(originalObject, 'x') // { y: 456 } 5533 * console.log(originalObject) // { x: 123, y: 456 } 5534 * ``` 5535 */ 5536 function remove<K, C extends Collection<K, unknown>>( 5537 collection: C, 5538 key: K 5539 ): C; 5540 function remove< 5541 TProps extends object, 5542 C extends Record<TProps>, 5543 K extends keyof TProps 5544 >(collection: C, key: K): C; 5545 function remove<C extends Array<unknown>>(collection: C, key: number): C; 5546 function remove<C, K extends keyof C>(collection: C, key: K): C; 5547 function remove<C extends { [key: string]: unknown }, K extends keyof C>( 5548 collection: C, 5549 key: K 5550 ): C; 5551 5552 /** 5553 * Returns a copy of the collection with the value at key set to the provided 5554 * value. 5555 * 5556 * A functional alternative to `collection.set(key, value)` which will also 5557 * work with plain Objects and Arrays as an alternative for 5558 * `collectionCopy[key] = value`. 5559 * 5560 * <!-- runkit:activate --> 5561 * ```js 5562 * const { set } = require('immutable') 5563 * const originalArray = [ 'dog', 'frog', 'cat' ] 5564 * set(originalArray, 1, 'cow') // [ 'dog', 'cow', 'cat' ] 5565 * console.log(originalArray) // [ 'dog', 'frog', 'cat' ] 5566 * const originalObject = { x: 123, y: 456 } 5567 * set(originalObject, 'x', 789) // { x: 789, y: 456 } 5568 * console.log(originalObject) // { x: 123, y: 456 } 5569 * ``` 5570 */ 5571 function set<K, V, C extends Collection<K, V>>( 5572 collection: C, 5573 key: K, 5574 value: V 5575 ): C; 5576 function set< 5577 TProps extends object, 5578 C extends Record<TProps>, 5579 K extends keyof TProps 5580 >(record: C, key: K, value: TProps[K]): C; 5581 function set<V, C extends Array<V>>(collection: C, key: number, value: V): C; 5582 function set<C, K extends keyof C>(object: C, key: K, value: C[K]): C; 5583 function set<V, C extends { [key: string]: V }>( 5584 collection: C, 5585 key: string, 5586 value: V 5587 ): C; 5588 5589 /** 5590 * Returns a copy of the collection with the value at key set to the result of 5591 * providing the existing value to the updating function. 5592 * 5593 * A functional alternative to `collection.update(key, fn)` which will also 5594 * work with plain Objects and Arrays as an alternative for 5595 * `collectionCopy[key] = fn(collection[key])`. 5596 * 5597 * <!-- runkit:activate --> 5598 * ```js 5599 * const { update } = require('immutable') 5600 * const originalArray = [ 'dog', 'frog', 'cat' ] 5601 * update(originalArray, 1, val => val.toUpperCase()) // [ 'dog', 'FROG', 'cat' ] 5602 * console.log(originalArray) // [ 'dog', 'frog', 'cat' ] 5603 * const originalObject = { x: 123, y: 456 } 5604 * update(originalObject, 'x', val => val * 6) // { x: 738, y: 456 } 5605 * console.log(originalObject) // { x: 123, y: 456 } 5606 * ``` 5607 */ 5608 function update<K, V, C extends Collection<K, V>>( 5609 collection: C, 5610 key: K, 5611 updater: (value: V | undefined) => V | undefined 5612 ): C; 5613 function update<K, V, C extends Collection<K, V>, NSV>( 5614 collection: C, 5615 key: K, 5616 notSetValue: NSV, 5617 updater: (value: V | NSV) => V 5618 ): C; 5619 function update< 5620 TProps extends object, 5621 C extends Record<TProps>, 5622 K extends keyof TProps 5623 >(record: C, key: K, updater: (value: TProps[K]) => TProps[K]): C; 5624 function update< 5625 TProps extends object, 5626 C extends Record<TProps>, 5627 K extends keyof TProps, 5628 NSV 5629 >( 5630 record: C, 5631 key: K, 5632 notSetValue: NSV, 5633 updater: (value: TProps[K] | NSV) => TProps[K] 5634 ): C; 5635 function update<V>( 5636 collection: Array<V>, 5637 key: number, 5638 updater: (value: V | undefined) => V | undefined 5639 ): Array<V>; 5640 function update<V, NSV>( 5641 collection: Array<V>, 5642 key: number, 5643 notSetValue: NSV, 5644 updater: (value: V | NSV) => V 5645 ): Array<V>; 5646 function update<C, K extends keyof C>( 5647 object: C, 5648 key: K, 5649 updater: (value: C[K]) => C[K] 5650 ): C; 5651 function update<C, K extends keyof C, NSV>( 5652 object: C, 5653 key: K, 5654 notSetValue: NSV, 5655 updater: (value: C[K] | NSV) => C[K] 5656 ): C; 5657 function update<V, C extends { [key: string]: V }, K extends keyof C>( 5658 collection: C, 5659 key: K, 5660 updater: (value: V) => V 5661 ): { [key: string]: V }; 5662 function update<V, C extends { [key: string]: V }, K extends keyof C, NSV>( 5663 collection: C, 5664 key: K, 5665 notSetValue: NSV, 5666 updater: (value: V | NSV) => V 5667 ): { [key: string]: V }; 5668 5669 /** 5670 * Returns the value at the provided key path starting at the provided 5671 * collection, or notSetValue if the key path is not defined. 5672 * 5673 * A functional alternative to `collection.getIn(keypath)` which will also 5674 * work with plain Objects and Arrays. 5675 * 5676 * <!-- runkit:activate --> 5677 * ```js 5678 * const { getIn } = require('immutable') 5679 * getIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // 123 5680 * getIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p'], 'ifNotSet') // 'ifNotSet' 5681 * ``` 5682 */ 5683 function getIn( 5684 collection: unknown, 5685 keyPath: Iterable<unknown>, 5686 notSetValue?: unknown 5687 ): unknown; 5688 5689 /** 5690 * Returns true if the key path is defined in the provided collection. 5691 * 5692 * A functional alternative to `collection.hasIn(keypath)` which will also 5693 * work with plain Objects and Arrays. 5694 * 5695 * <!-- runkit:activate --> 5696 * ```js 5697 * const { hasIn } = require('immutable') 5698 * hasIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // true 5699 * hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // false 5700 * ``` 5701 */ 5702 function hasIn(collection: unknown, keyPath: Iterable<unknown>): boolean; 5703 5704 /** 5705 * Returns a copy of the collection with the value at the key path removed. 5706 * 5707 * A functional alternative to `collection.removeIn(keypath)` which will also 5708 * work with plain Objects and Arrays. 5709 * 5710 * <!-- runkit:activate --> 5711 * ```js 5712 * const { removeIn } = require('immutable') 5713 * const original = { x: { y: { z: 123 }}} 5714 * removeIn(original, ['x', 'y', 'z']) // { x: { y: {}}} 5715 * console.log(original) // { x: { y: { z: 123 }}} 5716 * ``` 5717 */ 5718 function removeIn<C>(collection: C, keyPath: Iterable<unknown>): C; 5719 5720 /** 5721 * Returns a copy of the collection with the value at the key path set to the 5722 * provided value. 5723 * 5724 * A functional alternative to `collection.setIn(keypath)` which will also 5725 * work with plain Objects and Arrays. 5726 * 5727 * <!-- runkit:activate --> 5728 * ```js 5729 * const { setIn } = require('immutable') 5730 * const original = { x: { y: { z: 123 }}} 5731 * setIn(original, ['x', 'y', 'z'], 456) // { x: { y: { z: 456 }}} 5732 * console.log(original) // { x: { y: { z: 123 }}} 5733 * ``` 5734 */ 5735 function setIn<C>( 5736 collection: C, 5737 keyPath: Iterable<unknown>, 5738 value: unknown 5739 ): C; 5740 5741 /** 5742 * Returns a copy of the collection with the value at key path set to the 5743 * result of providing the existing value to the updating function. 5744 * 5745 * A functional alternative to `collection.updateIn(keypath)` which will also 5746 * work with plain Objects and Arrays. 5747 * 5748 * <!-- runkit:activate --> 5749 * ```js 5750 * const { updateIn } = require('immutable') 5751 * const original = { x: { y: { z: 123 }}} 5752 * updateIn(original, ['x', 'y', 'z'], val => val * 6) // { x: { y: { z: 738 }}} 5753 * console.log(original) // { x: { y: { z: 123 }}} 5754 * ``` 5755 */ 5756 function updateIn<C>( 5757 collection: C, 5758 keyPath: Iterable<unknown>, 5759 updater: (value: unknown) => unknown 5760 ): C; 5761 function updateIn<C>( 5762 collection: C, 5763 keyPath: Iterable<unknown>, 5764 notSetValue: unknown, 5765 updater: (value: unknown) => unknown 5766 ): C; 5767 5768 /** 5769 * Returns a copy of the collection with the remaining collections merged in. 5770 * 5771 * A functional alternative to `collection.merge()` which will also work with 5772 * plain Objects and Arrays. 5773 * 5774 * <!-- runkit:activate --> 5775 * ```js 5776 * const { merge } = require('immutable') 5777 * const original = { x: 123, y: 456 } 5778 * merge(original, { y: 789, z: 'abc' }) // { x: 123, y: 789, z: 'abc' } 5779 * console.log(original) // { x: 123, y: 456 } 5780 * ``` 5781 */ 5782 function merge<C>( 5783 collection: C, 5784 ...collections: Array< 5785 | Iterable<unknown> 5786 | Iterable<[unknown, unknown]> 5787 | { [key: string]: unknown } 5788 > 5789 ): C; 5790 5791 /** 5792 * Returns a copy of the collection with the remaining collections merged in, 5793 * calling the `merger` function whenever an existing value is encountered. 5794 * 5795 * A functional alternative to `collection.mergeWith()` which will also work 5796 * with plain Objects and Arrays. 5797 * 5798 * <!-- runkit:activate --> 5799 * ```js 5800 * const { mergeWith } = require('immutable') 5801 * const original = { x: 123, y: 456 } 5802 * mergeWith( 5803 * (oldVal, newVal) => oldVal + newVal, 5804 * original, 5805 * { y: 789, z: 'abc' } 5806 * ) // { x: 123, y: 1245, z: 'abc' } 5807 * console.log(original) // { x: 123, y: 456 } 5808 * ``` 5809 */ 5810 function mergeWith<C>( 5811 merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown, 5812 collection: C, 5813 ...collections: Array< 5814 | Iterable<unknown> 5815 | Iterable<[unknown, unknown]> 5816 | { [key: string]: unknown } 5817 > 5818 ): C; 5819 5820 /** 5821 * Like `merge()`, but when two compatible collections are encountered with 5822 * the same key, it merges them as well, recursing deeply through the nested 5823 * data. Two collections are considered to be compatible (and thus will be 5824 * merged together) if they both fall into one of three categories: keyed 5825 * (e.g., `Map`s, `Record`s, and objects), indexed (e.g., `List`s and 5826 * arrays), or set-like (e.g., `Set`s). If they fall into separate 5827 * categories, `mergeDeep` will replace the existing collection with the 5828 * collection being merged in. This behavior can be customized by using 5829 * `mergeDeepWith()`. 5830 * 5831 * Note: Indexed and set-like collections are merged using 5832 * `concat()`/`union()` and therefore do not recurse. 5833 * 5834 * A functional alternative to `collection.mergeDeep()` which will also work 5835 * with plain Objects and Arrays. 5836 * 5837 * <!-- runkit:activate --> 5838 * ```js 5839 * const { mergeDeep } = require('immutable') 5840 * const original = { x: { y: 123 }} 5841 * mergeDeep(original, { x: { z: 456 }}) // { x: { y: 123, z: 456 }} 5842 * console.log(original) // { x: { y: 123 }} 5843 * ``` 5844 */ 5845 function mergeDeep<C>( 5846 collection: C, 5847 ...collections: Array< 5848 | Iterable<unknown> 5849 | Iterable<[unknown, unknown]> 5850 | { [key: string]: unknown } 5851 > 5852 ): C; 5853 5854 /** 5855 * Like `mergeDeep()`, but when two non-collections or incompatible 5856 * collections are encountered at the same key, it uses the `merger` function 5857 * to determine the resulting value. Collections are considered incompatible 5858 * if they fall into separate categories between keyed, indexed, and set-like. 5859 * 5860 * A functional alternative to `collection.mergeDeepWith()` which will also 5861 * work with plain Objects and Arrays. 5862 * 5863 * <!-- runkit:activate --> 5864 * ```js 5865 * const { mergeDeepWith } = require('immutable') 5866 * const original = { x: { y: 123 }} 5867 * mergeDeepWith( 5868 * (oldVal, newVal) => oldVal + newVal, 5869 * original, 5870 * { x: { y: 456 }} 5871 * ) // { x: { y: 579 }} 5872 * console.log(original) // { x: { y: 123 }} 5873 * ``` 5874 */ 5875 function mergeDeepWith<C>( 5876 merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown, 5877 collection: C, 5878 ...collections: Array< 5879 | Iterable<unknown> 5880 | Iterable<[unknown, unknown]> 5881 | { [key: string]: unknown } 5882 > 5883 ): C; 5884 } 5885 5886 /** 5887 * Defines the main export of the immutable module to be the Immutable namespace 5888 * This supports many common module import patterns: 5889 * 5890 * const Immutable = require("immutable"); 5891 * const { List } = require("immutable"); 5892 * import Immutable from "immutable"; 5893 * import * as Immutable from "immutable"; 5894 * import { List } from "immutable"; 5895 * 5896 */ 5897 export = Immutable; 5898 5899 /** 5900 * A global "Immutable" namespace used by UMD modules which allows the use of 5901 * the full Immutable API. 5902 * 5903 * If using Immutable as an imported module, prefer using: 5904 * 5905 * import Immutable from 'immutable' 5906 * 5907 */ 5908 export as namespace Immutable;