/** * Selects the save mode for ink signatures. * * @public * @readonly * @memberof PSPDFKit * @property {PSPDFKit.SignatureSaveMode} ALWAYS Always store new ink signatures. * @property {PSPDFKit.SignatureSaveMode} NEVER Never store new ink signatures. * @property {PSPDFKit.SignatureSaveMode} USING_UI Store new ink signatures if the option is selected in the UI. */ declare const SignatureSaveMode: { readonly ALWAYS: "ALWAYS"; readonly NEVER: "NEVER"; readonly USING_UI: "USING_UI"; }; type ISignatureSaveMode = (typeof SignatureSaveMode)[keyof typeof SignatureSaveMode]; /** * Copyright (c) 2014-present, Facebook, Inc. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */ /** * Immutable data encourages pure functions (data-in, data-out) and lends itself * to much simpler application development and enabling techniques from * functional programming such as lazy evaluation. * * While designed to bring these powerful functional concepts to JavaScript, it * presents an Object-Oriented API familiar to Javascript engineers and closely * mirroring that of Array, Map, and Set. It is easy and efficient to convert to * and from plain Javascript types. * * ## How to read these docs * * In order to better explain what kinds of values the Immutable.js API expects * and produces, this documentation is presented in a statically typed dialect of * JavaScript (like [Flow][] or [TypeScript][]). You *don't need* to use these * type checking tools in order to use Immutable.js, however becoming familiar * with their syntax will help you get a deeper understanding of this API. * * **A few examples and how to read them.** * * All methods describe the kinds of data they accept and the kinds of data * they return. For example a function which accepts two numbers and returns * a number would look like this: * * ```js * sum(first: number, second: number): number * ``` * * Sometimes, methods can accept different kinds of data or return different * kinds of data, and this is described with a *type variable*, which is * typically in all-caps. For example, a function which always returns the same * kind of data it was provided would look like this: * * ```js * identity(value: T): T * ``` * * Type variables are defined with classes and referred to in methods. For * example, a class that holds onto a value for you might look like this: * * ```js * class Box { * constructor(value: T) * getValue(): T * } * ``` * * In order to manipulate Immutable data, methods that we're used to affecting * a Collection instead return a new Collection of the same type. The type * `this` refers to the same kind of class. For example, a List which returns * new Lists when you `push` a value onto it might look like: * * ```js * class List { * push(value: T): this * } * ``` * * Many methods in Immutable.js accept values which implement the JavaScript * [Iterable][] protocol, and might appear like `Iterable` for something * which represents sequence of strings. Typically in JavaScript we use plain * Arrays (`[]`) when an Iterable is expected, but also all of the Immutable.js * collections are iterable themselves! * * For example, to get a value deep within a structure of data, we might use * `getIn` which expects an `Iterable` path: * * ``` * getIn(path: Iterable): any * ``` * * To use this method, we could pass an array: `data.getIn([ "key", 2 ])`. * * * Note: All examples are presented in the modern [ES2015][] version of * JavaScript. Use tools like Babel to support older browsers. * * For example: * * ```js * // ES2015 * const mappedFoo = foo.map(x => x * x); * // ES5 * var mappedFoo = foo.map(function (x) { return x * x; }); * ``` * * [ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla * [TypeScript]: http://www.typescriptlang.org/ * [Flow]: https://flowtype.org/ * [Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols */ /** * Lists are ordered indexed dense collections, much like a JavaScript * Array. * * Lists are immutable and fully persistent with O(log32 N) gets and sets, * and O(1) push and pop. * * Lists implement Deque, with efficient addition and removal from both the * end (`push`, `pop`) and beginning (`unshift`, `shift`). * * Unlike a JavaScript Array, there is no distinction between an * "unset" index and an index set to `undefined`. `List#forEach` visits all * indices from 0 to size, regardless of whether they were explicitly defined. */ declare module List { /** * True if the provided value is a List * * * ```js * const { List } = require('immutable'); * List.isList([]); // false * List.isList(List()); // true * ``` */ function isList(maybeList: any): maybeList is List; /** * Creates a new List containing `values`. * * * ```js * const { List } = require('immutable'); * List.of(1, 2, 3, 4) * // List [ 1, 2, 3, 4 ] * ``` * * Note: Values are not altered or converted in any way. * * * ```js * const { List } = require('immutable'); * List.of({x:1}, 2, [3], 4) * // List [ { x: 1 }, 2, [ 3 ], 4 ] * ``` */ function of(...values: Array): List; } /** * Create a new immutable List containing the values of the provided * collection-like. * * Note: `List` is a factory function and not a class, and does not use the * `new` keyword during construction. * * * ```js * const { List, Set } = require('immutable') * * const emptyList = List() * // List [] * * const plainArray = [ 1, 2, 3, 4 ] * const listFromPlainArray = List(plainArray) * // List [ 1, 2, 3, 4 ] * * const plainSet = Set([ 1, 2, 3, 4 ]) * const listFromPlainSet = List(plainSet) * // List [ 1, 2, 3, 4 ] * * const arrayIterator = plainArray[Symbol.iterator]() * const listFromCollectionArray = List(arrayIterator) * // List [ 1, 2, 3, 4 ] * * listFromPlainArray.equals(listFromCollectionArray) // true * listFromPlainSet.equals(listFromCollectionArray) // true * listFromPlainSet.equals(listFromPlainArray) // true * ``` */ declare function List(): List; declare function List(): List; declare function List(collection: Iterable): List; interface List extends Collection.Indexed { /** * The number of items in this List. */ readonly size: number; // Persistent changes /** * Returns a new List which includes `value` at `index`. If `index` already * exists in this List, it will be replaced. * * `index` may be a negative number, which indexes back from the end of the * List. `v.set(-1, "value")` sets the last item in the List. * * If `index` larger than `size`, the returned List's `size` will be large * enough to include the `index`. * * * ```js * const originalList = List([ 0 ]); * // List [ 0 ] * originalList.set(1, 1); * // List [ 0, 1 ] * originalList.set(0, 'overwritten'); * // List [ "overwritten" ] * originalList.set(2, 2); * // List [ 0, undefined, 2 ] * * List().set(50000, 'value').size; * // 50001 * ``` * * Note: `set` can be used in `withMutations`. */ set(index: number, value: T): List; /** * Returns a new List which excludes this `index` and with a size 1 less * than this List. Values at indices above `index` are shifted down by 1 to * fill the position. * * This is synonymous with `list.splice(index, 1)`. * * `index` may be a negative number, which indexes back from the end of the * List. `v.delete(-1)` deletes the last item in the List. * * Note: `delete` cannot be safely used in IE8 * * * ```js * List([ 0, 1, 2, 3, 4 ]).delete(0); * // List [ 1, 2, 3, 4 ] * ``` * * Since `delete()` re-indexes values, it produces a complete copy, which * has `O(N)` complexity. * * Note: `delete` *cannot* be used in `withMutations`. * * @alias remove */ delete(index: number): List; remove(index: number): List; /** * Returns a new List with `value` at `index` with a size 1 more than this * List. Values at indices above `index` are shifted over by 1. * * This is synonymous with `list.splice(index, 0, value)`. * * * ```js * List([ 0, 1, 2, 3, 4 ]).insert(6, 5) * // List [ 0, 1, 2, 3, 4, 5 ] * ``` * * Since `insert()` re-indexes values, it produces a complete copy, which * has `O(N)` complexity. * * Note: `insert` *cannot* be used in `withMutations`. */ insert(index: number, value: T): List; /** * Returns a new List with 0 size and no values in constant time. * * * ```js * List([ 1, 2, 3, 4 ]).clear() * // List [] * ``` * * Note: `clear` can be used in `withMutations`. */ clear(): List; /** * Returns a new List with the provided `values` appended, starting at this * List's `size`. * * * ```js * List([ 1, 2, 3, 4 ]).push(5) * // List [ 1, 2, 3, 4, 5 ] * ``` * * Note: `push` can be used in `withMutations`. */ push(...values: Array): List; /** * Returns a new List with a size ones less than this List, excluding * the last index in this List. * * Note: this differs from `Array#pop` because it returns a new * List rather than the removed value. Use `last()` to get the last value * in this List. * * ```js * List([ 1, 2, 3, 4 ]).pop() * // List[ 1, 2, 3 ] * ``` * * Note: `pop` can be used in `withMutations`. */ pop(): List; /** * Returns a new List with the provided `values` prepended, shifting other * values ahead to higher indices. * * * ```js * List([ 2, 3, 4]).unshift(1); * // List [ 1, 2, 3, 4 ] * ``` * * Note: `unshift` can be used in `withMutations`. */ unshift(...values: Array): List; /** * Returns a new List with a size ones less than this List, excluding * the first index in this List, shifting all other values to a lower index. * * Note: this differs from `Array#shift` because it returns a new * List rather than the removed value. Use `first()` to get the first * value in this List. * * * ```js * List([ 0, 1, 2, 3, 4 ]).shift(); * // List [ 1, 2, 3, 4 ] * ``` * * Note: `shift` can be used in `withMutations`. */ shift(): List; /** * Returns a new List with an updated value at `index` with the return * value of calling `updater` with the existing value, or `notSetValue` if * `index` was not set. If called with a single argument, `updater` is * called with the List itself. * * `index` may be a negative number, which indexes back from the end of the * List. `v.update(-1)` updates the last item in the List. * * * ```js * const list = List([ 'a', 'b', 'c' ]) * const result = list.update(2, val => val.toUpperCase()) * // List [ "a", "b", "C" ] * ``` * * This can be very useful as a way to "chain" a normal function into a * sequence of methods. RxJS calls this "let" and lodash calls it "thru". * * For example, to sum a List after mapping and filtering: * * * ```js * function sum(collection) { * return collection.reduce((sum, x) => sum + x, 0) * } * * List([ 1, 2, 3 ]) * .map(x => x + 1) * .filter(x => x % 2 === 0) * .update(sum) * // 6 * ``` * * Note: `update(index)` can be used in `withMutations`. * * @see `Map#update` */ update(index: number, notSetValue: T, updater: (value: T) => T): this; update(index: number, updater: (value: T) => T): this; update(updater: (value: this) => R): R; /** * Returns a new List with size `size`. If `size` is less than this * List's size, the new List will exclude values at the higher indices. * If `size` is greater than this List's size, the new List will have * undefined values for the newly available indices. * * When building a new List and the final size is known up front, `setSize` * used in conjunction with `withMutations` may result in the more * performant construction. */ setSize(size: number): List; // Deep persistent changes /** * Returns a new List having set `value` at this `keyPath`. If any keys in * `keyPath` do not exist, a new immutable Map will be created at that key. * * Index numbers are used as keys to determine the path to follow in * the List. * * * ```js * const { List } = require('immutable') * const list = List([ 0, 1, 2, List([ 3, 4 ])]) * list.setIn([3, 0], 999); * // List [ 0, 1, 2, List [ 999, 4 ] ] * ``` * * Plain JavaScript Object or Arrays may be nested within an Immutable.js * Collection, and setIn() can update those values as well, treating them * immutably by creating new copies of those values with the changes applied. * * * ```js * const { List } = require('immutable') * const list = List([ 0, 1, 2, { plain: 'object' }]) * list.setIn([3, 'plain'], 'value'); * // List([ 0, 1, 2, { plain: 'value' }]) * ``` * * Note: `setIn` can be used in `withMutations`. */ setIn(keyPath: Iterable, value: any): this; /** * Returns a new List having removed the value at this `keyPath`. If any * keys in `keyPath` do not exist, no change will occur. * * * ```js * const { List } = require('immutable') * const list = List([ 0, 1, 2, List([ 3, 4 ])]) * list.deleteIn([3, 0]); * // List [ 0, 1, 2, List [ 4 ] ] * ``` * * Plain JavaScript Object or Arrays may be nested within an Immutable.js * Collection, and removeIn() can update those values as well, treating them * immutably by creating new copies of those values with the changes applied. * * * ```js * const { List } = require('immutable') * const list = List([ 0, 1, 2, { plain: 'object' }]) * list.removeIn([3, 'plain']); * // List([ 0, 1, 2, {}]) * ``` * * Note: `deleteIn` *cannot* be safely used in `withMutations`. * * @alias removeIn */ deleteIn(keyPath: Iterable): this; removeIn(keyPath: Iterable): this; /** * Note: `updateIn` can be used in `withMutations`. * * @see `Map#updateIn` */ updateIn(keyPath: Iterable, notSetValue: any, updater: (value: any) => any): this; updateIn(keyPath: Iterable, updater: (value: any) => any): this; /** * Note: `mergeIn` can be used in `withMutations`. * * @see `Map#mergeIn` */ mergeIn(keyPath: Iterable, ...collections: Array): this; /** * Note: `mergeDeepIn` can be used in `withMutations`. * * @see `Map#mergeDeepIn` */ mergeDeepIn(keyPath: Iterable, ...collections: Array): this; // Transient changes /** * Note: Not all methods can be safely used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * allows being used in `withMutations`. * * @see `Map#withMutations` */ withMutations(mutator: (mutable: this) => any): this; /** * An alternative API for withMutations() * * Note: Not all methods can be safely used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * allows being used in `withMutations`. * * @see `Map#asMutable` */ asMutable(): this; /** * @see `Map#wasAltered` */ wasAltered(): boolean; /** * @see `Map#asImmutable` */ asImmutable(): this; // Sequence algorithms /** * Returns a new List with other values or collections concatenated to this one. * * Note: `concat` can be used in `withMutations`. * * @alias merge */ concat(...valuesOrCollections: Array | C>): List; merge(...collections: Array>): List; /** * Returns a new List with values passed through a * `mapper` function. * * * ```js * List([ 1, 2 ]).map(x => 10 * x) * // List [ 10, 20 ] * ``` */ map( mapper: (value: T, key: number, iter: this) => M, context?: any ): List; /** * Flat-maps the List, returning a new List. * * Similar to `list.map(...).flatten(true)`. */ flatMap( mapper: (value: T, key: number, iter: this) => Iterable, context?: any ): List; /** * Returns a new List with only the values for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: T, index: number, iter: this) => value is F, context?: any ): List; filter( predicate: (value: T, index: number, iter: this) => any, context?: any ): this; /** * Returns a List "zipped" with the provided collection. * * Like `zipWith`, but using the default `zipper`: creating an `Array`. * * * ```js * const a = List([ 1, 2, 3 ]); * const b = List([ 4, 5, 6 ]); * const c = a.zip(b); // List [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] * ``` */ zip(other: Collection): List<[T,U]>; zip(other: Collection, other2: Collection): List<[T,U,V]>; zip(...collections: Array>): List; /** * Returns a List "zipped" with the provided collections. * * Unlike `zip`, `zipAll` continues zipping until the longest collection is * exhausted. Missing values from shorter collections are filled with `undefined`. * * * ```js * const a = List([ 1, 2 ]); * const b = List([ 3, 4, 5 ]); * const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] * ``` * * Note: Since zipAll will return a collection as large as the largest * input, some results may contain undefined values. TypeScript cannot * account for these without cases (as of v2.5). */ zipAll(other: Collection): List<[T,U]>; zipAll(other: Collection, other2: Collection): List<[T,U,V]>; zipAll(...collections: Array>): List; /** * Returns a List "zipped" with the provided collections by using a * custom `zipper` function. * * * ```js * const a = List([ 1, 2, 3 ]); * const b = List([ 4, 5, 6 ]); * const c = a.zipWith((a, b) => a + b, b); * // List [ 5, 7, 9 ] * ``` */ zipWith( zipper: (value: T, otherValue: U) => Z, otherCollection: Collection ): List; zipWith( zipper: (value: T, otherValue: U, thirdValue: V) => Z, otherCollection: Collection, thirdCollection: Collection ): List; zipWith( zipper: (...any: Array) => Z, ...collections: Array> ): List; } /** * Immutable Map is an unordered Collection.Keyed of (key, value) pairs with * `O(log32 N)` gets and `O(log32 N)` persistent sets. * * Iteration order of a Map is undefined, however is stable. Multiple * iterations of the same Map will iterate in the same order. * * Map's keys can be of any type, and use `Immutable.is` to determine key * equality. This allows the use of any value (including NaN) as a key. * * Because `Immutable.is` returns equality based on value semantics, and * Immutable collections are treated as values, any Immutable collection may * be used as a key. * * * ```js * const { Map, List } = require('immutable'); * Map().set(List([ 1 ]), 'listofone').get(List([ 1 ])); * // 'listofone' * ``` * * Any JavaScript object may be used as a key, however strict identity is used * to evaluate key equality. Two similar looking objects will represent two * different keys. * * Implemented by a hash-array mapped trie. */ declare module Map { /** * True if the provided value is a Map * * * ```js * const { Map } = require('immutable') * Map.isMap({}) // false * Map.isMap(Map()) // true * ``` */ function isMap(maybeMap: any): maybeMap is Map; /** * Creates a new Map from alternating keys and values * * * ```js * const { Map } = require('immutable') * Map.of( * 'key', 'value', * 'numerical value', 3, * 0, 'numerical key' * ) * // Map { 0: "numerical key", "key": "value", "numerical value": 3 } * ``` * * @deprecated Use Map([ [ 'k', 'v' ] ]) or Map({ k: 'v' }) */ function of(...keyValues: Array): Map; } /** * Creates a new Immutable Map. * * Created with the same key value pairs as the provided Collection.Keyed or * JavaScript Object or expects a Collection of [K, V] tuple entries. * * Note: `Map` is a factory function and not a class, and does not use the * `new` keyword during construction. * * * ```js * const { Map } = require('immutable') * Map({ key: "value" }) * Map([ [ "key", "value" ] ]) * ``` * * Keep in mind, when using JS objects to construct Immutable Maps, that * JavaScript Object properties are always strings, even if written in a * quote-less shorthand, while Immutable Maps accept keys of any type. * * * ```js * let obj = { 1: "one" } * Object.keys(obj) // [ "1" ] * assert.equal(obj["1"], obj[1]) // "one" === "one" * * let map = Map(obj) * assert.notEqual(map.get("1"), map.get(1)) // "one" !== undefined * ``` * * Property access for JavaScript Objects first converts the key to a string, * but since Immutable Map keys can be of any type the argument to `get()` is * not altered. */ declare function Map(collection: Iterable<[K, V]>): Map; declare function Map(collection: Iterable>): Map; declare function Map(obj: {[key: string]: V}): Map; declare function Map(): Map; declare function Map(): Map; interface Map extends Collection.Keyed { /** * The number of entries in this Map. */ readonly size: number; // Persistent changes /** * Returns a new Map also containing the new key, value pair. If an equivalent * key already exists in this Map, it will be replaced. * * * ```js * const { Map } = require('immutable') * const originalMap = Map() * const newerMap = originalMap.set('key', 'value') * const newestMap = newerMap.set('key', 'newer value') * * originalMap * // Map {} * newerMap * // Map { "key": "value" } * newestMap * // Map { "key": "newer value" } * ``` * * Note: `set` can be used in `withMutations`. */ set(key: K, value: V): this; /** * Returns a new Map which excludes this `key`. * * Note: `delete` cannot be safely used in IE8, but is provided to mirror * the ES6 collection API. * * * ```js * const { Map } = require('immutable') * const originalMap = Map({ * key: 'value', * otherKey: 'other value' * }) * // Map { "key": "value", "otherKey": "other value" } * originalMap.delete('otherKey') * // Map { "key": "value" } * ``` * * Note: `delete` can be used in `withMutations`. * * @alias remove */ delete(key: K): this; remove(key: K): this; /** * Returns a new Map which excludes the provided `keys`. * * * ```js * const { Map } = require('immutable') * const names = Map({ a: "Aaron", b: "Barry", c: "Connor" }) * names.deleteAll([ 'a', 'c' ]) * // Map { "b": "Barry" } * ``` * * Note: `deleteAll` can be used in `withMutations`. * * @alias removeAll */ deleteAll(keys: Iterable): this; removeAll(keys: Iterable): this; /** * Returns a new Map containing no keys or values. * * * ```js * const { Map } = require('immutable') * Map({ key: 'value' }).clear() * // Map {} * ``` * * Note: `clear` can be used in `withMutations`. */ clear(): this; /** * Returns a new Map having updated the value at this `key` with the return * value of calling `updater` with the existing value. * * Similar to: `map.set(key, updater(map.get(key)))`. * * * ```js * const { Map } = require('immutable') * const aMap = Map({ key: 'value' }) * const newMap = aMap.update('key', value => value + value) * // Map { "key": "valuevalue" } * ``` * * This is most commonly used to call methods on collections within a * structure of data. For example, in order to `.push()` onto a nested `List`, * `update` and `push` can be used together: * * * ```js * const aMap = Map({ nestedList: List([ 1, 2, 3 ]) }) * const newMap = aMap.update('nestedList', list => list.push(4)) * // Map { "nestedList": List [ 1, 2, 3, 4 ] } * ``` * * When a `notSetValue` is provided, it is provided to the `updater` * function when the value at the key does not exist in the Map. * * * ```js * const aMap = Map({ key: 'value' }) * const newMap = aMap.update('noKey', 'no value', value => value + value) * // Map { "key": "value", "noKey": "no valueno value" } * ``` * * However, if the `updater` function returns the same value it was called * with, then no change will occur. This is still true if `notSetValue` * is provided. * * * ```js * const aMap = Map({ apples: 10 }) * const newMap = aMap.update('oranges', 0, val => val) * // Map { "apples": 10 } * assert.strictEqual(newMap, map); * ``` * * For code using ES2015 or later, using `notSetValue` is discourged in * favor of function parameter default values. This helps to avoid any * potential confusion with identify functions as described above. * * The previous example behaves differently when written with default values: * * * ```js * const aMap = Map({ apples: 10 }) * const newMap = aMap.update('oranges', (val = 0) => val) * // Map { "apples": 10, "oranges": 0 } * ``` * * If no key is provided, then the `updater` function return value is * returned as well. * * * ```js * const aMap = Map({ key: 'value' }) * const result = aMap.update(aMap => aMap.get('key')) * // "value" * ``` * * This can be very useful as a way to "chain" a normal function into a * sequence of methods. RxJS calls this "let" and lodash calls it "thru". * * For example, to sum the values in a Map * * * ```js * function sum(collection) { * return collection.reduce((sum, x) => sum + x, 0) * } * * Map({ x: 1, y: 2, z: 3 }) * .map(x => x + 1) * .filter(x => x % 2 === 0) * .update(sum) * // 6 * ``` * * Note: `update(key)` can be used in `withMutations`. */ update(key: K, notSetValue: V, updater: (value: V) => V): this; update(key: K, updater: (value: V) => V): this; update(updater: (value: this) => R): R; /** * Returns a new Map resulting from merging the provided Collections * (or JS objects) into this Map. In other words, this takes each entry of * each collection and sets it on this Map. * * Note: Values provided to `merge` are shallowly converted before being * merged. No nested values are altered. * * * ```js * const { Map } = require('immutable') * const one = Map({ a: 10, b: 20, c: 30 }) * const two = Map({ b: 40, a: 50, d: 60 }) * one.merge(two) // Map { "a": 50, "b": 40, "c": 30, "d": 60 } * two.merge(one) // Map { "b": 20, "a": 10, "d": 60, "c": 30 } * ``` * * Note: `merge` can be used in `withMutations`. * * @alias concat */ merge(...collections: Array>): Map; merge(...collections: Array<{[key: string]: C}>): Map; concat(...collections: Array>): Map; concat(...collections: Array<{[key: string]: C}>): Map; /** * Like `merge()`, `mergeWith()` returns a new Map resulting from merging * the provided Collections (or JS objects) into this Map, but uses the * `merger` function for dealing with conflicts. * * * ```js * const { Map } = require('immutable') * const one = Map({ a: 10, b: 20, c: 30 }) * const two = Map({ b: 40, a: 50, d: 60 }) * one.mergeWith((oldVal, newVal) => oldVal / newVal, two) * // { "a": 0.2, "b": 0.5, "c": 30, "d": 60 } * two.mergeWith((oldVal, newVal) => oldVal / newVal, one) * // { "b": 2, "a": 5, "d": 60, "c": 30 } * ``` * * Note: `mergeWith` can be used in `withMutations`. */ mergeWith( merger: (oldVal: V, newVal: V, key: K) => V, ...collections: Array | {[key: string]: V}> ): this; /** * Like `merge()`, but when two Collections conflict, it merges them as well, * recursing deeply through the nested data. * * Note: Values provided to `merge` are shallowly converted before being * merged. No nested values are altered unless they will also be merged at * a deeper level. * * * ```js * const { Map } = require('immutable') * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) }) * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) }) * one.mergeDeep(two) * // Map { * // "a": Map { "x": 2, "y": 10 }, * // "b": Map { "x": 20, "y": 5 }, * // "c": Map { "z": 3 } * // } * ``` * * Note: `mergeDeep` can be used in `withMutations`. */ mergeDeep(...collections: Array | {[key: string]: V}>): this; /** * Like `mergeDeep()`, but when two non-Collections conflict, it uses the * `merger` function to determine the resulting value. * * * ```js * const { Map } = require('immutable') * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) }) * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) }) * one.mergeDeepWith((oldVal, newVal) => oldVal / newVal, two) * // Map { * // "a": Map { "x": 5, "y": 10 }, * // "b": Map { "x": 20, "y": 10 }, * // "c": Map { "z": 3 } * // } * ``` * Note: `mergeDeepWith` can be used in `withMutations`. */ mergeDeepWith( merger: (oldVal: any, newVal: any, key: any) => any, ...collections: Array | {[key: string]: V}> ): this; // Deep persistent changes /** * Returns a new Map having set `value` at this `keyPath`. If any keys in * `keyPath` do not exist, a new immutable Map will be created at that key. * * * ```js * const { Map } = require('immutable') * const originalMap = Map({ * subObject: Map({ * subKey: 'subvalue', * subSubObject: Map({ * subSubKey: 'subSubValue' * }) * }) * }) * * const newMap = originalMap.setIn(['subObject', 'subKey'], 'ha ha!') * // Map { * // "subObject": Map { * // "subKey": "ha ha!", * // "subSubObject": Map { "subSubKey": "subSubValue" } * // } * // } * * const newerMap = originalMap.setIn( * ['subObject', 'subSubObject', 'subSubKey'], * 'ha ha ha!' * ) * // Map { * // "subObject": Map { * // "subKey": "subvalue", * // "subSubObject": Map { "subSubKey": "ha ha ha!" } * // } * // } * ``` * * Plain JavaScript Object or Arrays may be nested within an Immutable.js * Collection, and setIn() can update those values as well, treating them * immutably by creating new copies of those values with the changes applied. * * * ```js * const { Map } = require('immutable') * const originalMap = Map({ * subObject: { * subKey: 'subvalue', * subSubObject: { * subSubKey: 'subSubValue' * } * } * }) * * originalMap.setIn(['subObject', 'subKey'], 'ha ha!') * // Map { * // "subObject": { * // subKey: "ha ha!", * // subSubObject: { subSubKey: "subSubValue" } * // } * // } * ``` * * If any key in the path exists but cannot be updated (such as a primitive * like number or a custom Object like Date), an error will be thrown. * * Note: `setIn` can be used in `withMutations`. */ setIn(keyPath: Iterable, value: any): this; /** * Returns a new Map having removed the value at this `keyPath`. If any keys * in `keyPath` do not exist, no change will occur. * * Note: `deleteIn` can be used in `withMutations`. * * @alias removeIn */ deleteIn(keyPath: Iterable): this; removeIn(keyPath: Iterable): this; /** * Returns a new Map having applied the `updater` to the entry found at the * keyPath. * * This is most commonly used to call methods on collections nested within a * structure of data. For example, in order to `.push()` onto a nested `List`, * `updateIn` and `push` can be used together: * * * ```js * const { Map, List } = require('immutable') * const map = Map({ inMap: Map({ inList: List([ 1, 2, 3 ]) }) }) * const newMap = map.updateIn(['inMap', 'inList'], list => list.push(4)) * // Map { "inMap": Map { "inList": List [ 1, 2, 3, 4 ] } } * ``` * * If any keys in `keyPath` do not exist, new Immutable `Map`s will * be created at those keys. If the `keyPath` does not already contain a * value, the `updater` function will be called with `notSetValue`, if * provided, otherwise `undefined`. * * * ```js * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) * const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2) * // Map { "a": Map { "b": Map { "c": 20 } } } * ``` * * If the `updater` function returns the same value it was called with, then * no change will occur. This is still true if `notSetValue` is provided. * * * ```js * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) * const newMap = map.updateIn(['a', 'b', 'x'], 100, val => val) * // Map { "a": Map { "b": Map { "c": 10 } } } * assert.strictEqual(newMap, aMap) * ``` * * For code using ES2015 or later, using `notSetValue` is discourged in * favor of function parameter default values. This helps to avoid any * potential confusion with identify functions as described above. * * The previous example behaves differently when written with default values: * * * ```js * const map = Map({ a: Map({ b: Map({ c: 10 }) }) }) * const newMap = map.updateIn(['a', 'b', 'x'], (val = 100) => val) * // Map { "a": Map { "b": Map { "c": 10, "x": 100 } } } * ``` * * Plain JavaScript Object or Arrays may be nested within an Immutable.js * Collection, and updateIn() can update those values as well, treating them * immutably by creating new copies of those values with the changes applied. * * * ```js * const map = Map({ a: { b: { c: 10 } } }) * const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2) * // Map { "a": { b: { c: 20 } } } * ``` * * If any key in the path exists but cannot be updated (such as a primitive * like number or a custom Object like Date), an error will be thrown. * * Note: `updateIn` can be used in `withMutations`. */ updateIn(keyPath: Iterable, notSetValue: any, updater: (value: any) => any): this; updateIn(keyPath: Iterable, updater: (value: any) => any): this; /** * A combination of `updateIn` and `merge`, returning a new Map, but * performing the merge at a point arrived at by following the keyPath. * In other words, these two lines are equivalent: * * ```js * map.updateIn(['a', 'b', 'c'], abc => abc.merge(y)) * map.mergeIn(['a', 'b', 'c'], y) * ``` * * Note: `mergeIn` can be used in `withMutations`. */ mergeIn(keyPath: Iterable, ...collections: Array): this; /** * A combination of `updateIn` and `mergeDeep`, returning a new Map, but * performing the deep merge at a point arrived at by following the keyPath. * In other words, these two lines are equivalent: * * ```js * map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y)) * map.mergeDeepIn(['a', 'b', 'c'], y) * ``` * * Note: `mergeDeepIn` can be used in `withMutations`. */ mergeDeepIn(keyPath: Iterable, ...collections: Array): this; // Transient changes /** * Every time you call one of the above functions, a new immutable Map is * created. If a pure function calls a number of these to produce a final * return value, then a penalty on performance and memory has been paid by * creating all of the intermediate immutable Maps. * * If you need to apply a series of mutations to produce a new immutable * Map, `withMutations()` creates a temporary mutable copy of the Map which * can apply mutations in a highly performant manner. In fact, this is * exactly how complex mutations like `merge` are done. * * As an example, this results in the creation of 2, not 4, new Maps: * * * ```js * const { Map } = require('immutable') * const map1 = Map() * const map2 = map1.withMutations(map => { * map.set('a', 1).set('b', 2).set('c', 3) * }) * assert.equal(map1.size, 0) * assert.equal(map2.size, 3) * ``` * * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Read the documentation for each method to see if it * is safe to use in `withMutations`. */ withMutations(mutator: (mutable: this) => any): this; /** * Another way to avoid creation of intermediate Immutable maps is to create * a mutable copy of this collection. Mutable copies *always* return `this`, * and thus shouldn't be used for equality. Your function should never return * a mutable copy of a collection, only use it internally to create a new * collection. * * If possible, use `withMutations` to work with temporary mutable copies as * it provides an easier to use API and considers many common optimizations. * * Note: if the collection is already mutable, `asMutable` returns itself. * * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Read the documentation for each method to see if it * is safe to use in `withMutations`. * * @see `Map#asImmutable` */ asMutable(): this; /** * Returns true if this is a mutable copy (see `asMutable()`) and mutative * alterations have been applied. * * @see `Map#asMutable` */ wasAltered(): boolean; /** * The yin to `asMutable`'s yang. Because it applies to mutable collections, * this operation is *mutable* and may return itself (though may not * return itself, i.e. if the result is an empty collection). Once * performed, the original mutable copy must no longer be mutated since it * may be the immutable result. * * If possible, use `withMutations` to work with temporary mutable copies as * it provides an easier to use API and considers many common optimizations. * * @see `Map#asMutable` */ asImmutable(): this; // Sequence algorithms /** * Returns a new Map with values passed through a * `mapper` function. * * Map({ a: 1, b: 2 }).map(x => 10 * x) * // Map { a: 10, b: 20 } */ map( mapper: (value: V, key: K, iter: this) => M, context?: any ): Map; /** * @see Collection.Keyed.mapKeys */ mapKeys( mapper: (key: K, value: V, iter: this) => M, context?: any ): Map; /** * @see Collection.Keyed.mapEntries */ mapEntries( mapper: (entry: [K, V], index: number, iter: this) => [KM, VM], context?: any ): Map; /** * Flat-maps the Map, returning a new Map. * * Similar to `data.map(...).flatten(true)`. */ flatMap( mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, context?: any ): Map; /** * Returns a new Map with only the entries for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: V, key: K, iter: this) => value is F, context?: any ): Map; filter( predicate: (value: V, key: K, iter: this) => any, context?: any ): this; /** * @see Collection.Keyed.flip */ flip(): Map; } /** * A type of Map that has the additional guarantee that the iteration order of * entries will be the order in which they were set(). * * The iteration behavior of OrderedMap is the same as native ES6 Map and * JavaScript Object. * * Note that `OrderedMap` are more expensive than non-ordered `Map` and may * consume more memory. `OrderedMap#set` is amortized O(log32 N), but not * stable. */ declare module OrderedMap { /** * True if the provided value is an OrderedMap. */ function isOrderedMap(maybeOrderedMap: any): maybeOrderedMap is OrderedMap; } /** * Creates a new Immutable OrderedMap. * * Created with the same key value pairs as the provided Collection.Keyed or * JavaScript Object or expects a Collection of [K, V] tuple entries. * * The iteration order of key-value pairs provided to this constructor will * be preserved in the OrderedMap. * * let newOrderedMap = OrderedMap({key: "value"}) * let newOrderedMap = OrderedMap([["key", "value"]]) * * Note: `OrderedMap` is a factory function and not a class, and does not use * the `new` keyword during construction. */ declare function OrderedMap(collection: Iterable<[K, V]>): OrderedMap; declare function OrderedMap(collection: Iterable>): OrderedMap; declare function OrderedMap(obj: {[key: string]: V}): OrderedMap; declare function OrderedMap(): OrderedMap; declare function OrderedMap(): OrderedMap; interface OrderedMap extends Map { /** * The number of entries in this OrderedMap. */ readonly size: number; /** * Returns a new OrderedMap also containing the new key, value pair. If an * equivalent key already exists in this OrderedMap, it will be replaced * while maintaining the existing order. * * * ```js * const { OrderedMap } = require('immutable') * const originalMap = OrderedMap({a:1, b:1, c:1}) * const updatedMap = originalMap.set('b', 2) * * originalMap * // OrderedMap {a: 1, b: 1, c: 1} * updatedMap * // OrderedMap {a: 1, b: 2, c: 1} * ``` * * Note: `set` can be used in `withMutations`. */ set(key: K, value: V): this; /** * Returns a new OrderedMap resulting from merging the provided Collections * (or JS objects) into this OrderedMap. In other words, this takes each * entry of each collection and sets it on this OrderedMap. * * Note: Values provided to `merge` are shallowly converted before being * merged. No nested values are altered. * * * ```js * const { OrderedMap } = require('immutable') * const one = OrderedMap({ a: 10, b: 20, c: 30 }) * const two = OrderedMap({ b: 40, a: 50, d: 60 }) * one.merge(two) // OrderedMap { "a": 50, "b": 40, "c": 30, "d": 60 } * two.merge(one) // OrderedMap { "b": 20, "a": 10, "d": 60, "c": 30 } * ``` * * Note: `merge` can be used in `withMutations`. * * @alias concat */ merge(...collections: Array>): OrderedMap; merge(...collections: Array<{[key: string]: C}>): OrderedMap; concat(...collections: Array>): OrderedMap; concat(...collections: Array<{[key: string]: C}>): OrderedMap; // Sequence algorithms /** * Returns a new OrderedMap with values passed through a * `mapper` function. * * OrderedMap({ a: 1, b: 2 }).map(x => 10 * x) * // OrderedMap { "a": 10, "b": 20 } * * Note: `map()` always returns a new instance, even if it produced the same * value at every step. */ map( mapper: (value: V, key: K, iter: this) => M, context?: any ): OrderedMap; /** * @see Collection.Keyed.mapKeys */ mapKeys( mapper: (key: K, value: V, iter: this) => M, context?: any ): OrderedMap; /** * @see Collection.Keyed.mapEntries */ mapEntries( mapper: (entry: [K, V], index: number, iter: this) => [KM, VM], context?: any ): OrderedMap; /** * Flat-maps the OrderedMap, returning a new OrderedMap. * * Similar to `data.map(...).flatten(true)`. */ flatMap( mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, context?: any ): OrderedMap; /** * Returns a new OrderedMap with only the entries for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: V, key: K, iter: this) => value is F, context?: any ): OrderedMap; filter( predicate: (value: V, key: K, iter: this) => any, context?: any ): this; /** * @see Collection.Keyed.flip */ flip(): OrderedMap; } /** * A Collection of unique values with `O(log32 N)` adds and has. * * When iterating a Set, the entries will be (value, value) pairs. Iteration * order of a Set is undefined, however is stable. Multiple iterations of the * same Set will iterate in the same order. * * Set values, like Map keys, may be of any type. Equality is determined using * `Immutable.is`, enabling Sets to uniquely include other Immutable * collections, custom value types, and NaN. */ declare module Set { /** * True if the provided value is a Set */ function isSet(maybeSet: any): maybeSet is Set; /** * Creates a new Set containing `values`. */ function of(...values: Array): Set; /** * `Set.fromKeys()` creates a new immutable Set containing the keys from * this Collection or JavaScript Object. */ function fromKeys(iter: Collection): Set; function fromKeys(obj: {[key: string]: any}): Set; /** * `Set.intersect()` creates a new immutable Set that is the intersection of * a collection of other sets. * * ```js * const { Set } = require('immutable') * const intersected = Set.intersect([ * Set([ 'a', 'b', 'c' ]) * Set([ 'c', 'a', 't' ]) * ]) * // Set [ "a", "c"" ] * ``` */ function intersect(sets: Iterable>): Set; /** * `Set.union()` creates a new immutable Set that is the union of a * collection of other sets. * * ```js * const { Set } = require('immutable') * const unioned = Set.union([ * Set([ 'a', 'b', 'c' ]) * Set([ 'c', 'a', 't' ]) * ]) * // Set [ "a", "b", "c", "t"" ] * ``` */ function union(sets: Iterable>): Set; } /** * Create a new immutable Set containing the values of the provided * collection-like. * * Note: `Set` is a factory function and not a class, and does not use the * `new` keyword during construction. */ declare function Set(): Set; declare function Set(): Set; declare function Set(collection: Iterable): Set; interface Set extends Collection.Set { /** * The number of items in this Set. */ readonly size: number; // Persistent changes /** * Returns a new Set which also includes this value. * * Note: `add` can be used in `withMutations`. */ add(value: T): this; /** * Returns a new Set which excludes this value. * * Note: `delete` can be used in `withMutations`. * * Note: `delete` **cannot** be safely used in IE8, use `remove` if * supporting old browsers. * * @alias remove */ delete(value: T): this; remove(value: T): this; /** * Returns a new Set containing no values. * * Note: `clear` can be used in `withMutations`. */ clear(): this; /** * Returns a Set including any value from `collections` that does not already * exist in this Set. * * Note: `union` can be used in `withMutations`. * @alias merge * @alias concat */ union(...collections: Array>): Set; merge(...collections: Array>): Set; concat(...collections: Array>): Set; /** * Returns a Set which has removed any values not also contained * within `collections`. * * Note: `intersect` can be used in `withMutations`. */ intersect(...collections: Array>): this; /** * Returns a Set excluding any values contained within `collections`. * * * ```js * const { OrderedSet } = require('immutable') * OrderedSet([ 1, 2, 3 ]).subtract([1, 3]) * // OrderedSet [2] * ``` * * Note: `subtract` can be used in `withMutations`. */ subtract(...collections: Array>): this; // Transient changes /** * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * mentions being safe to use in `withMutations`. * * @see `Map#withMutations` */ withMutations(mutator: (mutable: this) => any): this; /** * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * mentions being safe to use in `withMutations`. * * @see `Map#asMutable` */ asMutable(): this; /** * @see `Map#wasAltered` */ wasAltered(): boolean; /** * @see `Map#asImmutable` */ asImmutable(): this; // Sequence algorithms /** * Returns a new Set with values passed through a * `mapper` function. * * Set([1,2]).map(x => 10 * x) * // Set [10,20] */ map( mapper: (value: T, key: T, iter: this) => M, context?: any ): Set; /** * Flat-maps the Set, returning a new Set. * * Similar to `set.map(...).flatten(true)`. */ flatMap( mapper: (value: T, key: T, iter: this) => Iterable, context?: any ): Set; /** * Returns a new Set with only the values for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: T, key: T, iter: this) => value is F, context?: any ): Set; filter( predicate: (value: T, key: T, iter: this) => any, context?: any ): this; } /** * A type of Set that has the additional guarantee that the iteration order of * values will be the order in which they were `add`ed. * * The iteration behavior of OrderedSet is the same as native ES6 Set. * * Note that `OrderedSet` are more expensive than non-ordered `Set` and may * consume more memory. `OrderedSet#add` is amortized O(log32 N), but not * stable. */ declare module OrderedSet { /** * True if the provided value is an OrderedSet. */ function isOrderedSet(maybeOrderedSet: any): boolean; /** * Creates a new OrderedSet containing `values`. */ function of(...values: Array): OrderedSet; /** * `OrderedSet.fromKeys()` creates a new immutable OrderedSet containing * the keys from this Collection or JavaScript Object. */ function fromKeys(iter: Collection): OrderedSet; function fromKeys(obj: {[key: string]: any}): OrderedSet; } /** * Create a new immutable OrderedSet containing the values of the provided * collection-like. * * Note: `OrderedSet` is a factory function and not a class, and does not use * the `new` keyword during construction. */ declare function OrderedSet(): OrderedSet; declare function OrderedSet(): OrderedSet; declare function OrderedSet(collection: Iterable): OrderedSet; interface OrderedSet extends Set { /** * The number of items in this OrderedSet. */ readonly size: number; /** * Returns an OrderedSet including any value from `collections` that does * not already exist in this OrderedSet. * * Note: `union` can be used in `withMutations`. * @alias merge * @alias concat */ union(...collections: Array>): OrderedSet; merge(...collections: Array>): OrderedSet; concat(...collections: Array>): OrderedSet; // Sequence algorithms /** * Returns a new Set with values passed through a * `mapper` function. * * OrderedSet([ 1, 2 ]).map(x => 10 * x) * // OrderedSet [10, 20] */ map( mapper: (value: T, key: T, iter: this) => M, context?: any ): OrderedSet; /** * Flat-maps the OrderedSet, returning a new OrderedSet. * * Similar to `set.map(...).flatten(true)`. */ flatMap( mapper: (value: T, key: T, iter: this) => Iterable, context?: any ): OrderedSet; /** * Returns a new OrderedSet with only the values for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: T, key: T, iter: this) => value is F, context?: any ): OrderedSet; filter( predicate: (value: T, key: T, iter: this) => any, context?: any ): this; /** * Returns an OrderedSet of the same type "zipped" with the provided * collections. * * Like `zipWith`, but using the default `zipper`: creating an `Array`. * * ```js * const a = OrderedSet([ 1, 2, 3 ]) * const b = OrderedSet([ 4, 5, 6 ]) * const c = a.zip(b) * // OrderedSet [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] * ``` */ zip(other: Collection): OrderedSet<[T,U]>; zip(other1: Collection, other2: Collection): OrderedSet<[T,U,V]>; zip(...collections: Array>): OrderedSet; /** * Returns a OrderedSet of the same type "zipped" with the provided * collections. * * Unlike `zip`, `zipAll` continues zipping until the longest collection is * exhausted. Missing values from shorter collections are filled with `undefined`. * * ```js * const a = OrderedSet([ 1, 2 ]); * const b = OrderedSet([ 3, 4, 5 ]); * const c = a.zipAll(b); // OrderedSet [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] * ``` * * Note: Since zipAll will return a collection as large as the largest * input, some results may contain undefined values. TypeScript cannot * account for these without cases (as of v2.5). */ zipAll(other: Collection): OrderedSet<[T,U]>; zipAll(other1: Collection, other2: Collection): OrderedSet<[T,U,V]>; zipAll(...collections: Array>): OrderedSet; /** * Returns an OrderedSet of the same type "zipped" with the provided * collections by using a custom `zipper` function. * * @see Seq.Indexed.zipWith */ zipWith( zipper: (value: T, otherValue: U) => Z, otherCollection: Collection ): OrderedSet; zipWith( zipper: (value: T, otherValue: U, thirdValue: V) => Z, otherCollection: Collection, thirdCollection: Collection ): OrderedSet; zipWith( zipper: (...any: Array) => Z, ...collections: Array> ): OrderedSet; } /** * Stacks are indexed collections which support very efficient O(1) addition * and removal from the front using `unshift(v)` and `shift()`. * * For familiarity, Stack also provides `push(v)`, `pop()`, and `peek()`, but * be aware that they also operate on the front of the list, unlike List or * a JavaScript Array. * * Note: `reverse()` or any inherent reverse traversal (`reduceRight`, * `lastIndexOf`, etc.) is not efficient with a Stack. * * Stack is implemented with a Single-Linked List. */ declare module Stack { /** * True if the provided value is a Stack */ function isStack(maybeStack: any): maybeStack is Stack; /** * Creates a new Stack containing `values`. */ function of(...values: Array): Stack; } /** * Create a new immutable Stack containing the values of the provided * collection-like. * * The iteration order of the provided collection is preserved in the * resulting `Stack`. * * Note: `Stack` is a factory function and not a class, and does not use the * `new` keyword during construction. */ declare function Stack(): Stack; declare function Stack(): Stack; declare function Stack(collection: Iterable): Stack; interface Stack extends Collection.Indexed { /** * The number of items in this Stack. */ readonly size: number; // Reading values /** * Alias for `Stack.first()`. */ peek(): T | undefined; // Persistent changes /** * Returns a new Stack with 0 size and no values. * * Note: `clear` can be used in `withMutations`. */ clear(): Stack; /** * Returns a new Stack with the provided `values` prepended, shifting other * values ahead to higher indices. * * This is very efficient for Stack. * * Note: `unshift` can be used in `withMutations`. */ unshift(...values: Array): Stack; /** * Like `Stack#unshift`, but accepts a collection rather than varargs. * * Note: `unshiftAll` can be used in `withMutations`. */ unshiftAll(iter: Iterable): Stack; /** * Returns a new Stack with a size ones less than this Stack, excluding * the first item in this Stack, shifting all other values to a lower index. * * Note: this differs from `Array#shift` because it returns a new * Stack rather than the removed value. Use `first()` or `peek()` to get the * first value in this Stack. * * Note: `shift` can be used in `withMutations`. */ shift(): Stack; /** * Alias for `Stack#unshift` and is not equivalent to `List#push`. */ push(...values: Array): Stack; /** * Alias for `Stack#unshiftAll`. */ pushAll(iter: Iterable): Stack; /** * Alias for `Stack#shift` and is not equivalent to `List#pop`. */ pop(): Stack; // Transient changes /** * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * mentions being safe to use in `withMutations`. * * @see `Map#withMutations` */ withMutations(mutator: (mutable: this) => any): this; /** * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Check the documentation for each method to see if it * mentions being safe to use in `withMutations`. * * @see `Map#asMutable` */ asMutable(): this; /** * @see `Map#wasAltered` */ wasAltered(): boolean; /** * @see `Map#asImmutable` */ asImmutable(): this; // Sequence algorithms /** * Returns a new Stack with other collections concatenated to this one. */ concat(...valuesOrCollections: Array | C>): Stack; /** * Returns a new Stack with values passed through a * `mapper` function. * * Stack([ 1, 2 ]).map(x => 10 * x) * // Stack [ 10, 20 ] * * Note: `map()` always returns a new instance, even if it produced the same * value at every step. */ map( mapper: (value: T, key: number, iter: this) => M, context?: any ): Stack; /** * Flat-maps the Stack, returning a new Stack. * * Similar to `stack.map(...).flatten(true)`. */ flatMap( mapper: (value: T, key: number, iter: this) => Iterable, context?: any ): Stack; /** * Returns a new Set with only the values for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: T, index: number, iter: this) => value is F, context?: any ): Set; filter( predicate: (value: T, index: number, iter: this) => any, context?: any ): this; /** * Returns a Stack "zipped" with the provided collections. * * Like `zipWith`, but using the default `zipper`: creating an `Array`. * * ```js * const a = Stack([ 1, 2, 3 ]); * const b = Stack([ 4, 5, 6 ]); * const c = a.zip(b); // Stack [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ] * ``` */ zip(other: Collection): Stack<[T,U]>; zip(other: Collection, other2: Collection): Stack<[T,U,V]>; zip(...collections: Array>): Stack; /** * Returns a Stack "zipped" with the provided collections. * * Unlike `zip`, `zipAll` continues zipping until the longest collection is * exhausted. Missing values from shorter collections are filled with `undefined`. * * ```js * const a = Stack([ 1, 2 ]); * const b = Stack([ 3, 4, 5 ]); * const c = a.zipAll(b); // Stack [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ] * ``` * * Note: Since zipAll will return a collection as large as the largest * input, some results may contain undefined values. TypeScript cannot * account for these without cases (as of v2.5). */ zipAll(other: Collection): Stack<[T,U]>; zipAll(other: Collection, other2: Collection): Stack<[T,U,V]>; zipAll(...collections: Array>): Stack; /** * Returns a Stack "zipped" with the provided collections by using a * custom `zipper` function. * * ```js * const a = Stack([ 1, 2, 3 ]); * const b = Stack([ 4, 5, 6 ]); * const c = a.zipWith((a, b) => a + b, b); * // Stack [ 5, 7, 9 ] * ``` */ zipWith( zipper: (value: T, otherValue: U) => Z, otherCollection: Collection ): Stack; zipWith( zipper: (value: T, otherValue: U, thirdValue: V) => Z, otherCollection: Collection, thirdCollection: Collection ): Stack; zipWith( zipper: (...any: Array) => Z, ...collections: Array> ): Stack; } /** * A record is similar to a JS object, but enforces a specific set of allowed * string keys, and has default values. * * The `Record()` function produces new Record Factories, which when called * create Record instances. * * ```js * const { Record } = require('immutable') * const ABRecord = Record({ a: 1, b: 2 }) * const myRecord = ABRecord({ b: 3 }) * ``` * * Records always have a value for the keys they define. `remove`ing a key * from a record simply resets it to the default value for that key. * * ```js * myRecord.size // 2 * myRecord.get('a') // 1 * myRecord.get('b') // 3 * const myRecordWithoutB = myRecord.remove('b') * myRecordWithoutB.get('b') // 2 * myRecordWithoutB.size // 2 * ``` * * Values provided to the constructor not found in the Record type will * be ignored. For example, in this case, ABRecord is provided a key "x" even * though only "a" and "b" have been defined. The value for "x" will be * ignored for this record. * * ```js * const myRecord = ABRecord({ b: 3, x: 10 }) * myRecord.get('x') // undefined * ``` * * Because Records have a known set of string keys, property get access works * as expected, however property sets will throw an Error. * * Note: IE8 does not support property access. Only use `get()` when * supporting IE8. * * ```js * myRecord.b // 3 * myRecord.b = 5 // throws Error * ``` * * Record Types can be extended as well, allowing for custom methods on your * Record. This is not a common pattern in functional environments, but is in * many JS programs. * * However Record Types are more restricted than typical JavaScript classes. * They do not use a class constructor, which also means they cannot use * class properties (since those are technically part of a constructor). * * While Record Types can be syntactically created with the JavaScript `class` * form, the resulting Record function is actually a factory function, not a * class constructor. Even though Record Types are not classes, JavaScript * currently requires the use of `new` when creating new Record instances if * they are defined as a `class`. * * ``` * class ABRecord extends Record({ a: 1, b: 2 }) { * getAB() { * return this.a + this.b; * } * } * * var myRecord = new ABRecord({b: 3}) * myRecord.getAB() // 4 * ``` * * * **Flow Typing Records:** * * Immutable.js exports two Flow types designed to make it easier to use * Records with flow typed code, `RecordOf` and `RecordFactory`. * * When defining a new kind of Record factory function, use a flow type that * describes the values the record contains along with `RecordFactory`. * To type instances of the Record (which the factory function returns), * use `RecordOf`. * * Typically, new Record definitions will export both the Record factory * function as well as the Record instance type for use in other code. * * ```js * import type { RecordFactory, RecordOf } from 'immutable'; * * // Use RecordFactory for defining new Record factory functions. * type Point3DProps = { x: number, y: number, z: number }; * const defaultValues: Point3DProps = { x: 0, y: 0, z: 0 }; * const makePoint3D: RecordFactory = Record(defaultValues); * export makePoint3D; * * // Use RecordOf for defining new instances of that Record. * export type Point3D = RecordOf; * const some3DPoint: Point3D = makePoint3D({ x: 10, y: 20, z: 30 }); * ``` * * **Flow Typing Record Subclasses:** * * Records can be subclassed as a means to add additional methods to Record * instances. This is generally discouraged in favor of a more functional API, * since Subclasses have some minor overhead. However the ability to create * a rich API on Record types can be quite valuable. * * When using Flow to type Subclasses, do not use `RecordFactory`, * instead apply the props type when subclassing: * * ```js * type PersonProps = {name: string, age: number}; * const defaultValues: PersonProps = {name: 'Aristotle', age: 2400}; * const PersonRecord = Record(defaultValues); * class Person extends PersonRecord { * getName(): string { * return this.get('name') * } * * setName(name: string): this { * return this.set('name', name); * } * } * ``` * * **Choosing Records vs plain JavaScript objects** * * Records offer a persistently immutable alternative to plain JavaScript * objects, however they're not required to be used within Immutable.js * collections. In fact, the deep-access and deep-updating functions * like `getIn()` and `setIn()` work with plain JavaScript Objects as well. * * Deciding to use Records or Objects in your application should be informed * by the tradeoffs and relative benefits of each: * * - *Runtime immutability*: plain JS objects may be carefully treated as * immutable, however Record instances will *throw* if attempted to be * mutated directly. Records provide this additional guarantee, however at * some marginal runtime cost. While JS objects are mutable by nature, the * use of type-checking tools like [Flow](https://medium.com/@gcanti/immutability-with-flow-faa050a1aef4) * can help gain confidence in code written to favor immutability. * * - *Value equality*: Records use value equality when compared with `is()` * or `record.equals()`. That is, two Records with the same keys and values * are equal. Plain objects use *reference equality*. Two objects with the * same keys and values are not equal since they are different objects. * This is important to consider when using objects as keys in a `Map` or * values in a `Set`, which use equality when retrieving values. * * - *API methods*: Records have a full featured API, with methods like * `.getIn()`, and `.equals()`. These can make working with these values * easier, but comes at the cost of not allowing keys with those names. * * - *Default values*: Records provide default values for every key, which * can be useful when constructing Records with often unchanging values. * However default values can make using Flow and TypeScript more laborious. * * - *Serialization*: Records use a custom internal representation to * efficiently store and update their values. Converting to and from this * form isn't free. If converting Records to plain objects is common, * consider sticking with plain objects to begin with. */ declare module Record$1 { /** * True if `maybeRecord` is an instance of a Record. */ export function isRecord(maybeRecord: any): maybeRecord is Record$1; /** * Records allow passing a second parameter to supply a descriptive name * that appears when converting a Record to a string or in any error * messages. A descriptive name for any record can be accessed by using this * method. If one was not provided, the string "Record" is returned. * * ```js * const { Record } = require('immutable') * const Person = Record({ * name: null * }, 'Person') * * var me = Person({ name: 'My Name' }) * me.toString() // "Person { "name": "My Name" }" * Record.getDescriptiveName(me) // "Person" * ``` */ export function getDescriptiveName(record: Record$1): string; /** * A Record.Factory is created by the `Record()` function. Record instances * are created by passing it some of the accepted values for that Record * type: * * * ```js * // makePerson is a Record Factory function * const makePerson = Record({ name: null, favoriteColor: 'unknown' }); * * // alan is a Record instance * const alan = makePerson({ name: 'Alan' }); * ``` * * Note that Record Factories return `Record & Readonly`, * this allows use of both the Record instance API, and direct property * access on the resulting instances: * * * ```js * // Use the Record API * console.log('Record API: ' + alan.get('name')) * * // Or direct property access (Readonly) * console.log('property access: ' + alan.name) * ``` * * **Flow Typing Records:** * * Use the `RecordFactory` Flow type to get high quality type checking of * Records: * * ```js * import type { RecordFactory, RecordOf } from 'immutable'; * * // Use RecordFactory for defining new Record factory functions. * type PersonProps = { name: ?string, favoriteColor: string }; * const makePerson: RecordFactory = Record({ name: null, favoriteColor: 'unknown' }); * * // Use RecordOf for defining new instances of that Record. * type Person = RecordOf; * const alan: Person = makePerson({ name: 'Alan' }); * ``` */ export module Factory {} export interface Factory { (values?: Partial | Iterable<[string, any]>): Record$1 & Readonly; new (values?: Partial | Iterable<[string, any]>): Record$1 & Readonly; } export function Factory(values?: Partial | Iterable<[string, any]>): Record$1 & Readonly; } /** * Unlike other types in Immutable.js, the `Record()` function creates a new * Record Factory, which is a function that creates Record instances. * * See above for examples of using `Record()`. * * Note: `Record` is a factory function and not a class, and does not use the * `new` keyword during construction. */ declare function Record$1(defaultValues: TProps, name?: string): Record$1.Factory; interface Record$1 { // Reading values has(key: string): key is keyof TProps & string; /** * Returns the value associated with the provided key, which may be the * default value defined when creating the Record factory function. * * If the requested key is not defined by this Record type, then * notSetValue will be returned if provided. Note that this scenario would * produce an error when using Flow or TypeScript. */ get(key: K, notSetValue?: any): TProps[K]; get(key: string, notSetValue: T): T; // Reading deep values hasIn(keyPath: Iterable): boolean; getIn(keyPath: Iterable): any; // Value equality equals(other: any): boolean; hashCode(): number; // Persistent changes set(key: K, value: TProps[K]): this; update(key: K, updater: (value: TProps[K]) => TProps[K]): this; merge(...collections: Array | Iterable<[string, any]>>): this; mergeDeep(...collections: Array | Iterable<[string, any]>>): this; mergeWith( merger: (oldVal: any, newVal: any, key: keyof TProps) => any, ...collections: Array | Iterable<[string, any]>> ): this; mergeDeepWith( merger: (oldVal: any, newVal: any, key: any) => any, ...collections: Array | Iterable<[string, any]>> ): this; /** * Returns a new instance of this Record type with the value for the * specific key set to its default value. * * @alias remove */ delete(key: K): this; remove(key: K): this; /** * Returns a new instance of this Record type with all values set * to their default values. */ clear(): this; // Deep persistent changes setIn(keyPath: Iterable, value: any): this; updateIn(keyPath: Iterable, updater: (value: any) => any): this; mergeIn(keyPath: Iterable, ...collections: Array): this; mergeDeepIn(keyPath: Iterable, ...collections: Array): this; /** * @alias removeIn */ deleteIn(keyPath: Iterable): this; removeIn(keyPath: Iterable): this; // Conversion to JavaScript types /** * Deeply converts this Record to equivalent native JavaScript Object. * * Note: This method may not be overridden. Objects with custom * serialization to plain JS may override toJSON() instead. */ toJS(): { [K in keyof TProps]: any }; /** * Shallowly converts this Record to equivalent native JavaScript Object. */ toJSON(): TProps; /** * Shallowly converts this Record to equivalent JavaScript Object. */ toObject(): TProps; // Transient changes /** * Note: Not all methods can be used on a mutable collection or within * `withMutations`! Only `set` may be used mutatively. * * @see `Map#withMutations` */ withMutations(mutator: (mutable: this) => any): this; /** * @see `Map#asMutable` */ asMutable(): this; /** * @see `Map#wasAltered` */ wasAltered(): boolean; /** * @see `Map#asImmutable` */ asImmutable(): this; // Sequence algorithms toSeq(): Seq.Keyed; [Symbol.iterator](): IterableIterator<[keyof TProps, TProps[keyof TProps]]>; } /** * `Seq` describes a lazy operation, allowing them to efficiently chain * use of all the higher-order collection methods (such as `map` and `filter`) * by not creating intermediate collections. * * **Seq is immutable** — Once a Seq is created, it cannot be * changed, appended to, rearranged or otherwise modified. Instead, any * mutative method called on a `Seq` will return a new `Seq`. * * **Seq is lazy** — `Seq` does as little work as necessary to respond to any * method call. Values are often created during iteration, including implicit * iteration when reducing or converting to a concrete data structure such as * a `List` or JavaScript `Array`. * * For example, the following performs no work, because the resulting * `Seq`'s values are never iterated: * * ```js * const { Seq } = require('immutable') * const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ]) * .filter(x => x % 2 !== 0) * .map(x => x * x) * ``` * * Once the `Seq` is used, it performs only the work necessary. In this * example, no intermediate arrays are ever created, filter is called three * times, and map is only called once: * * ```js * oddSquares.get(1); // 9 * ``` * * Any collection can be converted to a lazy Seq with `Seq()`. * * * ```js * const { Map } = require('immutable') * const map = Map({ a: 1, b: 2, c: 3 } * const lazySeq = Seq(map) * ``` * * `Seq` allows for the efficient chaining of operations, allowing for the * expression of logic that can otherwise be very tedious: * * ```js * lazySeq * .flip() * .map(key => key.toUpperCase()) * .flip() * // Seq { A: 1, B: 1, C: 1 } * ``` * * As well as expressing logic that would otherwise seem memory or time * limited, for example `Range` is a special kind of Lazy sequence. * * * ```js * const { Range } = require('immutable') * Range(1, Infinity) * .skip(1000) * .map(n => -n) * .filter(n => n % 2 === 0) * .take(2) * .reduce((r, n) => r * n, 1) * // 1006008 * ``` * * Seq is often used to provide a rich collection API to JavaScript Object. * * ```js * Seq({ x: 0, y: 1, z: 2 }).map(v => v * 2).toObject(); * // { x: 0, y: 2, z: 4 } * ``` */ declare module Seq { /** * True if `maybeSeq` is a Seq, it is not backed by a concrete * structure such as Map, List, or Set. */ function isSeq(maybeSeq: any): maybeSeq is Seq.Indexed | Seq.Keyed | Seq.Set; /** * `Seq` which represents key-value pairs. */ export module Keyed {} /** * Always returns a Seq.Keyed, if input is not keyed, expects an * collection of [K, V] tuples. * * Note: `Seq.Keyed` is a conversion function and not a class, and does not * use the `new` keyword during construction. */ export function Keyed(collection: Iterable<[K, V]>): Seq.Keyed; export function Keyed(obj: {[key: string]: V}): Seq.Keyed; export function Keyed(): Seq.Keyed; export function Keyed(): Seq.Keyed; export interface Keyed extends Seq, Collection.Keyed { /** * Deeply converts this Keyed Seq to equivalent native JavaScript Object. * * Converts keys to Strings. */ toJS(): Object; /** * Shallowly converts this Keyed Seq to equivalent native JavaScript Object. * * Converts keys to Strings. */ toJSON(): { [key: string]: V }; /** * Shallowly converts this collection to an Array. */ toArray(): Array<[K, V]>; /** * Returns itself */ toSeq(): this; /** * Returns a new Seq with other collections concatenated to this one. * * All entries will be present in the resulting Seq, even if they * have the same key. */ concat(...collections: Array>): Seq.Keyed; concat(...collections: Array<{[key: string]: C}>): Seq.Keyed; /** * Returns a new Seq.Keyed with values passed through a * `mapper` function. * * ```js * const { Seq } = require('immutable') * Seq.Keyed({ a: 1, b: 2 }).map(x => 10 * x) * // Seq { "a": 10, "b": 20 } * ``` * * Note: `map()` always returns a new instance, even if it produced the * same value at every step. */ map( mapper: (value: V, key: K, iter: this) => M, context?: any ): Seq.Keyed; /** * @see Collection.Keyed.mapKeys */ mapKeys( mapper: (key: K, value: V, iter: this) => M, context?: any ): Seq.Keyed; /** * @see Collection.Keyed.mapEntries */ mapEntries( mapper: (entry: [K, V], index: number, iter: this) => [KM, VM], context?: any ): Seq.Keyed; /** * Flat-maps the Seq, returning a Seq of the same type. * * Similar to `seq.map(...).flatten(true)`. */ flatMap( mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, context?: any ): Seq.Keyed; /** * Returns a new Seq with only the entries for which the `predicate` * function returns true. * * Note: `filter()` always returns a new instance, even if it results in * not filtering out any values. */ filter( predicate: (value: V, key: K, iter: this) => value is F, context?: any ): Seq.Keyed; filter( predicate: (value: V, key: K, iter: this) => any, context?: any ): this; /** * @see Collection.Keyed.flip */ flip(): Seq.Keyed; } /** * `Seq` which represents an ordered indexed list of values. */ module Indexed { /** * Provides an Seq.Indexed of the values provided. */ function of(...values: Array

Example