Неизменяемые данные поощряют чистые функции (входные данные — выходные данные) и упрощают разработку приложений, а также позволяют использовать такие приёмы функционального программирования, как ленивая вычисления.

Хотя разработан для внедрения этих мощных функциональных концепций в JavaScript, он предоставляет объектно-ориентированный API, знакомый разработчикам JavaScript и тесно связанный с API массивов, карт и множеств. Легко и эффективно преобразовывать в обычные типы JavaScript.

Как читать эти документы

Для лучшего объяснения типов значений, ожидаемых и производимых API Immutable.js, эта документация представлена в статически типизированном диалекте JavaScript (например, Flow или TypeScript). Вам не нужно использовать эти инструменты проверки типов для использования Immutable.js, однако знакомство с их синтаксисом поможет вам лучше понять этот API.

Несколько примеров и как их читать.

Все методы описывают типы данных, которые они принимают, и типы данных, которые они возвращают. Например, функция, которая принимает два числа и возвращает число, будет выглядеть так:

sum(first: number, second: number): number

Иногда методы могут принимать разные типы данных или возвращать разные типы данных, и это описывается с помощью переменной типа, которая обычно записывается заглавными буквами. Например, функция, которая всегда возвращает тот же тип данных, что и входной, будет выглядеть так:

identity<T>(value: T): T

Переменные типов определяются классами и упоминаются в методах. Например, класс, который хранит значение для вас, может выглядеть так:

class Box<T> {
  constructor(value: T)
  getValue(): T
}

Для работы с данными Immutable методы, к которым мы привыкли, для изменения Коллекции вместо этого возвращают новую Коллекцию того же типа. Тип this относится к тому же классу. Например, список, который возвращает новые списки при добавлении значения, может выглядеть так:

class List<T> {
  push(value: T): this
}

Многие методы в Immutable.js принимают значения, которые реализуют протокол JavaScript Iterable, и могут выглядеть, например, как Iterable<string> для последовательности строк. Как правило, в JavaScript для обозначения Iterable используются обычные массивы ([]), но и все коллекции Immutable.js являются итерируемыми!

Например, для получения значения глубоко в структуре данных можно использовать getIn, который ожидает Iterable путь:

getIn(path: Iterable<string | number>): unknown

Для использования этого метода можно передать массив: data.getIn([ "key", 2 ]).

Примечание: все примеры представлены в современной версии JavaScript ES2015. Используйте инструменты, такие как Babel, для поддержки старых браузеров.

Например:

// ES2015
const mappedFoo = foo.map(x => x * x);
// ES5
var mappedFoo = foo.map(function (x) { return x * x; });

Списки — это упорядоченные, индексированные, плотные коллекции, очень похожие на JavaScript массив.

Неизменяемая Карта — это неупорядоченная Коллекция пар (ключ, значение) с O(log32 N) получением и O(log32 N) постоянными множествами.

Тип Карты, который гарантирует, что порядок итерирования записей будет соответствовать порядку их установки.

Коллекция уникальных значений с O(log32 N) добавлением и наличием.

Тип Множества, который гарантирует, что порядок итерирования значений будет соответствовать порядку их add.

Стеки — это индексированные коллекции, которые поддерживают очень эффективное добавление и удаление из начала за O(1) с помощью unshift(v) и shift().

Возвращает Seq.Indexed чисел от start (включительно) до end (исключительно), с шагом step, где start по умолчанию 0, step 1, и end бесконечность. Когда start равно end, возвращается пустой диапазон.

Возвращает Seq.Indexed значения value повторяющегося times раз. Если times не определено, возвращается бесконечная Seq последовательность из value.

Запись похожа на JS объект, но принудительно накладывает определенный набор разрешенных строковых ключей и имеет значения по умолчанию.

Фабрика Записей создается функцией Record(). Экземпляры Записей создаются путем передачи ей некоторых принятых значений для данного типа Записи:

Seq описывает ленивые операции, позволяющие эффективно использовать все методы высшего порядка для коллекций (например, map и filter) без создания промежуточных коллекций.

Seq представляющая пары ключ-значение.

Seq представляющая упорядоченный индексированный список значений.

Seq представляющая множество значений.

Collection — это набор (ключ, значение) записей, по которым можно итерироваться, и является базовым классом для всех коллекций в immutable, позволяя им использовать все методы Коллекций (например, map и filter).

Ключевые коллекции имеют дискретные ключи, привязанные к каждому значению.

Индексированные коллекции имеют инкрементные числовые ключи. Они демонстрируют немного другое поведение, чем Collection.Keyed для некоторых методов, чтобы лучше отразить поведение JavaScript Array, и добавляют методы, которые не имеют смысла для неиндексированных коллекций, таких как indexOf.

Множества Коллекций представляют только значения. У них нет связанных ключей или индексов. Повторяющиеся значения возможны в ленивых Seq.Set , однако конкретная Set Коллекция не допускает дубликатов.

Глубоко преобразует обычные JS объекты и массивы в неизменяемые карты и списки.

Проверка равенства значений со семантикой, похожей на Object.is, но рассматривает неизменяемые Collection как значения, равные, если второе Collection содержит эквивалентные значения.

Функция hash() является важной частью того, как Immutable определяет, являются ли два значения эквивалентными, и используется для определения того, как хранить эти значения. Принимая любое значение, hash() вернет 31-битное целое число.

Истина, если maybeImmutable является неизменяемой коллекцией или записью.

Истина, если maybeCollection является коллекцией или любым из её подклассов.

Истина, если maybeKeyed является Collection.Keyed или любым из её подклассов.

Истина, если maybeIndexed является Collection.Indexed или любым из её подклассов.

Истина, если maybeAssociative является либо ключевой, либо индексированной коллекцией.

Истина, если maybeOrdered — коллекция, где порядок итерирования определён. Истина для Collection.Indexed, а также OrderedMap и OrderedSet.

Истина, если maybeValue является JavaScript объектом, который имеет методы equals() и hashCode().

Истина, если maybeSeq является Seq.

Истина, если maybeList является списком.

Истина, если maybeMap является картой.

Истина, если maybeOrderedMap является упорядоченной картой.

Истина, если maybeStack является стеком.

Истина, если maybeSet является множеством.

Истина, если maybeOrderedSet является упорядоченным множеством.

Истина, если maybeRecord является записью.

Возвращает true, если ключ определён в предоставленной коллекции.

Возвращает значение по заданному пути ключа, начиная с предоставленной коллекции, или notSetValue, если путь ключа не определён.

Возвращает true, если путь ключа определён в предоставленной коллекции.

Возвращает копию коллекции со удалённым значением по пути ключа.

Возвращает копию коллекции со значением по пути ключа, установленным в предоставленное значение.

Возвращает копию коллекции с объединёнными остальными коллекциями.

Возвращает копию коллекции с объединёнными остальными коллекциями, вызывая функцию merger всякий раз, когда встречается существующее значение.

Как и merge(), но когда встречаются две совместимые коллекции с одинаковым ключом, они также объединяются, рекурсивно проходя по вложенным данным. Две коллекции считаются совместимыми (и, следовательно, будут объединены), если они обе относятся к одной из трех категорий: с ключами (например, Mapы, Recordы и объекты), индексированные (например, Listы и массивы) или подобные множествам (например, Setы). Если они относятся к разным категориям, mergeDeep заменит существующую коллекцию коллекцией, которая должна быть объединена. Это поведение можно настроить, используя mergeDeepWith().

Как и mergeDeep(), но когда встречаются две не-коллекции или несовместимые коллекции по одному и тому же ключу, она использует функцию merger, чтобы определить результирующее значение. Коллекции считаются несовместимыми, если они относятся к разным категориям между с ключами, индексированными и подобными множествам.