Brunobkr/llama.cpp_AlgMor24_github

1/** @ignore we should disable this rules, but let's activate it to enable eslint first */2/**3 * Immutable data encourages pure functions (data-in, data-out) and lends itself4 * to much simpler application development and enabling techniques from5 * functional programming such as lazy evaluation.6 *7 * While designed to bring these powerful functional concepts to JavaScript, it8 * presents an Object-Oriented API familiar to Javascript engineers and closely9 * mirroring that of Array, Map, and Set. It is easy and efficient to convert to10 * and from plain Javascript types.11 *12 * ## How to read these docs13 *14 * In order to better explain what kinds of values the Immutable.js API expects15 * and produces, this documentation is presented in a statically typed dialect of16 * JavaScript (like [Flow][] or [TypeScript][]). You *don't need* to use these17 * type checking tools in order to use Immutable.js, however becoming familiar18 * with their syntax will help you get a deeper understanding of this API.19 *20 * **A few examples and how to read them.**21 *22 * All methods describe the kinds of data they accept and the kinds of data23 * they return. For example a function which accepts two numbers and returns24 * a number would look like this:25 *26 * ```js27 * sum(first: number, second: number): number28 * ```29 *30 * Sometimes, methods can accept different kinds of data or return different31 * kinds of data, and this is described with a *type variable*, which is32 * typically in all-caps. For example, a function which always returns the same33 * kind of data it was provided would look like this:34 *35 * ```js36 * identity<T>(value: T): T37 * ```38 *39 * Type variables are defined with classes and referred to in methods. For40 * example, a class that holds onto a value for you might look like this:41 *42 * ```js43 * class Box<T> {44 *   constructor(value: T)45 *   getValue(): T46 * }47 * ```48 *49 * In order to manipulate Immutable data, methods that we're used to affecting50 * a Collection instead return a new Collection of the same type. The type51 * `this` refers to the same kind of class. For example, a List which returns52 * new Lists when you `push` a value onto it might look like:53 *54 * ```js55 * class List<T> {56 *   push(value: T): this57 * }58 * ```59 *60 * Many methods in Immutable.js accept values which implement the JavaScript61 * [Iterable][] protocol, and might appear like `Iterable<string>` for something62 * which represents sequence of strings. Typically in JavaScript we use plain63 * Arrays (`[]`) when an Iterable is expected, but also all of the Immutable.js64 * collections are iterable themselves!65 *66 * For example, to get a value deep within a structure of data, we might use67 * `getIn` which expects an `Iterable` path:68 *69 * ```70 * getIn(path: Iterable<string | number>): unknown71 * ```72 *73 * To use this method, we could pass an array: `data.getIn([ "key", 2 ])`.74 *75 *76 * Note: All examples are presented in the modern [ES2015][] version of77 * JavaScript. Use tools like Babel to support older browsers.78 *79 * For example:80 *81 * ```js82 * // ES201583 * const mappedFoo = foo.map(x => x * x);84 * // ES585 * var mappedFoo = foo.map(function (x) { return x * x; });86 * ```87 *88 * [ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla89 * [TypeScript]: https://www.typescriptlang.org/90 * [Flow]: https://flowtype.org/91 * [Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols92 */93 94declare namespace Immutable {95  /** @ignore */96  type OnlyObject<T> = Extract<T, object>;97 98  /** @ignore */99  type ContainObject<T> =100    OnlyObject<T> extends object101      ? OnlyObject<T> extends never102        ? false103        : true104      : false;105 106  /**107   * @ignore108   *109   * Used to convert deeply all immutable types to a plain TS type.110   * Using `unknown` on object instead of recursive call as we have a circular reference issue111   */112  export type DeepCopy<T> =113    T extends Record<infer R>114      ? // convert Record to DeepCopy plain JS object115        {116          [key in keyof R]: ContainObject<R[key]> extends true117            ? unknown118            : R[key];119        }120      : T extends MapOf<infer R>121        ? // convert MapOf to DeepCopy plain JS object122          {123            [key in keyof R]: ContainObject<R[key]> extends true124              ? unknown125              : R[key];126          }127        : T extends Collection.Keyed<infer KeyedKey, infer V>128          ? // convert KeyedCollection to DeepCopy plain JS object129            {130              [key in KeyedKey extends PropertyKey131                ? KeyedKey132                : string]: V extends object ? unknown : V;133            }134          : // convert IndexedCollection or Immutable.Set to DeepCopy plain JS array135            // eslint-disable-next-line @typescript-eslint/no-unused-vars136            T extends Collection<infer _, infer V>137            ? Array<DeepCopy<V>>138            : T extends string | number // Iterable scalar types : should be kept as is139              ? T140              : T extends Iterable<infer V> // Iterable are converted to plain JS array141                ? Array<DeepCopy<V>>142                : T extends object // plain JS object are converted deeply143                  ? {144                      [ObjectKey in keyof T]: ContainObject<145                        T[ObjectKey]146                      > extends true147                        ? unknown148                        : T[ObjectKey];149                    }150                  : // other case : should be kept as is151                    T;152 153  /**154   * Describes which item in a pair should be placed first when sorting155   *156   * @ignore157   */158  export enum PairSorting {159    LeftThenRight = -1,160    RightThenLeft = +1,161  }162 163  /**164   * Function comparing two items of the same type. It can return:165   *166   * * a PairSorting value, to indicate whether the left-hand item or the right-hand item should be placed before the other167   *168   * * the traditional numeric return value - especially -1, 0, or 1169   *170   * @ignore171   */172  export type Comparator<T> = (left: T, right: T) => PairSorting | number;173 174  /**175   * @ignore176   *177   * KeyPath allowed for `xxxIn` methods178   */179  export type KeyPath<K> = OrderedCollection<K> | ArrayLike<K>;180 181  /**182   * Lists are ordered indexed dense collections, much like a JavaScript183   * Array.184   *185   * Lists are immutable and fully persistent with O(log32 N) gets and sets,186   * and O(1) push and pop.187   *188   * Lists implement Deque, with efficient addition and removal from both the189   * end (`push`, `pop`) and beginning (`unshift`, `shift`).190   *191   * Unlike a JavaScript Array, there is no distinction between an192   * "unset" index and an index set to `undefined`. `List#forEach` visits all193   * indices from 0 to size, regardless of whether they were explicitly defined.194   */195  namespace List {196    /**197     * True if the provided value is a List198     */199    function isList(maybeList: unknown): maybeList is List<unknown>;200 201    /**202     * Creates a new List containing `values`.203     *204     * Note: Values are not altered or converted in any way.205     */206    function of<T>(...values: Array<T>): List<T>;207  }208 209  /**210   * Create a new immutable List containing the values of the provided211   * collection-like.212   *213   * Note: `List` is a factory function and not a class, and does not use the214   * `new` keyword during construction.215   */216  function List<T>(collection?: Iterable<T> | ArrayLike<T>): List<T>;217 218  interface List<T> extends Collection.Indexed<T> {219    /**220     * The number of items in this List.221     */222    readonly size: number;223 224    // Persistent changes225 226    /**227     * Returns a new List which includes `value` at `index`. If `index` already228     * exists in this List, it will be replaced.229     *230     * `index` may be a negative number, which indexes back from the end of the231     * List. `v.set(-1, "value")` sets the last item in the List.232     *233     * If `index` larger than `size`, the returned List's `size` will be large234     * enough to include the `index`.235     *236     * Note: `set` can be used in `withMutations`.237     */238    set(index: number, value: T): List<T>;239 240    /**241     * Returns a new List which excludes this `index` and with a size 1 less242     * than this List. Values at indices above `index` are shifted down by 1 to243     * fill the position.244     *245     * This is synonymous with `list.splice(index, 1)`.246     *247     * `index` may be a negative number, which indexes back from the end of the248     * List. `v.delete(-1)` deletes the last item in the List.249     *250     * Note: `delete` cannot be safely used in IE8251     *252     * Since `delete()` re-indexes values, it produces a complete copy, which253     * has `O(N)` complexity.254     *255     * Note: `delete` *cannot* be used in `withMutations`.256     *257     * @alias remove258     */259    delete(index: number): List<T>;260    remove(index: number): List<T>;261 262    /**263     * Returns a new List with `value` at `index` with a size 1 more than this264     * List. Values at indices above `index` are shifted over by 1.265     *266     * This is synonymous with `list.splice(index, 0, value)`.267     *268     * Since `insert()` re-indexes values, it produces a complete copy, which269     * has `O(N)` complexity.270     *271     * Note: `insert` *cannot* be used in `withMutations`.272     */273    insert(index: number, value: T): List<T>;274 275    /**276     * Returns a new List with 0 size and no values in constant time.277     *278     * Note: `clear` can be used in `withMutations`.279     */280    clear(): List<T>;281 282    /**283     * Returns a new List with the provided `values` appended, starting at this284     * List's `size`.285     *286     * Note: `push` can be used in `withMutations`.287     */288    push(...values: Array<T>): List<T>;289 290    /**291     * Returns a new List with a size ones less than this List, excluding292     * the last index in this List.293     *294     * Note: this differs from `Array#pop` because it returns a new295     * List rather than the removed value. Use `last()` to get the last value296     * in this List.297     *298     * ```js299     * List([ 1, 2, 3, 4 ]).pop()300     * // List[ 1, 2, 3 ]301     * ```302     *303     * Note: `pop` can be used in `withMutations`.304     */305    pop(): List<T>;306 307    /**308     * Returns a new List with the provided `values` prepended, shifting other309     * values ahead to higher indices.310     *311     * Note: `unshift` can be used in `withMutations`.312     */313    unshift(...values: Array<T>): List<T>;314 315    /**316     * Returns a new List with a size ones less than this List, excluding317     * the first index in this List, shifting all other values to a lower index.318     *319     * Note: this differs from `Array#shift` because it returns a new320     * List rather than the removed value. Use `first()` to get the first321     * value in this List.322     *323     * Note: `shift` can be used in `withMutations`.324     */325    shift(): List<T>;326 327    /**328     * Returns a new List with an updated value at `index` with the return329     * value of calling `updater` with the existing value, or `notSetValue` if330     * `index` was not set. If called with a single argument, `updater` is331     * called with the List itself.332     *333     * `index` may be a negative number, which indexes back from the end of the334     * List. `v.update(-1)` updates the last item in the List.335     *336     * This can be very useful as a way to "chain" a normal function into a337     * sequence of methods. RxJS calls this "let" and lodash calls it "thru".338     *339     * For example, to sum a List after mapping and filtering:340     *341     * Note: `update(index)` can be used in `withMutations`.342     *343     * @see `Map#update`344     */345    update(index: number, notSetValue: T, updater: (value: T) => T): this;346    update(347      index: number,348      updater: (value: T | undefined) => T | undefined349    ): this;350    update<R>(updater: (value: this) => R): R;351 352    /**353     * Returns a new List with size `size`. If `size` is less than this354     * List's size, the new List will exclude values at the higher indices.355     * If `size` is greater than this List's size, the new List will have356     * undefined values for the newly available indices.357     *358     * When building a new List and the final size is known up front, `setSize`359     * used in conjunction with `withMutations` may result in the more360     * performant construction.361     */362    setSize(size: number): List<T>;363 364    // Deep persistent changes365 366    /**367     * Returns a new List having set `value` at this `keyPath`. If any keys in368     * `keyPath` do not exist, a new immutable Map will be created at that key.369     *370     * Index numbers are used as keys to determine the path to follow in371     * the List.372     *373     * Plain JavaScript Object or Arrays may be nested within an Immutable.js374     * Collection, and setIn() can update those values as well, treating them375     * immutably by creating new copies of those values with the changes applied.376     *377     * Note: `setIn` can be used in `withMutations`.378     */379    setIn(keyPath: Iterable<unknown>, value: unknown): this;380 381    /**382     * Returns a new List having removed the value at this `keyPath`. If any383     * keys in `keyPath` do not exist, no change will occur.384     *385     * Plain JavaScript Object or Arrays may be nested within an Immutable.js386     * Collection, and removeIn() can update those values as well, treating them387     * immutably by creating new copies of those values with the changes applied.388     *389     * Note: `deleteIn` *cannot* be safely used in `withMutations`.390     *391     * @alias removeIn392     */393    deleteIn(keyPath: Iterable<unknown>): this;394    removeIn(keyPath: Iterable<unknown>): this;395 396    /**397     * Note: `updateIn` can be used in `withMutations`.398     *399     * @see `Map#updateIn`400     */401    updateIn(402      keyPath: Iterable<unknown>,403      notSetValue: unknown,404      updater: (value: unknown) => unknown405    ): this;406    updateIn(407      keyPath: Iterable<unknown>,408      updater: (value: unknown) => unknown409    ): this;410 411    /**412     * Note: `mergeIn` can be used in `withMutations`.413     *414     * @see `Map#mergeIn`415     */416    mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this;417 418    /**419     * Note: `mergeDeepIn` can be used in `withMutations`.420     *421     * @see `Map#mergeDeepIn`422     */423    mergeDeepIn(424      keyPath: Iterable<unknown>,425      ...collections: Array<unknown>426    ): this;427 428    // Transient changes429 430    /**431     * Note: Not all methods can be safely used on a mutable collection or within432     * `withMutations`! Check the documentation for each method to see if it433     * allows being used in `withMutations`.434     *435     * @see `Map#withMutations`436     */437    withMutations(mutator: (mutable: this) => unknown): this;438 439    /**440     * An alternative API for withMutations()441     *442     * Note: Not all methods can be safely used on a mutable collection or within443     * `withMutations`! Check the documentation for each method to see if it444     * allows being used in `withMutations`.445     *446     * @see `Map#asMutable`447     */448    asMutable(): this;449 450    /**451     * @see `Map#wasAltered`452     */453    wasAltered(): boolean;454 455    /**456     * @see `Map#asImmutable`457     */458    asImmutable(): this;459 460    // Sequence algorithms461 462    /**463     * Returns a new List with other values or collections concatenated to this one.464     *465     * Note: `concat` can be used in `withMutations`.466     *467     * @alias merge468     */469    concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>;470    merge<C>(...collections: Array<Iterable<C>>): List<T | C>;471 472    /**473     * Returns a new List with values passed through a474     * `mapper` function.475     */476    map<M>(477      mapper: (value: T, key: number, iter: this) => M,478      context?: unknown479    ): List<M>;480 481    /**482     * Flat-maps the List, returning a new List.483     *484     * Similar to `list.map(...).flatten(true)`.485     */486    flatMap<M>(487      mapper: (value: T, key: number, iter: this) => Iterable<M>,488      context?: unknown489    ): List<M>;490 491    /**492     * Returns a new List with only the values for which the `predicate`493     * function returns true.494     *495     * Note: `filter()` always returns a new instance, even if it results in496     * not filtering out any values.497     */498    filter<F extends T>(499      predicate: (value: T, index: number, iter: this) => value is F,500      context?: unknown501    ): List<F>;502    filter(503      predicate: (value: T, index: number, iter: this) => unknown,504      context?: unknown505    ): this;506 507    /**508     * Returns a new List with the values for which the `predicate`509     * function returns false and another for which is returns true.510     */511    partition<F extends T, C>(512      predicate: (this: C, value: T, index: number, iter: this) => value is F,513      context?: C514    ): [List<T>, List<F>];515    partition<C>(516      predicate: (this: C, value: T, index: number, iter: this) => unknown,517      context?: C518    ): [this, this];519 520    /**521     * Returns a List "zipped" with the provided collection.522     *523     * Like `zipWith`, but using the default `zipper`: creating an `Array`.524     */525    zip<U>(other: Collection<unknown, U>): List<[T, U]>;526    zip<U, V>(527      other: Collection<unknown, U>,528      other2: Collection<unknown, V>529    ): List<[T, U, V]>;530    zip(...collections: Array<Collection<unknown, unknown>>): List<unknown>;531 532    /**533     * Returns a List "zipped" with the provided collections.534     *535     * Unlike `zip`, `zipAll` continues zipping until the longest collection is536     * exhausted. Missing values from shorter collections are filled with `undefined`.537     *538     * Note: Since zipAll will return a collection as large as the largest539     * input, some results may contain undefined values. TypeScript cannot540     * account for these without cases (as of v2.5).541     */542    zipAll<U>(other: Collection<unknown, U>): List<[T, U]>;543    zipAll<U, V>(544      other: Collection<unknown, U>,545      other2: Collection<unknown, V>546    ): List<[T, U, V]>;547    zipAll(...collections: Array<Collection<unknown, unknown>>): List<unknown>;548 549    /**550     * Returns a List "zipped" with the provided collections by using a551     * custom `zipper` function.552     */553    zipWith<U, Z>(554      zipper: (value: T, otherValue: U) => Z,555      otherCollection: Collection<unknown, U>556    ): List<Z>;557    zipWith<U, V, Z>(558      zipper: (value: T, otherValue: U, thirdValue: V) => Z,559      otherCollection: Collection<unknown, U>,560      thirdCollection: Collection<unknown, V>561    ): List<Z>;562    zipWith<Z>(563      zipper: (...values: Array<unknown>) => Z,564      ...collections: Array<Collection<unknown, unknown>>565    ): List<Z>;566 567    /**568     * Returns a new List with its values shuffled thanks to the569     * [Fisher–Yates](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle)570     * algorithm.571     * It uses Math.random, but you can provide your own random number generator.572     */573    shuffle(random?: () => number): this;574  }575 576  /**577   * Immutable Map is an unordered Collection.Keyed of (key, value) pairs with578   * `O(log32 N)` gets and `O(log32 N)` persistent sets.579   *580   * Iteration order of a Map is undefined, however is stable. Multiple581   * iterations of the same Map will iterate in the same order.582   *583   * Map's keys can be of any type, and use `Immutable.is` to determine key584   * equality. This allows the use of any value (including NaN) as a key.585   *586   * Because `Immutable.is` returns equality based on value semantics, and587   * Immutable collections are treated as values, any Immutable collection may588   * be used as a key.589   *590   * Any JavaScript object may be used as a key, however strict identity is used591   * to evaluate key equality. Two similar looking objects will represent two592   * different keys.593   *594   * Implemented by a hash-array mapped trie.595   */596  namespace Map {597    /**598     * True if the provided value is a Map599     */600    function isMap(maybeMap: unknown): maybeMap is Map<unknown, unknown>;601  }602 603  /**604   * Creates a new Immutable Map.605   *606   * Created with the same key value pairs as the provided Collection.Keyed or607   * JavaScript Object or expects a Collection of [K, V] tuple entries.608   *609   * Note: `Map` is a factory function and not a class, and does not use the610   * `new` keyword during construction.611   *612   * Keep in mind, when using JS objects to construct Immutable Maps, that613   * JavaScript Object properties are always strings, even if written in a614   * quote-less shorthand, while Immutable Maps accept keys of any type.615   *616   * Property access for JavaScript Objects first converts the key to a string,617   * but since Immutable Map keys can be of any type the argument to `get()` is618   * not altered.619   */620  function Map<K, V>(collection?: Iterable<readonly [K, V]>): Map<K, V>;621  function Map<R extends { [key in PropertyKey]: unknown }>(obj: R): MapOf<R>;622  function Map<V>(obj: { [key: string]: V }): Map<string, V>;623  function Map<K extends string | symbol, V>(obj: { [P in K]?: V }): Map<K, V>;624 625  /**626   * Represent a Map constructed by an object627   *628   * @ignore629   */630  interface MapOf<R extends { [key in PropertyKey]: unknown }>631    extends Map<keyof R, R[keyof R]> {632    /**633     * Returns the value associated with the provided key, or notSetValue if634     * the Collection does not contain this key.635     *636     * Note: it is possible a key may be associated with an `undefined` value,637     * so if `notSetValue` is not provided and this method returns `undefined`,638     * that does not guarantee the key was not found.639     */640    get<K extends keyof R>(key: K, notSetValue?: unknown): R[K];641    get<NSV>(key: unknown, notSetValue: NSV): NSV;642 643    // TODO `<const P extends ...>` can be used after dropping support for TypeScript 4.x644    // reference: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters645    // after this change, `as const` assertions can be remove from the type tests646    getIn<P extends ReadonlyArray<PropertyKey>>(647      searchKeyPath: [...P],648      notSetValue?: unknown649    ): RetrievePath<R, P>;650 651    set<K extends keyof R>(key: K, value: R[K]): this;652 653    update(updater: (value: this) => this): this;654    update<K extends keyof R>(key: K, updater: (value: R[K]) => R[K]): this;655    update<K extends keyof R, NSV extends R[K]>(656      key: K,657      notSetValue: NSV,658      updater: (value: R[K]) => R[K]659    ): this;660 661    // Possible best type is MapOf<Omit<R, K>> but Omit seems to broke other function calls662    // and generate recursion error with other methods (update, merge, etc.) until those functions are defined in MapOf663    delete<K extends keyof R>(664      key: K665    ): Extract<R[K], undefined> extends never ? never : this;666    remove<K extends keyof R>(667      key: K668    ): Extract<R[K], undefined> extends never ? never : this;669 670    toJS(): { [K in keyof R]: DeepCopy<R[K]> };671 672    toJSON(): { [K in keyof R]: R[K] };673  }674 675  // Loosely based off of this work.676  // https://github.com/immutable-js/immutable-js/issues/1462#issuecomment-584123268677 678  /**679   * @ignore680   * Convert an immutable type to the equivalent plain TS type681   * - MapOf -> object682   * - List -> Array683   */684  type GetNativeType<S> =685    S extends MapOf<infer T> ? T : S extends List<infer I> ? Array<I> : S;686 687  /** @ignore */688  type Head<T extends ReadonlyArray<unknown>> = T extends [689    infer H,690    ...Array<unknown>,691  ]692    ? H693    : never;694  /** @ignore */695  type Tail<T extends ReadonlyArray<unknown>> = T extends [unknown, ...infer I]696    ? I697    : Array<never>;698  /** @ignore */699  type RetrievePathReducer<700    T,701    C,702    L extends ReadonlyArray<unknown>,703    NT = GetNativeType<T>,704  > =705    // we can not retrieve a path from a primitive type706    T extends string | number | boolean | null | undefined707      ? never708      : C extends keyof NT709        ? L extends [] // L extends [] means we are at the end of the path, lets return the current type710          ? NT[C]711          : // we are not at the end of the path, lets continue with the next key712            RetrievePathReducer<NT[C], Head<L>, Tail<L>>713        : // C is not a "key" of NT, so the path is invalid714          never;715 716  /** @ignore */717  type RetrievePath<R, P extends ReadonlyArray<unknown>> = P extends []718    ? P719    : RetrievePathReducer<R, Head<P>, Tail<P>>;720 721  interface Map<K, V> extends Collection.Keyed<K, V> {722    /**723     * The number of entries in this Map.724     */725    readonly size: number;726 727    // Persistent changes728 729    /**730     * Returns a new Map also containing the new key, value pair. If an equivalent731     * key already exists in this Map, it will be replaced.732     *733     * Note: `set` can be used in `withMutations`.734     */735    set(key: K, value: V): this;736 737    /**738     * Returns a new Map which excludes this `key`.739     *740     * Note: `delete` cannot be safely used in IE8, but is provided to mirror741     * the ES6 collection API.742     *743     * Note: `delete` can be used in `withMutations`.744     *745     * @alias remove746     */747    delete(key: K): this;748    remove(key: K): this;749 750    /**751     * Returns a new Map which excludes the provided `keys`.752     *753     * Note: `deleteAll` can be used in `withMutations`.754     *755     * @alias removeAll756     */757    deleteAll(keys: Iterable<K>): this;758    removeAll(keys: Iterable<K>): this;759 760    /**761     * Returns a new Map containing no keys or values.762     *763     * Note: `clear` can be used in `withMutations`.764     */765    clear(): this;766 767    /**768     * Returns a new Map having updated the value at this `key` with the return769     * value of calling `updater` with the existing value.770     *771     * Similar to: `map.set(key, updater(map.get(key)))`.772     *773     * This is most commonly used to call methods on collections within a774     * structure of data. For example, in order to `.push()` onto a nested `List`,775     * `update` and `push` can be used together:776     *777     * When a `notSetValue` is provided, it is provided to the `updater`778     * function when the value at the key does not exist in the Map.779     *780     * However, if the `updater` function returns the same value it was called781     * with, then no change will occur. This is still true if `notSetValue`782     * is provided.783     *784     * For code using ES2015 or later, using `notSetValue` is discourged in785     * favor of function parameter default values. This helps to avoid any786     * potential confusion with identify functions as described above.787     *788     * The previous example behaves differently when written with default values:789     *790     * If no key is provided, then the `updater` function return value is791     * returned as well.792     *793     * This can be very useful as a way to "chain" a normal function into a794     * sequence of methods. RxJS calls this "let" and lodash calls it "thru".795     *796     * For example, to sum the values in a Map797     *798     * Note: `update(key)` can be used in `withMutations`.799     */800    update(key: K, notSetValue: V, updater: (value: V) => V): this;801    update(key: K, updater: (value: V | undefined) => V | undefined): this;802    update<R>(updater: (value: this) => R): R;803 804    /**805     * Returns a new Map resulting from merging the provided Collections806     * (or JS objects) into this Map. In other words, this takes each entry of807     * each collection and sets it on this Map.808     *809     * Note: Values provided to `merge` are shallowly converted before being810     * merged. No nested values are altered.811     * ```812     *813     * Note: `merge` can be used in `withMutations`.814     *815     * @alias concat816     */817    merge<KC, VC>(818      ...collections: Array<Iterable<[KC, VC]>>819    ): Map<K | KC, Exclude<V, VC> | VC>;820    merge<C>(821      ...collections: Array<{ [key: string]: C }>822    ): Map<K | string, Exclude<V, C> | C>;823 824    concat<KC, VC>(825      ...collections: Array<Iterable<[KC, VC]>>826    ): Map<K | KC, Exclude<V, VC> | VC>;827    concat<C>(828      ...collections: Array<{ [key: string]: C }>829    ): Map<K | string, Exclude<V, C> | C>;830 831    /**832     * Like `merge()`, `mergeWith()` returns a new Map resulting from merging833     * the provided Collections (or JS objects) into this Map, but uses the834     * `merger` function for dealing with conflicts.835     *836     * Note: `mergeWith` can be used in `withMutations`.837     */838    mergeWith<KC, VC, VCC>(839      merger: (oldVal: V, newVal: VC, key: K) => VCC,840      ...collections: Array<Iterable<[KC, VC]>>841    ): Map<K | KC, V | VC | VCC>;842    mergeWith<C, CC>(843      merger: (oldVal: V, newVal: C, key: string) => CC,844      ...collections: Array<{ [key: string]: C }>845    ): Map<K | string, V | C | CC>;846 847    /**848     * Like `merge()`, but when two compatible collections are encountered with849     * the same key, it merges them as well, recursing deeply through the nested850     * data. Two collections are considered to be compatible (and thus will be851     * merged together) if they both fall into one of three categories: keyed852     * (e.g., `Map`s, `Record`s, and objects), indexed (e.g., `List`s and853     * arrays), or set-like (e.g., `Set`s). If they fall into separate854     * categories, `mergeDeep` will replace the existing collection with the855     * collection being merged in. This behavior can be customized by using856     * `mergeDeepWith()`.857     *858     * Note: Indexed and set-like collections are merged using859     * `concat()`/`union()` and therefore do not recurse.860     *861     * Note: `mergeDeep` can be used in `withMutations`.862     */863    mergeDeep<KC, VC>(864      ...collections: Array<Iterable<[KC, VC]>>865    ): Map<K | KC, V | VC>;866    mergeDeep<C>(867      ...collections: Array<{ [key: string]: C }>868    ): Map<K | string, V | C>;869 870    /**871     * Like `mergeDeep()`, but when two non-collections or incompatible872     * collections are encountered at the same key, it uses the `merger`873     * function to determine the resulting value. Collections are considered874     * incompatible if they fall into separate categories between keyed,875     * indexed, and set-like.876     *877     * Note: `mergeDeepWith` can be used in `withMutations`.878     */879    mergeDeepWith(880      merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,881      ...collections: Array<Iterable<[K, V]> | { [key: string]: V }>882    ): this;883 884    // Deep persistent changes885 886    /**887     * Returns a new Map having set `value` at this `keyPath`. If any keys in888     * `keyPath` do not exist, a new immutable Map will be created at that key.889     *890     * Plain JavaScript Object or Arrays may be nested within an Immutable.js891     * Collection, and setIn() can update those values as well, treating them892     * immutably by creating new copies of those values with the changes applied.893     *894     * If any key in the path exists but cannot be updated (such as a primitive895     * like number or a custom Object like Date), an error will be thrown.896     *897     * Note: `setIn` can be used in `withMutations`.898     */899    setIn(keyPath: Iterable<unknown>, value: unknown): this;900 901    /**902     * Returns a new Map having removed the value at this `keyPath`. If any keys903     * in `keyPath` do not exist, no change will occur.904     *905     * Note: `deleteIn` can be used in `withMutations`.906     *907     * @alias removeIn908     */909    deleteIn(keyPath: Iterable<unknown>): this;910    removeIn(keyPath: Iterable<unknown>): this;911 912    /**913     * Returns a new Map having applied the `updater` to the entry found at the914     * keyPath.915     *916     * This is most commonly used to call methods on collections nested within a917     * structure of data. For example, in order to `.push()` onto a nested `List`,918     * `updateIn` and `push` can be used together:919 920     *921     * If any keys in `keyPath` do not exist, new Immutable `Map`s will922     * be created at those keys. If the `keyPath` does not already contain a923     * value, the `updater` function will be called with `notSetValue`, if924     * provided, otherwise `undefined`.925     *926     * If the `updater` function returns the same value it was called with, then927     * no change will occur. This is still true if `notSetValue` is provided.928     *929     * For code using ES2015 or later, using `notSetValue` is discourged in930     * favor of function parameter default values. This helps to avoid any931     * potential confusion with identify functions as described above.932     *933     * The previous example behaves differently when written with default values:934     *935     * Plain JavaScript Object or Arrays may be nested within an Immutable.js936     * Collection, and updateIn() can update those values as well, treating them937     * immutably by creating new copies of those values with the changes applied.938     *939     * If any key in the path exists but cannot be updated (such as a primitive940     * like number or a custom Object like Date), an error will be thrown.941     *942     * Note: `updateIn` can be used in `withMutations`.943     */944    updateIn(945      keyPath: Iterable<unknown>,946      notSetValue: unknown,947      updater: (value: unknown) => unknown948    ): this;949    updateIn(950      keyPath: Iterable<unknown>,951      updater: (value: unknown) => unknown952    ): this;953 954    /**955     * A combination of `updateIn` and `merge`, returning a new Map, but956     * performing the merge at a point arrived at by following the keyPath.957     * In other words, these two lines are equivalent:958     *959     * ```js960     * map.updateIn(['a', 'b', 'c'], abc => abc.merge(y))961     * map.mergeIn(['a', 'b', 'c'], y)962     * ```963     *964     * Note: `mergeIn` can be used in `withMutations`.965     */966    mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this;967 968    /**969     * A combination of `updateIn` and `mergeDeep`, returning a new Map, but970     * performing the deep merge at a point arrived at by following the keyPath.971     * In other words, these two lines are equivalent:972     *973     * ```js974     * map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y))975     * map.mergeDeepIn(['a', 'b', 'c'], y)976     * ```977     *978     * Note: `mergeDeepIn` can be used in `withMutations`.979     */980    mergeDeepIn(981      keyPath: Iterable<unknown>,982      ...collections: Array<unknown>983    ): this;984 985    // Transient changes986 987    /**988     * Every time you call one of the above functions, a new immutable Map is989     * created. If a pure function calls a number of these to produce a final990     * return value, then a penalty on performance and memory has been paid by991     * creating all of the intermediate immutable Maps.992     *993     * If you need to apply a series of mutations to produce a new immutable994     * Map, `withMutations()` creates a temporary mutable copy of the Map which995     * can apply mutations in a highly performant manner. In fact, this is996     * exactly how complex mutations like `merge` are done.997     *998     * As an example, this results in the creation of 2, not 4, new Maps:999     *1000     * Note: Not all methods can be used on a mutable collection or within1001     * `withMutations`! Read the documentation for each method to see if it1002     * is safe to use in `withMutations`.1003     */1004    withMutations(mutator: (mutable: this) => unknown): this;1005 1006    /**1007     * Another way to avoid creation of intermediate Immutable maps is to create1008     * a mutable copy of this collection. Mutable copies *always* return `this`,1009     * and thus shouldn't be used for equality. Your function should never return1010     * a mutable copy of a collection, only use it internally to create a new1011     * collection.1012     *1013     * If possible, use `withMutations` to work with temporary mutable copies as1014     * it provides an easier to use API and considers many common optimizations.1015     *1016     * Note: if the collection is already mutable, `asMutable` returns itself.1017     *1018     * Note: Not all methods can be used on a mutable collection or within1019     * `withMutations`! Read the documentation for each method to see if it1020     * is safe to use in `withMutations`.1021     *1022     * @see `Map#asImmutable`1023     */1024    asMutable(): this;1025 1026    /**1027     * Returns true if this is a mutable copy (see `asMutable()`) and mutative1028     * alterations have been applied.1029     *1030     * @see `Map#asMutable`1031     */1032    wasAltered(): boolean;1033 1034    /**1035     * The yin to `asMutable`'s yang. Because it applies to mutable collections,1036     * this operation is *mutable* and may return itself (though may not1037     * return itself, i.e. if the result is an empty collection). Once1038     * performed, the original mutable copy must no longer be mutated since it1039     * may be the immutable result.1040     *1041     * If possible, use `withMutations` to work with temporary mutable copies as1042     * it provides an easier to use API and considers many common optimizations.1043     *1044     * @see `Map#asMutable`1045     */1046    asImmutable(): this;1047 1048    // Sequence algorithms1049 1050    /**1051     * Returns a new Map with values passed through a1052     * `mapper` function.1053     *1054     *     Map({ a: 1, b: 2 }).map(x => 10 * x)1055     *     // Map { a: 10, b: 20 }1056     */1057    map<M>(1058      mapper: (value: V, key: K, iter: this) => M,1059      context?: unknown1060    ): Map<K, M>;1061 1062    /**1063     * @see Collection.Keyed.mapKeys1064     */1065    mapKeys<M>(1066      mapper: (key: K, value: V, iter: this) => M,1067      context?: unknown1068    ): Map<M, V>;1069 1070    /**1071     * @see Collection.Keyed.mapEntries1072     */1073    mapEntries<KM, VM>(1074      mapper: (1075        entry: [K, V],1076        index: number,1077        iter: this1078      ) => [KM, VM] | undefined,1079      context?: unknown1080    ): Map<KM, VM>;1081 1082    /**1083     * Flat-maps the Map, returning a new Map.1084     *1085     * Similar to `data.map(...).flatten(true)`.1086     */1087    flatMap<KM, VM>(1088      mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,1089      context?: unknown1090    ): Map<KM, VM>;1091 1092    /**1093     * Returns a new Map with only the entries for which the `predicate`1094     * function returns true.1095     *1096     * Note: `filter()` always returns a new instance, even if it results in1097     * not filtering out any values.1098     */1099    filter<F extends V>(1100      predicate: (value: V, key: K, iter: this) => value is F,1101      context?: unknown1102    ): Map<K, F>;1103    filter(1104      predicate: (value: V, key: K, iter: this) => unknown,1105      context?: unknown1106    ): this;1107 1108    /**1109     * Returns a new Map with the values for which the `predicate`1110     * function returns false and another for which is returns true.1111     */1112    partition<F extends V, C>(1113      predicate: (this: C, value: V, key: K, iter: this) => value is F,1114      context?: C1115    ): [Map<K, V>, Map<K, F>];1116    partition<C>(1117      predicate: (this: C, value: V, key: K, iter: this) => unknown,1118      context?: C1119    ): [this, this];1120 1121    /**1122     * @see Collection.Keyed.flip1123     */1124    flip(): Map<V, K>;1125 1126    /**1127     * Returns an OrderedMap of the same type which includes the same entries,1128     * stably sorted by using a `comparator`.1129     *1130     * If a `comparator` is not provided, a default comparator uses `<` and `>`.1131     *1132     * `comparator(valueA, valueB)`:1133     *1134     *   * Returns `0` if the elements should not be swapped.1135     *   * Returns `-1` (or any negative number) if `valueA` comes before `valueB`1136     *   * Returns `1` (or any positive number) if `valueA` comes after `valueB`1137     *   * Alternatively, can return a value of the `PairSorting` enum type1138     *   * Is pure, i.e. it must always return the same value for the same pair1139     *     of values.1140     *1141     * Note: `sort()` Always returns a new instance, even if the original was1142     * already sorted.1143     *1144     * Note: This is always an eager operation.1145     */1146    sort(comparator?: Comparator<V>): this & OrderedMap<K, V>;1147 1148    /**1149     * Like `sort`, but also accepts a `comparatorValueMapper` which allows for1150     * sorting by more sophisticated means:1151     *1152     * Note: `sortBy()` Always returns a new instance, even if the original was1153     * already sorted.1154     *1155     * Note: This is always an eager operation.1156     */1157    sortBy<C>(1158      comparatorValueMapper: (value: V, key: K, iter: this) => C,1159      comparator?: (valueA: C, valueB: C) => number1160    ): this & OrderedMap<K, V>;1161  }1162 1163  /**1164   * A type of Map that has the additional guarantee that the iteration order of1165   * entries will be the order in which they were set().1166   *1167   * The iteration behavior of OrderedMap is the same as native ES6 Map and1168   * JavaScript Object.1169   *1170   * Note that `OrderedMap` are more expensive than non-ordered `Map` and may1171   * consume more memory. `OrderedMap#set` is amortized O(log32 N), but not1172   * stable.1173   */1174  namespace OrderedMap {1175    /**1176     * True if the provided value is an OrderedMap.1177     */1178    function isOrderedMap(1179      maybeOrderedMap: unknown1180    ): maybeOrderedMap is OrderedMap<unknown, unknown>;1181  }1182 1183  /**1184   * Creates a new Immutable OrderedMap.1185   *1186   * Created with the same key value pairs as the provided Collection.Keyed or1187   * JavaScript Object or expects a Collection of [K, V] tuple entries.1188   *1189   * The iteration order of key-value pairs provided to this constructor will1190   * be preserved in the OrderedMap.1191   *1192   *     let newOrderedMap = OrderedMap({key: "value"})1193   *     let newOrderedMap = OrderedMap([["key", "value"]])1194   *1195   * Note: `OrderedMap` is a factory function and not a class, and does not use1196   * the `new` keyword during construction.1197   */1198  function OrderedMap<K, V>(collection?: Iterable<[K, V]>): OrderedMap<K, V>;1199  function OrderedMap<V>(obj: { [key: string]: V }): OrderedMap<string, V>;1200 

Showing the first 1,200 of 5129 lines. Download the file for the rest.