inray 0.0.7 → 0.0.9

package/README.md

@@ -9,7 +9,7 @@ Inray - all-in-one инструментарий для разработки **No
 - [Текущий состав SDK](#текущий-состав-sdk)
 - [Обновления и версионирование](#обновления-и-версионирование)
 - [Документация](#документация-и-примеры-использования)
-- [Совместимость c Runtime](#совместимость-c-runtime)
+- [Совместимость](#совместимость)
 - [Лицензирование](#лицензирование)
 - [Благодарность](#благодарность)
 
@@ -91,6 +91,9 @@ Inray - all-in-one инструментарий для разработки **No
 | Различные инструменты и вспомогательные функции общего назначения | /utils                              | <span style="color:blue">III</span> | -                                                                                                                                                                                              |                   |
 | Кеширование                                                       | /caching                            | <span style="color:blue">III</span> | [cache-manager (и его части)](https://cacheable.org/)                                                                                                                                          |                   |
 | Обработка аргументов командной строки (CLI)                       | /cli                                | <span style="color:green">II</span> | [commander.js](https://github.com/tj/commander.js)                                                                                                                                             |                   |
+| Функции рандомизации                                              | /random                             | <span style="color:green">II</span> | [@std/random](https://jsr.io/@std/random/doc)                                                                                                                                                  |                   |
+| Функции для работы с SemVer                                       | /semver                             | <span style="color:green">II</span> | [@std/semver](https://jsr.io/@std/semver/doc)                                                                                                                                                  |                   |
+| Дополнительные функции для работы с текстом                       | /text                               | <span style="color:green">II</span> | [@std/text](https://jsr.io/@std/text/doc)                                                                                                                                                      |                   |
 
 \* _уровень может отображать как итог, так и процесс_
 
@@ -121,103 +124,560 @@ In progress 🛠️...
 
 ## Документация и примеры использования
 
-In progress 🛠️...
+Краткий обзор публичного API. Импорт - через namespace `inray/...`.
 
 ### inray/async - асинхронные функции
 
-In progress 🛠️...
+Вспомогательные функции для промисов и async-итераторов:
+
+- `delay` - пауза
+- `deadline` - таймаут для Promise
+- `abortable` (отменяемый через `AbortSignal`)
+- `retry` (повторы с [backoff](https://en.wikipedia.org/wiki/Exponential_backoff))
+- `debounce`
+- `poll` - ожидание условия
+- `pooledMap` - пул параллельных задач
+- `tee` - разветвление async-итератора (gen -> branch1, branch2...
+- `MuxAsyncIterator` - мультиплекс нескольких итераторов
+- `Channel` - канал send/receive (ну или producer/consumer)
+- `allKeyed` / `allSettledKeyed` resolve словаря промисов по ключам (аналог `Promise.all` для record)
+- `Lazy` - ленивая однократная инициализация значения
+
+```ts
+import { delay, retry, allKeyed } from 'inray/async';
+
+await delay(100);
+
+const user = await retry(() => fetch('/api/user').then((r) => r.json()), { maxAttempts: 3 });
+
+const { posts, comments } = await allKeyed({
+  posts: fetch('/api/posts').then((r) => r.json()),
+  comments: fetch('/api/comments').then((r) => r.json())
+});
+```
 
 ### inray/bytes - работа с байтами
 
-In progress 🛠️...
+Операции над `Uint8Array`:
+
+- `concat` склеивает байты
+- `copy` копирует в destination со смещением
+- `repeat` повторяет байты
+- `equals` сравнивает байты
+- плюс функции поиска и префиксы/суффиксы (как у строк) - `indexOfNeedle`, `lastIndexOfNeedle`, `includesNeedle`, `startsWith`, `endsWith`
+
+```ts
+import { concat, indexOfNeedle, endsWith } from 'inray/bytes';
+
+const a = new Uint8Array([0, 1, 2]);
+const b = new Uint8Array([3, 4, 5]);
+const c = concat([a, b]); // Uint8Array([0, 1, 2, 3, 4, 5])
+
+indexOfNeedle(c, new Uint8Array([2, 3])); // 2
+endsWith(c, b); // true
+```
 
 ### inray/caching - кеширование
 
-In progress 🛠️...
+_Оригинальная библиотека - cache-manager_
+
+`createCache` создаёт многослойный кеш _Cache_ (по умолчанию в памяти, как и в оригинальной библиотеке - инстанс `Keyv`)
+
+`Cache` предоставляет основные методы для управления данными - `get` / `mget`, `set` / `mset`, `del` / `mdel`, `ttl`, `clear`, `wrap`, `on` / `off` (события), `disconnect`, `cacheId`, `stores`
+
+Так-же предоставляется возможность использование внешнего хранилища, через реализацию `KeyvAdapter`
+
+Как и в оригинальной библиотеке _cache-manaher_ низкоуровневый key-value (`Keyv`) доступен отдельно из `inray/caching/keyv`
+
+```ts
+import { createCache } from 'inray/caching';
+
+const cache = createCache({ ttl: 60_000 });
+
+await cache.set('user:1', { name: 'Bob' });
+const bob = await cache.get<{ name: string }>('user:1');
+```
 
 ### inray/cli - CLI приложения
 
-In progress 🛠️...
+Это порт на TypeScript известной библиотеки [commander.js](https://github.com/tj/commander.js) версии _15.0_
+
+Добавление новой документации - In progress 🛠️...
 
 ### inray/collections - коллекции и вспомогательные функции для работы с итерируемыми объектами
 
-In progress 🛠️...
+Чистые функции для массивов и объектов (в духе Kotlin Collections / Lodash).
+
+Группировка и индексирование - `aggregateGroups`, `associateBy`, `associateWith`, `reduceGroups`
+
+Выбор и фильтрация - `distinct`, `distinctBy`, `dropWhile`, `dropLastWhile`, `takeWhile`, `takeLastWhile`, `filterEntries`, `filterKeys`, `filterValues`, `findSingle`, `firstNotNullishOf`, `includesValue`, `omit`, `pick`, `withoutAll`
+
+Преобразования - `chunk`, `mapEntries`, `mapKeys`, `mapValues`, `mapNotNullish`, `invert`, `invertBy`, `partition`, `partitionEntries`, `unzip`, `zip`, `interleave`, `slidingWindows`, `permutations`, `joinToString`, `runningReduce`, `deepMerge`, `sortBy`, `sample`
+
+Множества и агрегация - `intersect`, `union`, `maxBy`, `maxOf`, `maxWith`, `minBy`, `minOf`, `minWith`, `sumOf`
+
+```ts
+import { intersect, pick, chunk } from 'inray/collections';
+
+intersect(['Cooking', 'Music', 'Hiking'], ['Music', 'Tennis', 'Cooking']);
+// ["Cooking", "Music"]
+
+pick({ name: 'Lulu', age: 3, breed: 'Ragdoll' }, ['name', 'breed']);
+// { name: "Lulu", breed: "Ragdoll" }
+
+chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+```
 
 ### inray/csv - работа с CSV-файлами
 
-In progress 🛠️...
+Парсинг и сериализация CSV:
+
+- `parse` читает строку в массив массивов или объектов (`skipFirstRow`, `columns`, `separator`, `comment`)
+- `stringify` пишет данные обратно в CSV
+- для больших файлов - возможно использование потоков - `CsvParseStream` и `CsvStringifyStream`
+
+```ts
+import { parse, stringify } from 'inray/csv';
+
+parse('a,b,c\nd,e,f', { skipFirstRow: true });
+// [{ a: "d", b: "e", c: "f" }]
+
+stringify(
+  [
+    { name: 'john', age: '30' },
+    { name: 'mary', age: '25' }
+  ],
+  { columns: ['name', 'age'] }
+);
+// "name,age\r\njohn,30\r\nmary,25\r\n"
+```
+
+```ts
+import { ReadableStream } from 'node:stream/web';
+import { CsvParseStream } from 'inray/csv';
+
+const source = ReadableStream.from(['name,age\n', 'john,30\n', 'mary,25\n']);
+const records = await Array.fromAsync(source.pipeThrough(new CsvParseStream({ skipFirstRow: true })));
+```
 
 ### inray/data-structures - обобщенные структуры данных
 
-In progress 🛠️...
+Некоторые структуры для алгоритмов:
+
+- `BinarySearchTree` (поиск/вставка/удаление, `min`/`max`)
+- сбалансированное `RedBlackTree`
+- приоритетная очередь `BinaryHeap` (`push`/`pop`/`peek`)
+- двусторонняя очередь `Deque`
+
+Для задания порядка используются специальные компараторы - `ascend` и `descend`
+
+```ts
+import { BinarySearchTree, BinaryHeap, ascend } from 'inray/data-structures';
+
+const tree = new BinarySearchTree<number>();
+[3, 10, 4, 1, 7].forEach((v) => tree.insert(v));
+tree.min(); // 1
+tree.find(7); // 7
+[...tree]; // [1, 3, 4, 7, 10]
+
+const heap = new BinaryHeap<number>(ascend);
+heap.push(4, 1, 3);
+heap.peek(); // 1
+```
 
 ### inray/date-fns - работа с датой и временем
 
-In progress 🛠️...
+Поставка легендарной библиотеки для работы с датой и временем - [_date-fns_](https://date-fns.org/) (версии 4.4.0)
+
+Добавление новой документации - In progress 🛠️...
 
 ### inray/db, inray/db/postgres, inray/db-migrator - работа с БД
 
-In progress 🛠️...
+`inray/db/postgres` - драйвер [postgres.js](https://github.com/porsager/postgres). Исходный код драйвера (JS, ESM) поставляется как есть (единственный такой в inray)
+
+`inray/db-migrator` - мигратор применяет SQL/TS-миграции. CLI доступен через `inray-migrator`
+
+Добавление новой документации - In progress 🛠️...
+
+```ts
+import postgres from 'inray/db/postgres';
+
+const sql = postgres({ host: 'localhost', database: 'app', user: 'app' });
+const [user] = await sql<{ id: number; name: string }[]>`
+  select * from users where id = ${1}
+`;
+await sql.end();
+```
 
 ### inray/encoding - кодирование и декодирование данных
 
-In progress 🛠️...
+Кодирование и декодирование некоторых популярных форматов:
+
+- `encodeHex` / `decodeHex`
+- `encodeBase32` / `decodeBase32`
+- `encodeBase58` / `decodeBase58`
+- `encodeBase64` / `decodeBase64` и URL-safe версия `encodeBase64Url` / `decodeBase64Url`
+- `encodeAscii85` / `decodeAscii85`
+- Protobuf-подобные varint: `encodeVarint`, `decodeVarint`, `decodeVarint32`
+- лимиты - `MaxUint64`, `MaxVarintLen32`, `MaxVarintLen64`
+
+```ts
+import { encodeHex, decodeHex, encodeBase64Url, encodeVarint } from 'inray/encoding';
+
+encodeHex('Hello world!'); // "48656c6c6f20776f726c6421"
+new TextDecoder().decode(decodeHex('48656c6c6f20776f726c6421')); // "Hello world!"
+
+encodeBase64Url('ice creams'); // "aWNlIGNyZWFtcw" - URL-safe
+encodeVarint(9601n); // [Uint8Array([129, 75]), 2]
+```
 
 ### inray/fmt/bytes, inray/fmt/colors, inray/fmt/duration - функции строкового представления различных данных
 
-In progress 🛠️...
+- `inray/fmt/bytes`, `format` превращает число байт в человекочитаемую строку (`1.34 kB`), с различными опцииями
+- `inray/fmt/duration`, `format` переводит миллисекунды в длительность (`"1m 39s 674ms"`)
+- `inray/fmt/colors`, ANSI-цвета и стили
+
+```ts
+import { format as formatBytes } from 'inray/fmt/bytes';
+import { format as formatDuration } from 'inray/fmt/duration';
+import { bold, red, bgBlue } from 'inray/fmt/colors';
+
+formatBytes(1337); // "1.34 kB"
+formatDuration(99674, { ignoreZero: true }); // "1m 39s 674ms"
+console.log(bgBlue(bold(red('Hello, World!'))));
+```
 
 ### inray/hono - веб-фреймворк Hono и его части
 
-In progress 🛠️...
+[Hono](https://hono.dev/docs/) - фреймворк построенный на веб-стандартах для реализации. Версия 4.13.5
 
-### inray/jose - набор криптографический функций в рамках библиотеки jose
+Добавление новой документации - In progress 🛠️...
 
-In progress 🛠️...
+### inray/jose - криптография
+
+Библиотека криптографических функций [jose](https://github.com/panva/jose). Поставляется как есть, версия 6.2.8
+
+Добавление новой документации - In progress 🛠️...
 
 ### inray/json - дополнительные хелперы для работы с JSON
 
-In progress 🛠️...
+Доп. функции для работы с JSON/NDJSON:
+
+- `JsonParseStream` преобразует поток в объекты,
+- `JsonStringifyStream` сериализует объекты в поток (NDJSON)
+- `ConcatenatedJsonParseStream` читает склеенные JSON-значения без разделителей
+
+```ts
+import { ReadableStream } from 'node:stream/web';
+import { JsonStringifyStream, canonicalize } from 'inray/json';
+
+const encoded = ReadableStream.from([{ foo: 'bar' }, { baz: 100 }]).pipeThrough(new JsonStringifyStream());
+await Array.fromAsync(encoded); // ['{"foo":"bar"}\n', '{"baz":100}\n']
+
+canonicalize({ a: 1, A: 2, '1': 3 }); // '{"1":3,"A":2,"a":1}'
+```
 
 ### inray/jsonc - парсинг JSONC файлов
 
-In progress 🛠️...
+Единственная функция - `parse` позволяет читает JSON with Comments (включающие комментарии `//` и `/* */`, висячие запятые)
+
+Сериализация JSONC не поддерживается
+
+```ts
+import { parse } from 'inray/jsonc';
+
+parse('{"foo": "bar", } // comment'); // { foo: "bar" }
+parse('{"foo": "bar", } /* block */'); // { foo: "bar" }
+```
 
 ### inray/logtape - логгер logtape и его части
 
-In progress 🛠️...
+Продвинутый логгер [logTape](https://logtape.org/). Предоставляемая версия - 2.3.2
+
+Включает пакеты для конфигурации и направления потока логов:
+
+- logtape/config - конфигурация
+- logtape/file - направление в файлы
+- logtape/pretty - управление внешним видом
+- logtape/redaction - скрытие данных внутри лога
+- logtape/syslog - для системных логов (RFC 5424)
+
+Добавление новой документации - In progress 🛠️...
 
 ### inray/media-types - работа с "content-type" и MIME
 
-In progress 🛠️...
+MIME-утилиты:
+
+- `contentType` - полный `Content-Type` по расширению или типу
+- `parseMediaType` и `formatMediaType` - разбор и сборка заголовка
+
+```ts
+import { contentType, allExtensions, getCharset, parseMediaType } from 'inray/media-types';
+
+allExtensions('application/json'); // ["json", "map"]
+contentType('.json'); // "application/json; charset=UTF-8"
+getCharset('text/plain'); // "UTF-8"
+parseMediaType('text/html; charset=UTF-8'); // ["text/html", { charset: "UTF-8" }]
+```
 
 ### inray/node-cron - задачи по расписанию в рамках библиотеки node-cron
 
-In progress 🛠️...
+Форк библиотеки [node-cron](https://www.nodecron.com/), версии _4.6.0_. Планировщик cron-задач, API сохранён, однако
+в будущем библиотека претерпит изменения
+
+```ts
+import cron, { validate } from 'inray/node-cron';
+
+validate('*/5 * * * * *'); // true
+
+const task = cron.schedule('*/5 * * * * *', () => {
+  console.log('every 5 seconds');
+});
+
+await cron.shutdown();
+```
 
 ### inray/phonenumbers - парсинг и валидация телефонных номеров
 
-In progress 🛠️...
+Форк библиотеки [libphonenumber.js](https://gitlab.com/catamphetamine/libphonenumber-js) переписанный на TypeScript (с существенным рефакторингом, в будущем - ещё бОльшим)
+Парсинг E.164 / национальных номеров (libphonenumber):
+
+- `parsePhoneNumber` (без throw)
+- `parsePhoneNumberWithError`
+- проверки `isValidPhoneNumber`, `isPossiblePhoneNumber`, `validatePhoneNumberLength`
+- поиск в тексте - `findPhoneNumbersInText`, `searchPhoneNumbersInText`, `PhoneNumberMatcher`
+- метаданные стран: `getCountries`, `isSupportedCountry`, `getCountryCallingCode`, `getExtPrefix`, `getExampleNumber`
+- неполный ввод: `parseIncompletePhoneNumber`, `parsePhoneNumberCharacter`, `parseDigits`
+- работа с RFC 3966 - `parseRFC3966` / `formatRFC3966`
+- объект `PhoneNumber` содержит методы `isValid`, `isPossible`, `getType`, `format`, `formatNational`, `formatInternational`
+
+```ts
+import { parsePhoneNumber, isValidPhoneNumber, findPhoneNumbersInText } from 'inray/phonenumbers';
+
+isValidPhoneNumber('+12133734253'); // true
+
+const phone = parsePhoneNumber('8 (800) 555-35-35', { defaultCountry: 'RU' });
+phone?.formatInternational(); // "+7 800 555 35 35"
+phone?.country; // "RU"
+
+findPhoneNumbersInText('Call +1-213-373-4253 tomorrow');
+```
+
+### inray/random - функции рандомизации
+
+Генерация случайных значений с опциональным [PRNG](https://en.wikipedia.org/wiki/Pseudorandom_number_generator):
+
+- `randomBetween`
+- `randomIntegerBetween`
+- `sample` - случайный элемент массива
+- `shuffle` - перетасовать массив
+
+```ts
+import { randomIntegerBetween, randomSeeded, shuffle } from 'inray/random';
+
+const prng = randomSeeded(1n);
+randomIntegerBetween(1, 10, { prng }); // 3 - стабильно для того же seed
+
+shuffle(['a', 'b', 'c'], { prng });
+```
+
+### inray/semver - работа с SemVer
+
+Функции для работы SemVer 2.0 (обозначениями версионирования):
+
+- `parse` / `tryParse` / `canParse`, `format` - конкретная версия
+- `parseRange` / `tryParseRange` / `formatRange` / `isRange` - диапазоны версий
+- `compare`, `equals`, `notEquals`, `greaterThan`, `greaterOrEqual`, `lessThan`, `lessOrEqual`, `difference` - сравнение версий
+- `satisfies`, `maxSatisfying`, `minSatisfying`, `rangeIntersects`, `greaterThanRange`, `lessThanRange` - проверки диапазона
+- `increment` - повышение версии (bump)
+- `isSemVer` - проверка объекта (является-ли оно SemVer)
+
+```ts
+import { parse, parseRange, greaterThan, satisfies, increment, format } from 'inray/semver';
+
+const v = parse('1.2.3');
+format(v); // "1.2.3"
+greaterThan(parse('1.2.3'), parse('9.8.7')); // false
+
+const range = parseRange('^1.2.3');
+satisfies(parse('1.4.0'), range); // true
+format(increment(v, 'minor')); // "1.3.0"
+```
 
 ### inray/streams - работа с потоками (Stream)
 
-In progress 🛠️...
+Использовать с осторожностью ⚠️, нестабильная реализация (оригинальная библиотека [@std/streams](https://jsr.io/@std/streams))
+
+Утилиты Web-совместимых [потоков](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) (Streams, `node:stream/web`)
+
+- `concatReadableStreams`, `mergeReadableStreams`, `zipReadableStreams`, `earlyZipReadableStreams`
+- `TextLineStream`, `TextDelimiterStream`, `DelimiterStream`, `ByteSliceStream`, `LimitedTransformStream`, `LimitedBytesTransformStream`, `toTransformStream`
+- `toText`, `toJson`, `toBytes`, `toArrayBuffer`, `toBlob`
+- Буфер произвольного доступа - `Buffer`
+
+```ts
+import { ReadableStream } from 'node:stream/web';
+import { toText, TextLineStream } from 'inray/streams';
+
+const text = await toText(ReadableStream.from(['Hello, ', 'world!']));
+// "Hello, world!"
+
+const lines = ReadableStream.from(['a\nb\n', 'c\n']).pipeThrough(new TextLineStream());
+await Array.fromAsync(lines); // ["a", "b", "c"]
+```
+
+### inray/text - работа с текстом
+
+Различные функции для работы с текстом:
+
+- `toCamelCase`, `toPascalCase`, `toKebabCase`, `toSnakeCase` - преобразование к соответствующему регистру
+- `levenshteinDistance`, `closestString`, `compareSimilarity`, `wordSimilaritySort` - проверка схожести строк
+- `truncate` (`position`: `end` / `middle` / `start`) - отсечение
+
+```ts
+import { toCamelCase, compareSimilarity, truncate } from 'inray/text';
+
+toCamelCase('snake_case'); // "snakeCase"
+
+['hi', 'help', 'hello'].sort(compareSimilarity('hep'));
+// ["help", "hi", "hello"]
+
+truncate('very long text', 10); // "very lon…"
+```
 
 ### inray/unidecode - транслитерация строк
 
-In progress 🛠️...
+Функция транслитерации `unidecode` - переводит Unicode в ближайший ASCII
+
+```ts
+import { unidecode } from 'inray/unidecode';
+
+unidecode('étude'); // "etude"
+unidecode('北京'); // "Bei Jing "
+unidecode('Æneid'); // "AEneid"
+```
 
 ### inray/utils - вспомогательные функции, классы, типы и валидаторы общего назначения
 
-In progress 🛠️...
+Общие хелперы:
 
-### inray/yaml - работа с YAML-файлами в рамках библиотеки yaml
+- `createCid` - (детерминированный id из SHA-256)
+- `generateDigitCode` - простая генерация числового кода
+- `addOptionalFields` - перенос опциональных (?) полей из одного объекта в другой (с возможностью переименования)
+- `objectToQueryParams` - преобразование объекта в Query-совместимую строку
+- `getUrlDomain` - получение домена URL
+- `getFilenameFromExternalUrl` - получения названия файла из ссылки
+- `splitForPagination` - разбитие массива на пагинацию
+- `HTTP_METHODS`, `HttpStatusText` - HTTP хелперы
+- `mkdirs` / `mkdirsSync` - последовательное создание директорий
+- `totalist` / `totalistSync` - последовательный обход дерева
 
-In progress 🛠️...
+Классы:
 
-## Совместимость c Runtime
+- `TaskQueue` - последовательное выполнение промисов
+- `SequentialCompensation` + `CompensatedOperation` (мини-saga с возможностью отката)
 
-In progress 🛠️...
+Простые но часто используемые типы - `Serial`, `SortDirection` / `SortDirections`
+
+Валидаторы (`inray/utils/validation`):
+
+- предикаты: `isEmail`, `isUuid`, `isUuidArraySafe`, `isPositiveInteger`, `isNotEmptyString`, `isEmptyObject`, `isValidFileName`, `isValidUrlLike` / `urlPattern`, `inRangeOfMaxInt32`.
+- Valibot-схемы: `vEnvBoolean`, `vEnvBooleanOrUndefined`, `vEnvLogLevel`, `vOmniBoolean`, `vQueryBoolean`, `vQueryEmailArray`, `vQueryPositiveNumberArray`, `vQueryStringifiedEnumArray`, `vQueryUuidArray`, `vISO8601DateTime` / `vISO8601DateTimeOptional` / `vISO8601DateTimeNullableOptional`, `vLatinInput`.
+
+```ts
+import { createCid, objectToQueryParams, TaskQueue } from 'inray/utils';
+import { isEmail, isUuid } from 'inray/utils/validation';
+
+createCid({ base: 'user:42', prefix: 'usr' }); // "usr_<16 hex из SHA-256>"
+objectToQueryParams({ q: 'test', page: '1' }); // "?q=test&page=1"
+
+isEmail('jane@example.com'); // "jane@example.com"
+isUuid('not-a-uuid'); // false
+
+const queue = new TaskQueue('jobs');
+await queue.run(() => Promise.resolve(1));
+```
+
+### inray/valibot - валидация
+
+Библиотека валидации - [valibot](https://valibot.dev/), версия 1.4.2
+
+Поставляется практически без изменений включая части [to-Json-Schema](https://valibot.dev/guides/json-schema/) и [i18n](https://valibot.dev/guides/internationalization/)
+
+### inray/yaml - работа с YAML-файлами
+
+Оригинальная библиотека [yaml](https://eemeli.org/yaml/#yaml), версия 3.0.0-rc, YAML 1.1/1.2
+
+```ts
+import { parse, stringify } from 'inray/yaml';
+
+parse('[ true, false, maybe, null ]');
+// [true, false, "maybe", null]
+
+stringify({ number: 3, plain: 'string', block: 'two\nlines\n' });
+// number: 3
+// plain: string
+// block: >
+//   two
+//
+//   lines
+```
+
+## Совместимость
+
+Целевой платформой Inray является [Node.js](https://nodejs.org/en)
+
+Минимальная рекомендуемая версия - 22.18
+
+Код SDK написан в режиме type-erasure и компилируется в практически аналогичный ECMAScript 2022 (то есть отдельные модули могут быть совместимы с Node.js 18 и 20)
+
+Каждый* модуль Inray содержит тестовый набор, для тестирования используется [vitest](https://vitest.dev/). В сумме SDK содержит 17 200 тестов
+
+Совместимость с версией Node.js определяется следующим образом:
+
+- с помощью _nvm_ устанавливается соотв. версия Node.js
+- запускаются все тесты - _npm run test_
+- запускается отдельный скрипт проверки импортов уже скомпилированного JavaScript - _npm run test:smoke-exports_
+
+| Версия Node.js   | Совместимость с inray | Комментарий                                               |
+| :--------------- | :-------------------: | :-------------------------------------------------------- |
+| 22.18.0 (22 LTS) |          ✅           | 1 из 17200 тестов несовместим по коду самого теста        |
+| 23.11.1          |          ✅           |                                                           |
+| 24.21.0 (24 LTS) |          ✅           |                                                           |
+| 25.9.0           |          ✅           |                                                           |
+| 26.11.1          |          ✅           | в 5 из 3181 тестах Hono замечена разница в выбросе ошибок |
+
+\** - кроме _db/postgres_, _db/migrator_ и _utils_ - разработка тестов в процессе 🛠️...
+
+### Совместимость с браузерами
+
+Некоторые модули Inray могут использоваться в клиентских приложениях. Это особенно важно при разработке внутри монорепозиториев, где зависимости проекта "шерятся" между backend и frontend - приложениями
+
+Совместимость модуля inray браузерами определяется следующим образом:
+
+- сам модуль _логически_ считается совместимым если в нём - нет импортов Node-API, не используются Node.js специфичные вещи, и сам модуль по своей сути "изоморфный" (либо функционально чистый)
+- для подтверждения этой гипотезы тестовые наборы модуля дополнительно запускаются в двух конфигурациях vitest - [jsdom](https://github.com/jsdom/jsdom) и [happy-dom](https://github.com/capricorn86/happy-dom)
+- в будущем в обязательно порядке будут добавлены тесты [_playwright_](https://playwright.dev/) (либо аналога) - для настоящего инстанциирования chromium, firefox и т.д., т.к. jsdom и happy-dom лишь эмулируют части браузера поверх Node.js
+- при интерпретации результатов учитываются ограничения эмуляторов _jsdom_, _happy-dom_ - то есть наличие ошибки при прохождении теста, не означает несовместимость с браузером
+
+| Модуль Inray       | jsdom | happy-dom | Комментарий                                                                                                  |
+| :----------------- | :---: | :-------: | :----------------------------------------------------------------------------------------------------------- |
+| inray/async        |  ⚠️   |    ✅     | jsdom: разница в классах DOMException на проверках instanceof                                                |
+| inray/bytes        |  ✅   |    ✅     |                                                                                                              |
+| inray/collections  |  ✅   |    ✅     |                                                                                                              |
+| inray/data         |  ✅   |    ✅     |                                                                                                              |
+| inray/date         |  ✅   |    ✅     |                                                                                                              |
+| inray/encoding     |  ⚠️   |    ✅     | jsdom: разница в классах Uint8Array на проверках instanceof. <br> У jsdom нет ArrayBuffer.prototype.transfer |
+| inray/jsonc        |  ✅   |    ✅     |                                                                                                              |
+| inray/media_types  |  ✅   |    ✅     |                                                                                                              |
+| inray/phonenumbers |  ✅   |    ✅     |                                                                                                              |
+| inray/random       |  ✅   |    ✅     |                                                                                                              |
+| inray/semver       |  ✅   |    ✅     |                                                                                                              |
+| inray/text         |  ✅   |    ✅     |                                                                                                              |
+| inray/unidecode    |  ✅   |    ✅     |                                                                                                              |
+| inray/valibot      |  ✅   |    ✅     |                                                                                                              |
+
+_playwright_ и версии бразуеров - in progress 🛠️...
 
 ## Лицензирование
 
@@ -247,35 +707,38 @@ PERFORMANCE OF THIS SOFTWARE.
 
 Integrated and modified external libraries:
 
-| Library name                                                                                                                              | Author                                                                                 |   License   | Version\*        | Modification level\*\* | Internal name\*\*\* |
-| :---------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :---------: | :--------------- | ---------------------- | ------------------- |
-| [valibot](https://valibot.dev/)                                                                                                           | [Fabian Hiller](https://github.com/fabian-hiller)                                      |     MIT     | **1.4.2**        | Zero or low            | same                |
-| [@valibot/i18n](https://github.com/open-circle/valibot/tree/main/packages/i18n)                                                           | [Fabian Hiller](https://github.com/fabian-hiller)                                      |     MIT     | **1.2.0**        | Zero or low            | same                |
-| [@valibot/to-json-schema](https://github.com/open-circle/valibot/tree/main/packages/to-json-schema)                                       | [Fabian Hiller](https://github.com/fabian-hiller)                                      |     MIT     | **1.7.1**        | Zero                   | same                |
-| [node-cron](https://www.nodecron.com/)                                                                                                    | [Lucas Merencia](https://github.com/merencia)                                          |     ISC     | **4.6.0**        | Zero or low            | same                |
-| [yaml](https://eemeli.org/yaml/#yaml)                                                                                                     | [Eemeli Aro](https://github.com/eemeli)                                                |     ISC     | **3.0.0-1 (RC)** | Zero or low            | same                |
-| [@std/async](https://jsr.io/@std/async)                                                                                                   | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.5.0**        | Zero or low            | same as domain      |
-| [@std/bytes](https://jsr.io/@std/bytes)                                                                                                   | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.0.6**        | Zero or low            | same as domain      |
-| [@std/collections](https://jsr.io/@std/collections)                                                                                       | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.3.0**        | Zero or low            | same as domain      |
-| [@std/csv](https://jsr.io/@std/csv)                                                                                                       | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.0.6**        | Low                    | same as domain      |
-| [@std/data-structures](https://jsr.io/@std/data-structures)                                                                               | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.1.1**        | Zero or low            | same as domain      |
-| [@std/encoding](https://jsr.io/@std/encoding)                                                                                             | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.0.11**       | Low                    | same as domain      |
-| [@std/fmt](https://jsr.io/@std/fmt)                                                                                                       | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.0.10**       | Low                    | same as domain      |
-| [@std/json](https://jsr.io/@std/json)                                                                                                     | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.1.0**        | Low                    | same as domain      |
-| [@std/jsonc](https://jsr.io/@std/jsonc)                                                                                                   | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.0.2**        | Zero or low            | same as domain      |
-| [@std/media-types](https://jsr.io/@std/media-types)                                                                                       | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.1.0**        | Zero or low            | same as domain      |
-| [@std/streams](https://jsr.io/@std/streams)                                                                                               | [Deno authors](https://github.com/denoland)                                            |     MIT     | **1.1.1**        | Low                    | same as domain      |
-| [jose](https://github.com/panva/jose)                                                                                                     | [Filip Skokan](https://github.com/panva)                                               |     MIT     | **6.2.8**        | Zero or low            | same                |
-| [date-fns](https://date-fns.org/)                                                                                                         | [Sasha Koss](https://github.com/kossnocorp)                                            |     MIT     | **4.4.0**        | Zero or low            | same                |
-| [unidecode](https://github.com/FGRibreau/node-unidecode)                                                                                  | [Francois-Guillaume Ribreau](https://fgribreau.com)                                    |     BSD     | **1.1.0**        | Average                | same                |
-| [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js)                                                                  | [Nikolay Kuchumov](https://gitlab.com/catamphetamine)                                  | MIT, Apache | **1.13.11**      | High                   | phonenumbers        |
-| [logtape](https://logtape.org/) and parts: <br> @logtape/config, @logtape/file, <br> @logtape/pretty, @logtape/redaction, @logtape/syslog | [Hong Minhee (洪 民憙)](https://github.com/dahlia)                                     |     MIT     | **2.3.2**        | Zero or low            | same                |
-| [postgres.js](https://github.com/porsager/postgres/tree/master)                                                                           | [Rasmus Porsager](https://github.com/porsager)                                         |  UNLICENSE  | **3.4.9**        | Zero                   | same                |
-| [hono](https://hono.dev/)                                                                                                                 | [Yusuke Wada](https://github.com/yusukebe)                                             |     MIT     | **4.13.5**       | Low                    | same                |
-| [@hono/node-server](https://github.com/honojs/node-server)                                                                                | [Yusuke Wada](https://github.com/yusukebe)                                             |     MIT     | **2.1.1**        | Zero or low            | same                |
-| [cache-manager](https://cacheable.org/docs/cache-manager/) and parts: keyv, @keyv/serialize, @cacheable/utils, hashery, hookified         | [Jared Wray](https://github.com/jaredwray)                                             |     MIT     | **7.2.9**        | Average                | caching             |
-| [commander.js](https://github.com/tj/commander.js)                                                                                        | [TJ Holowaychuk](https://github.com/tj)<br> [John Gee](https://github.com/shadowspawn) |     MIT     | **15.0.0**       | Average                | cli                 |
-| [ley](https://github.com/lukeed/ley) and parts: <br> mk-dirs, totalist                                                                    | [Luke Edwards](https://github.com/lukeed)                                              |     MIT     | **0.8.1**        | High                   | db-migrator         |
+| Library name                                                                                                                              | Author                                                                                          |   License   | Version\*        | Modification level\*\* | Internal name\*\*\* |
+| :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :---------: | :--------------- | ---------------------- | ------------------- |
+| [valibot](https://valibot.dev/)                                                                                                           | [Fabian Hiller](https://github.com/fabian-hiller)                                               |     MIT     | **1.4.2**        | Zero or low            | same                |
+| [@valibot/i18n](https://github.com/open-circle/valibot/tree/main/packages/i18n)                                                           | [Fabian Hiller](https://github.com/fabian-hiller)                                               |     MIT     | **1.2.0**        | Zero or low            | same                |
+| [@valibot/to-json-schema](https://github.com/open-circle/valibot/tree/main/packages/to-json-schema)                                       | [Fabian Hiller](https://github.com/fabian-hiller)                                               |     MIT     | **1.7.1**        | Zero                   | same                |
+| [node-cron](https://www.nodecron.com/)                                                                                                    | [Lucas Merencia](https://github.com/merencia)                                                   |     ISC     | **4.6.0**        | Zero or low            | same                |
+| [yaml](https://eemeli.org/yaml/#yaml)                                                                                                     | [Eemeli Aro](https://github.com/eemeli)                                                         |     ISC     | **3.0.0-1 (RC)** | Zero or low            | same                |
+| [@std/async](https://jsr.io/@std/async)                                                                                                   | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.5.0**        | Zero or low            | same as domain      |
+| [@std/bytes](https://jsr.io/@std/bytes)                                                                                                   | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.6**        | Zero or low            | same as domain      |
+| [@std/collections](https://jsr.io/@std/collections)                                                                                       | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.3.0**        | Zero or low            | same as domain      |
+| [@std/csv](https://jsr.io/@std/csv)                                                                                                       | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.6**        | Low                    | same as domain      |
+| [@std/data-structures](https://jsr.io/@std/data-structures)                                                                               | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.1.1**        | Zero or low            | same as domain      |
+| [@std/encoding](https://jsr.io/@std/encoding)                                                                                             | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.11**       | Low                    | same as domain      |
+| [@std/fmt](https://jsr.io/@std/fmt)                                                                                                       | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.10**       | Low                    | same as domain      |
+| [@std/json](https://jsr.io/@std/json)                                                                                                     | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.1.0**        | Low                    | same as domain      |
+| [@std/jsonc](https://jsr.io/@std/jsonc)                                                                                                   | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.2**        | Zero or low            | same as domain      |
+| [@std/media-types](https://jsr.io/@std/media-types)                                                                                       | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.1.0**        | Zero or low            | same as domain      |
+| [@std/streams](https://jsr.io/@std/streams)                                                                                               | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.1.1**        | Low                    | same as domain      |
+| [jose](https://github.com/panva/jose)                                                                                                     | [Filip Skokan](https://github.com/panva)                                                        |     MIT     | **6.2.8**        | Zero or low            | same                |
+| [date-fns](https://date-fns.org/)                                                                                                         | [Sasha Koss](https://github.com/kossnocorp)                                                     |     MIT     | **4.4.0**        | Zero or low            | same                |
+| [unidecode](https://github.com/FGRibreau/node-unidecode)                                                                                  | [Francois-Guillaume Ribreau](https://fgribreau.com)                                             |     BSD     | **1.1.0**        | Average                | same                |
+| [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js)                                                                  | [Nikolay Kuchumov](https://gitlab.com/catamphetamine)                                           | MIT, Apache | **1.13.11**      | High                   | phonenumbers        |
+| [logtape](https://logtape.org/) and parts: <br> @logtape/config, @logtape/file, <br> @logtape/pretty, @logtape/redaction, @logtape/syslog | [Hong Minhee (洪 民憙)](https://github.com/dahlia)                                              |     MIT     | **2.3.2**        | Zero or low            | same                |
+| [postgres.js](https://github.com/porsager/postgres/tree/master)                                                                           | [Rasmus Porsager](https://github.com/porsager)                                                  |  UNLICENSE  | **3.4.9**        | Zero                   | same                |
+| [hono](https://hono.dev/)                                                                                                                 | [Yusuke Wada](https://github.com/yusukebe)                                                      |     MIT     | **4.13.5**       | Low                    | same                |
+| [@hono/node-server](https://github.com/honojs/node-server)                                                                                | [Yusuke Wada](https://github.com/yusukebe)                                                      |     MIT     | **2.1.1**        | Zero or low            | same                |
+| [cache-manager](https://cacheable.org/docs/cache-manager/) and parts: keyv, @keyv/serialize, @cacheable/utils, hashery, hookified         | [Jared Wray](https://github.com/jaredwray)                                                      |     MIT     | **7.2.9**        | Average                | caching             |
+| [commander.js](https://github.com/tj/commander.js)                                                                                        | [TJ Holowaychuk](https://github.com/tj)<br> [John Gee](https://github.com/shadowspawn)          |     MIT     | **15.0.0**       | Average                | cli                 |
+| [ley](https://github.com/lukeed/ley) and parts: <br> mk-dirs, totalist                                                                    | [Luke Edwards](https://github.com/lukeed)                                                       |     MIT     | **0.8.1**        | High                   | db-migrator         |
+| [@std/random](https://jsr.io/@std/random)                                                                                                 | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **0.1.5**        | Zero or low            | same as domain      |
+| [@std/semver](https://jsr.io/@std/semver)                                                                                                 | [Deno authors](https://github.com/denoland)<br> [Isaac Z. Schlueter](https://github.com/isaacs) |  MIT, ISC   | **1.0.8**        | Zero or low            | same as domain      |
+| [@std/text](https://jsr.io/@std/text)                                                                                                     | [Deno authors](https://github.com/denoland)                                                     |     MIT     | **1.0.19**       | Zero or low            | same as domain      |
 
 \* - integrated version of library
 
@@ -329,3 +792,4 @@ However, sometimes integrated libraries change their original name for one or mo
 - [TJ Holowaychuk](https://github.com/tj)
 - [John Gee](https://github.com/shadowspawn)
 - [Luke Edwards](https://github.com/lukeed)
+- [Isaac Z. Schlueter](https://github.com/isaacs)