Описание

Библиотека представляет работу со структурой данных "коллекция".

Коллекция - это объект, содержащий пары ключ-значение, но с ним можно работать как с массивом:

• итерация по every, for / for...of, forEach, map,
• фильтрация по filter,
• поиск по includes, find, some,
• реверсивные методы findReversed, forEachReversed,
• добавление по push, unshift,
• добавление по delete, pop, shift.

Библиотка javascript/typescript (ES6) для node.js.

Большинство операций оптимизировано по скорости работы.

• ключ:значение,
• индексированный массив,
• итерирование в обратном порядке,
• стек и очередь,
• быстрый поиск,
• методы forEach, map, filter.

Пример

Импортируем библиотеку:

import { Collection } from 'lib-collection';

Создадим коллекцию:

const collection = new Collection({
  a: 11,
  b: 22,
  c: 33,
});

Добавим новый элемент:

collection.push('d', 44);

Сделаем простое итерирование:

for (const [value, key] of collection) {
  console.log({ key, value });
}

Список методов

Методы извлечения данных:

• elements: CollectionType
• entries: EntriesType
• keys: string[]
• length: number
• values: T[]

Методы простых операций:

• add(obj: CollectionType)
• addByEntries(pairs: EntriesType)
• clear()
• delete(key: string)
• deleteByIndex(index: number)
• empty()
• get(key: string)
• getByIndex(index: number)
• includes(key: string)
• set(obj: CollectionType)
• setByEntries(pairs: EntriesType)

Методы изменения порядка коллекции:

• moveAfter(keyFrom: string, keyTo: string)
• moveBefore(keyFrom: string, keyTo: string)
• rename(oldName: string, newName: string)

Методы работы со стеком и очередью:

• pop()
• push(key: string, value: any)
• shift()
• unshift(key: string, value: any)

Методы итерации:

• every(callback: boolean)
• filter(callback: boolean)
• find(callback: boolean)
• findReversed(callback: boolean)
• forEach(callback: void)
• forEachReversed(callback: void)
• map(callback: U)
• reduce(callback: U, initialValue: U)
• some(callback: boolean)

Специальные методы:

• ${collection}
• collection.toString()
• String(collection)
• collection.toJSON()
• JSON.stringify(collection)
• Number(collection)
• +collection

Интерфейсы

CollectionType

{
  [key: string]: T;
}

EntriesType

[string, T][];

Конструктор

constructor(elements: CollectionType | undefined = undefined)

Создаёт экземпляр коллекции.

@param {CollectionType} [elements] - Элементы коллекции.

Методы извлечения данных

elements: CollectionType

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

@returns {CollectionType} Elements of collection.

entries: EntriesType

Возвращает все элементы коллекции в виде массива пар ключ-значение. Заново заполняет коллекцию из массива пар ключ-значение.

@returns {EntriesType<T>} Elements of collection as key-value pair array.

keys: string[]

Возвращает все ключи в коллекции.

@returns {string[]} Массив ключей.

length: number

Возвращает количество элементов в коллекции.

@returns {number} Длина коллекции.

values: T[]

Возвращает все значения в коллекции.

@returns {T[]} Массив значений.

Методы простых операций

add(obj: CollectionType)

Добавляет с заменой элементы в коллекцию из объекта ключ-значение.

Возвращает текущую коллекцию.

@param {Object} obj - Объект.

addByEntries(pairs: EntriesType)

Добавляет с заменой элементы в коллекцию из массива ключ-значение.

Возвращает текущую коллекцию.

@param {EntriesType<T>} pairs - Массив.

clear()

Очищает коллекцию.

Возвращает текущую коллекцию.

delete(key: string)

Удаляет элемент из коллекции по ключу.

Возвращает текущую коллекцию.

@param {string} key - Ключ удаляемого элемента.

deleteByIndex(index: number)

Удаляет элемент из коллекции по его индексу.

Возвращает текущую коллекцию.

@param {number} index - Индекс удаляемого элемента.

empty()

Проверяет, пустая коллекция или нет.

Возвращает true, если в коллекции нет элементов, false в противном случае.

get(key: string)

Возвращает элемент по ключу.

@param {string} key - ключ извлекаемого элемента.

getByIndex(index: number)

Возвращает элемент по указанному индексу.

@param {number} index - индекс извлекаемого элемента.

includes(key: string)

Проверяет, существует ли ключ в коллекции.

Возвращает true, если ключ существует, иначе false.

@param {string} key - ключ для проверки.

set(obj: CollectionType)

Заменяет коллекцию новыми элементами из объекта ключ-значение.

Возвращает текущую коллекцию.

@param {Object} obj - Объект.

setByEntries(pairs: EntriesType)

Добавляет с заменой элементы в коллекцию из массива ключ-значение.

Возвращает текущую коллекцию.

@param {EntriesType<T>} pairs - Массив.

Методы изменения порядка коллекции

moveAfter(keyFrom: string, keyTo: string)

Перемещает элемент коллекции после указанного.

Возвращает текущую коллекцию.

@param {string} keyFrom - Element key to move.
@param {string} keyTo - Key after which element should be placed.

moveBefore(keyFrom: string, keyTo: string)

Перемещает элемент коллекции перед указанным.

Возвращает текущую коллекцию.

@param {string} keyFrom - Element key to move.
@param {string} keyTo - Key before which element should be placed.

rename(oldName: string, newName: string)

Переименовывает ключ элемента.

Возвращает текущую коллекцию.

@param {string} oldName - Current name of item to be renamed.
@param {string} newName - New name to assign to item.

Методы работы со стеком и очередью

pop()

Удаляет и возвращает последний элемент из коллекции.

@returns {T} Удалённое значение.

push(key: string, value: any)

Добавляет новую пару ключ-значение в коллекцию.

@param {string} key - Ключ элемента.
@param {any} value - Значение элемента.

shift()

Удаляет и возвращает первый элемент из коллекции.

@returns {T} Удалённое значение.

unshift(key: string, value: any)

Добавляет новую пару ключ-значение в начало коллекции.

@param {string} key - Ключ элемента.
@param {any} value — значение элемента.

Методы итерации

Функция обратного вызова в итерациях всегда имеет одинаковые параметры:

callback: (value: T, key: string, index: number)

Первым аргументом передается значение элемента.

Вторым аргументом передается ключ элемента.

Третьм аргументом передается индекс элемента.

Ни один из этих аргументов не является обязательным.

every(callback: boolean)

Выполняет функцию один раз для каждой пары ключ-значение в коллекции.

Возвращает true, если обратный вызов возвращает истинное значение для каждого элемента. В противном случае — false.

filter(callback: boolean)

Применяет функцию к каждой паре ключ-значение, чтобы выполнить проверку.

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

find(callback: boolean)

Ищет первый элемент, удовлетворяющий предоставленной функции проверки.

Возвращает объект с парой ключ:значение.

findReversed(callback: boolean)

Ищет последний элемент, удовлетворяющий предоставленной функции проверки.

Возвращает объект с парой ключ:значение.

forEach(callback: void)

Выполняет предоставленную функцию один раз для каждой пары ключ-значение в коллекции.

Возвращает текущую коллекцию.

forEachReversed(callback: void)

Выполняет предоставленную функцию один раз для каждой пары ключ-значение, начиная с конца коллекции.

Возвращает текущую коллекцию.

map(callback: U)

Создаёт новую коллекцию, заполненную результатами вызова предоставленной функции для каждой пары ключ-значение.

reduce(callback: U, initialValue: U)

Агрегирует данные из коллекции в одно значение.

Первым аргументом передается функция callback.

Вторым необязательным аргументом initialValue передается начальное значение.

Функция callback здесь имеет немного другую структуру:

callback: (accumulator: U | undefined, value: T, key: string, index: number) => U;

Где accumulator - некое сквозное значение, которое изначально задается initialValue.

Метод выполняет предоставленную функцию один раз для каждой пары ключ-значение в коллекции.

И возвращает значение accumulator.

some(callback: boolean)

Выполняет проверку для элементов коллекции.

Возвращает true, если хотя бы один элемент прошел проверку. Иначе возвращает false.

Специальные методы

Коллекция может быть преобразована в строковое и числовое значение.

const collection = new Collection();

При вызове коллекции как строки, возвращается тип Collection и строка в формате json:

console.log(collection);
console.log(`${collection}`);
console.log(collection.toString());
console.log(String(collection));

При вызове коллекции как json, возвращается только строка в формате json:

console.log(collection.toJSON());
console.log(JSON.stringify(collection));

При вызове коллекции как числа, возвращается размер, количество элементов коллекции:

console.log(Number(collection));
console.log(+collection);

Особенности поведения

Коллекция всегда является упорядоченной структурой.

Методы add и push гарантируют добавление элементов в строгом порядке.

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

Для push, если в коллекции уже есть элемент с заданным ключом, то вместо него создается новый элемент, который добавляется в конец структуры.

Метод unshift действует аналогичным образом, только элементы добавляются в начало структуры.

Методы elements, entries, keys и values возвращают копии элементов структуры. На подготовку идут дополнительные расходы по памяти и времени.

Свойство entries возвращает массив пар ключ-значение. При этом оно гарантирует строгое сохранение порядка элементов.

Свойство elements возвращает объект пар ключ-значение, но не гарантирует сохранение того же порядка элементов, что и в коллекции.

Это происходит из-за поведения самих объектов в js. Например, объект

{ 2: 'a', 3: 'b', 1: 'c' };

Автоматически пример вид

{ 1: 'c', 2: 'a', 3: 'b' }

Если вы хотите создать структуру в изначальном порядке, вам нужно заполнять ее элементами последовательно:

collection.add('2', 'a');
collection.add('3', 'b');
collection.add('1', 'c');

Или использовать массив пар ключ-значение:

const pairs = [[2, 'a'], [3, 'b'], [1, 'c']];
collection.addByEntries(pairs);

Библиотека использует объекты вместо структуры данных Map. По нашим тестам, на текущий момент, это решение является более легким.

Рабочий пример

Давайте сделаем что-нибудь более веселое и приближенное к реальным задачам. Например, коллекцию котиков.

import { Collection } from 'lib-collection';

type CatsColors = 'black' | 'red' | 'white' | 'gray' | 'tricolor';

type CatsGenders = 'boy' | 'girl';

interface ICat {
  name: string;
  age: number;
  color?: CatsColors;
  gender?: CatsGenders;
};

const catsCollection = new Collection();

Давайте заведем пару котиков.

Помните, коллекция - это как именованный (ассоциативный) массив. Значит, каждая запись должна иметь ключ. Пусть ключом будет имя котика.

const cats = {
  Барсик: {
    name: 'Барсик',
    age: 1,
  },
  Пушок: {
    name: 'Пушок',
    age: 2,
  },
};

Можем их добавить в коллекцию:

catsCollection.add(cats);

А можем перезаписать через элементы:

catsCollection.set(cats);

Предположим, котики представлены массивом объектов:

const cats = [
  {
    name: 'Барсик',
    age: 1,
  },
  {
    name: 'Пушок',
    age: 2,
  },
];

Мы можем записать их последовательно:

cats.forEach((cat) => {
  catsCollection.add(cat.name, cat);
});

Можно ли массив так же просто добавить в коллекцию? Конечно. Но тогда ключами станут индексы. В этом нет смысла, потому что тогда коллекция не будет отличаться от массива.

Что мы получаем в результате.

По сравнению с массиsвом объектов, у нас есть быстрый доступ по ключу, без поиска и фильтрации:

const barsik = catsCollection.get('Барсик');

По сравнению с вложенными объектами, у нас есть сохранение последовательности и методы работы, как с обычным массивом:

catsCollection.forEach((cat) => {
  console.log(cat);
});

Версии

0.2.0

Библиотека полностью переписана на структуру Map.

Свойства переписаны на методы:

• elements,
• entries,
• keys,
• length,
• values.

Такое поведение более правильное, потому что значения больше не возвращаются по ссылке.

Добавлены новые методы:

В методах теперь почти всегда возвращается текущая коллекция. Это позволяет строить цепочки вызовов.

Добавлены методы для преобразования в строку, число и json.

Обновление платформы сборки:

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

0.1.2

Добавили тип (generic) класса коллекции для TypeScript.

0.1.1

Добавили три новых метода:

• rename - переименовать ключ элемента коллекции,
• moveAfter - переместить элемент коллекции после указанного,
• moveBefore - переместить элемент коллекции перед указанным.

Дополнено описание.

Поддержка

Больше интересных библиотек в репозитории.

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

А сейчас просто обнимите своих родных и близких, скажите им, как вы их любите.

Лицензия

Лицензия MIT, 2025