mn-utils

Набор утилит для работы с данными, URL, временем, событиями и асинхронным кодом.

Установка

npm install

Сборка

npm run build

Типы и сборка попадают в dist/.

Тесты

npm test

Документация API

Генерация Typedoc в каталог docs/:

npm run docs

Лицензия

MIT

Основные модули

• URL: urlParse, urlExtend, unparam, param — разбор и расширение URL, query-строки
• Время: formatTime, normalizeDate, getData — форматирование и нормализация дат
• События: attachEvent, EventEmitter, subscribe, Unsubscriber
• Асинхронность: wait, createTimeout, createInterval, createAnimationFrame
• Объекты и массивы: merge, without, extend-подобная логика, get по пути
• Строки: half, halfLast — разбиение по разделителю
• Прочее: noop, getUniqId, tryJsonParse, провайдеры (queue, template, router и др.)

Точный список экспортов — в src/index.ts. Подробное API — в сгенерированной документации (npm run docs).

Публичное API (экспортируется из src/index.ts)

Утилиты для DOM и событий

• attachEvent (attachEvent.ts): безопасная подписка на DOM-событие с возвратом функции отписки.
• EventEmitter (EventEmitter/): типизированный emitter с методами subscribe, once, clear, destroy.
• subscribe (subscribe.ts): утилита для добавления/удаления слушателей в произвольную коллекцию.
• Unsubscriber (Unsubscriber/): агрегатор отписок (add, unsubscribe), удобен для сборки всех unsubscribe‑функций.
• noop (noop.ts): пустая функция, часто используется как дефолтный колбэк.

Таймеры и асинхронность

• wait (wait.ts): Promise, который резолвится через указанный timeout, с опциональным значением.
• createTimeout (createTimeout.ts): обёртка над setTimeout, возвращает функцию отмены.
• createInterval (createInterval.ts): реализация интервала на базе setTimeout с контролем жизненного цикла и отменой.
• createAnimationFrame (createAnimationFrame.ts): loop на requestAnimationFrame с учётом накопленного времени.
• queueProvider (queueProvider.ts): последовательная очередь выполнения асинхронных задач (одна задача за раз).
• sendingQueue (sendingQueue.ts): очередь промисов с аккумуляцией ошибок и методом drain() для ожидания завершения всех.

URL, роутинг и HTTP‑окружение

• urlParse (urlParse.ts): низкоуровневый разбор URL в богатую структуру (TUrlProps), включая query, hash, child.
• urlExtend (urlExtend.ts): комбинирование base URL и частичных структур URL (TUrlOptions), для модификации query/path.
• unparam (unparam.ts): разбор query‑строки в объект (в т.ч. вложенные структуры и массивы по скобочной нотации).
• routeParseProvider (routeParseProvider.ts): генератор regexp+маппера по route‑шаблону (используется в routerProvider).
• regexpMapperProvider (regexpMapperProvider.ts): привязка regexp exec к мапперу значений (в том числе для роутинга).
• routerProvider (routerProvider.ts): сложный роутер поверх history/store и React‑компонентов (Link, Router и т.п.).
• rpc (rpc/): семейство модулей для RPC‑взаимодействия (кодирование сообщений, клиент, пул клиентов, browser/node адаптеры).

Шаблоны и текст

• templateProvider (templateProvider.ts): mini‑template движок {{expr}} по объекту‑scope (с templatePartsJoin под капотом).
• templatePartsJoin (templatePartsJoin.ts): композиция набора функций‑частей шаблона в одну функцию.
• convertToBreakLineHTML (convertToBreakLineHTML.ts): преобразование текста с \n в HTML со span/br и экранированием </>.
• formatTime (formatTime.ts): форматирование дат по маске, плюс вспомогательные normalizeDate, getData.
• dateToUTCString (dateToUTCString.ts): компактный UTC‑строковый формат YYYYMMDDThhmmssZ.
• withoutEmpty (withoutEmpty.ts): очистка структуры от null / undefined / пустых строк (с контролем глубины).

Объекты и коллекции

• merge (merge.ts): семантический merge коллекции значений (массив или одиночное значение) в одно значение/объект.
• mapperProvider (mapperProvider.ts): маппер [values] -> {keys: values[i]} с опциональным dst.
• pushArray (pushArray.ts): эффективная конкатенация array‑like в массив.
• reduce / reduceEach / reduceIn (reduce/): синхронный reduce для массивов/array‑like и объектов, с выбором стратегии по типу коллекции или флагу hasArray.
• without (without.ts): копия объекта без указанных ключей.
• queueProvider / sendingQueue: см. раздел «Таймеры и асинхронность».

Базовые утилиты

• half (half.ts): разбиение строки на две части по разделителю (первая/последняя позиция).
• tryJsonParse (tryJsonParse.ts): безопасный JSON.parse с возвратом исходного значения при ошибке.
• getUniqId (getUniqId.ts): генерация уникального строкового ID с опциональным префиксом.

Хранилища и cookie

• localStorageProvider (localStorageProvider.ts): адаптер под localStorage (с единым интерфейсом хранения).
• cookieStorageProvider (cookieStorageProvider.ts): адаптер под cookie‑хранилище с тем же интерфейсом.

Событийная модель и коммуникация

• EventEmitter / Unsubscriber / subscribe / attachEvent / noop / wait / queueProvider / sendingQueue — используются как фундамент для routerProvider, rpc, JSONP‑запросов и прочих high‑level модулей.

Тематические группы (расширенный обзор)

Ниже перечислены важные модули, в том числе не экспортируемые напрямую из src/index.ts, но активно используемые в коде.

1. Работа со строками

• half / halfLast: разбиение строки по разделителю (первое/последнее вхождение).
• trim: обрезка пробелов по краям.
• toLower / toUpper / lowerFirst / upperFirst: регистровые преобразования.
• scopeSplit / scopeJoin: парные утилиты для разбиения строки на иерархию «областей» по паре токенов (например, скобок) и обратной сборки этой структуры в строку.
• escapeRegExp: экранирование специальных символов для безопасной вставки в RegExp.
• repeat: повторение строки N раз (polyfill‑дружественно).
• joinProvider / joinOnly / joinComma / joinSpace: различные стратегии склейки массивов строк.
• kebabToCamelCase / snakeToCamelCase / camelToKebabCase / camelToSnakeCase / camelToDelimiterCase: преобразования регистров и разделителей в идентификаторах.
• convertToBreakLineHTML: см. выше, шаблоны и текст.

2. Объекты и коллекции (общие утилиты)

• extend / extendDepth / extendIfEmpty / extendOwn: различные варианты shallow/deep merge объектов.
• merge / complement: высокоуровневые стратегии слияния коллекций значений и объектов (см. также CRITICAL.md).
• set / get / baseSet / getBase / getWithContext: установка и получение значений по путям.
• without / withoutEmpty / toPlainFields / values / keys / entries / fromPairs: извлечение и фильтрация полей.
• pick / remove / removeByIndex / removeOf / addOf: выбор/удаление полей и элементов.
• indexOf / includes / startsWith / last / some / every / find / findIndex / findIndexLast: универсальные операции поиска по коллекции/строке.
• size: количество перечислимых значений.

3. Проверка типов (src/is/)

Основные проверки:

• isArray / isArrayLike / isCollection: массивы и коллекции.
• isObject / isObjectLike / isPlainObject: различные уровни «объектности».
• isString / isNumber / isBoolean / isSafeNumber / isInteger / isLength / isIndex: числовые и строковые типы.
• isEmpty: пустой объект.
• isRegExp / isDate / isFunction / isPromise / isFormData / isBlob / isBuffer / isArrayBuffer: специфические типы.
• isEmail / isPhone / isHttpUrl / isASCII / isHash: валидация строк по формату.

4. Асинхронные утилиты (src/async/)

• loopAsync (async/loop.ts): общий цикл while(checkFn) { await statementFn }.
• async/reduce / async/reduceEach: асинхронный reduce для массивов и объектов.
• async/map / async/filter / async/find / ... (и их parallel‑варианты): параллельные/последовательные обходы коллекций с async‑итераторами.
• withDelay / withReDelay / withDefer / delay: отложенное выполнение и повторные попытки.

5. Browser‑утилиты (src/browser/)

• ready / readyProvider: DOM ready для текущего окна/произвольного объекта window.
• jsonpRequest: JSONP‑обёртка с автоматической очисткой script‑тега и callback‑имени.
• getImageByUrl / getImageNaturalSizeByUrl / getDataLink / download: загрузка и подготовка ресурсов (картинки, blob‑ссылки).
• wsAsyncRequestProvider / wsSeriesRequestProvider / wsConnect: вспомогательные модули для работы с WebSocket‑запросами.

6. Node‑утилиты (src/node/)

• node/file/readUnopened / readSlice: чтение файлов по частям и без полного открытия.
• node/jsonl/: чтение/запись JSONL (JSON Lines) файлов, трансформы (TransformTo, TransformFrom), промифицированные версии.
• node/searchFiles/: обход файловой системы по маскам, searchFiles/index.ts возвращает список путей.

7. JSONL и потоковые форматы (src/jsonl/)

• stringify / parse: сериализация/десериализация JSONL.
• ProviderOfTransformFrom / ProviderOfTransformTo: фабрики stream‑трансформов.

8. RPC (src/rpc/)

• types.ts: типы сообщений (агент, тип RPC, форматы call/result/subCall/event/dispatch).
• RpcCoder: кодирование/декодирование полезной нагрузки.
• RpcClient / RpcClientPool / RpcConnect: высокоуровневые клиенты и пул клиентов.
• browser.ts / node.ts: адаптеры под среду исполнения.

9. Router (src/routerProvider.ts)

Высокоуровневый модуль, объединяющий:

• разбор/сборку URL (urlParse, urlExtend),
• сопоставление маршрутов (routeParseProvider, regexpMapperProvider),
• историю навигации (совместно с store),
• блокировки навигации (lock‑watchers),
• React‑компоненты для ссылок и роутера (TLinkProps, TRouteProps и др.).

Связь с CRITICAL.md

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

• CRITICAL.md — обязательно посмотри перед изменениями в:
  • routeParseProvider.ts
  • regexpMapperProvider.ts
  • set.ts, push.ts, slice.ts, concat.ts
  • reduce.ts
  • routerProvider.ts, rpc/*