@nemigo/helpers 0.13.3 → 1.5.0

package/dist/phymath/index.js

@@ -1,62 +1,70 @@
 /**
- * Приведение -/+ 0 к 0
+ * Приведение -0 и +0 к обычному 0
+ *
+ * Если не 0, то вернётся исходное значение
  */
-export const toZero = (value) => (value === 0 ? 0 : value);
+export const normalizero = (value) => (value === 0 ? 0 : value);
 /**
  * Округляет число до заданного количества знаков после запятой
  *
- * Если переданное значение является `NaN` возвращает 0
+ * Если переданное значение является `NaN` или 0, возвращает 0
  *
- * @param {number} value - Число для округления
- * @param {number} [fraction=2] - Количество знаков после запятой
- * @returns {number} Округленное число
+ * @param value - Число для округления
+ * @param [fraction=2] - Количество знаков после запятой
+ * @param [method="math"] - Метод округления
  */
-export const toRound = (value, fraction = 2) => {
+export const round = (value, fraction = 2, method = "math") => {
     if (isNaN(value) || value === 0)
         return 0;
-    return Number(value.toFixed(fraction));
+    const factor = Math.pow(10, fraction);
+    switch (method) {
+        case "up":
+            return Math.ceil(value * factor) / factor;
+        case "down":
+            return Math.floor(value * factor) / factor;
+        default:
+            return Math.round(value * factor) / factor;
+    }
 };
 //...
 /**
  * Вычисляет сумму всех переданных аргументов
  *
- * Сумма округляется с использованием функции {@link toRound}
- *
- * @param {...number} args - Числа для суммирования
- * @returns {number} Округленная сумма переданных чисел (или 0)
+ * Для пустого массива возвращает 0
  */
-export const sum = (...args) => toRound(args.reduce((acc, v) => acc + v, 0));
+export const sum = (...args) => args.reduce((acc, value) => acc + value, 0);
 /**
  * Вычисляет произведение всех переданных аргументов
  *
- * Произведение округляется с использованием функции {@link toRound}
- *
- * @param {...number} args - Числа для перемножения.
- * @returns {number} Округленное произведение переданных чисел (или 1)
+ * Для пустого массива возвращает 1
  */
-export const mult = (...args) => toRound(args.reduce((acc, v) => acc * v, 1));
+export const mult = (...args) => args.reduce((acc, value) => acc * value, 1);
 /**
  * Ограничивает значение в заданном диапазоне [min, max]
  *
- * Если значение меньше min, вернёт min. Если больше max — вернёт max.
- * Иначе возвращает само значение без изменений.
- *
- * @param {number} v - Исходное значение для ограничения
- * @param {number} min - Нижняя граница диапазона
- * @param {number} max - Верхняя граница диапазона
- *
- * @returns {number} Значение, ограниченное диапазоном [min, max]
+ * @example
+ * ```typescript
+ * clamp(5, 0, 10); // 5
+ * clamp(-5, 0, 10); // 0
+ * clamp(15, 0, 10); // 10
+ * ```
  */
-export const clamp = (v, min, max) => Math.max(Math.min(v, max), min);
+export const clamp = (value, min, max) => Math.max(Math.min(value, max), min);
+//...
+/**
+ * Преобразует градусы в радианы
+ */
+export const toRadians = (degrees) => (degrees * Math.PI) / 180;
+/**
+ * Преобразует радианы в градусы
+ */
+export const toDegrees = (radians) => (radians * 180) / Math.PI;
 //...
-export const toRadians = (deg) => (deg * Math.PI) / 180;
 /**
  * Линейная интерполяция между двумя числами
  *
- * @param {number} a - Начальное значение
- * @param {number} b - Конечное значение
- * @param {number} t - Весовой коэффициент, определяющий пропорцию между начальным и конечным значениями. Значение должно быть в диапазоне [0, 1]
- *
- * @returns {number} Результат линейной интерполяции между a и b при коэффициенте t
+ * @param a - Начальное значение
+ * @param b - Конечное значение
+ * @param t - Весовой коэффициент, определяющий состояние пропорции между начальным и конечным значениями. Должно быть в диапазоне `[0, 1]`
  */
 export const lerp = (a, b, t) => a + (b - a) * t;

package/dist/promoter.d.ts

@@ -1,25 +1,33 @@
 import type { RID } from "./types.js";
 /**
- * Класс для создания простого механизма подписок
+ * Простой механизм подписок
  */
-export declare class Promoter<Data> {
+export declare class Promoter<E> {
     __subs: Map<RID, {
-        call: (data: Data) => void;
+        callback: (event: E) => void;
         once?: boolean;
     }>;
+    notify(event: E): void;
     /**
-     * Вызывает подписчиков
+     * @param callback - Функция подписчика
+     * @param [options] - Опции запуска
+     * @param [options.once] - Одноразовая подписка
+     * @param [options.key=Symbol()] - Ключ подписчика
+     *
+     * @returns - Функция для отмены подписки
      */
-    notify(data: Data): void;
-    /**
-     * Подписка на события
-     */
-    sub(call: (data: Data) => void, params?: {
+    subscribe(callback: (event: E) => void, options?: {
         key?: RID;
         once?: boolean;
-    }): () => boolean;
+    }): () => void;
     /**
-     * Удаляет подписчика по ключу. Если не указан, очищаются все
+     * **Если ключ не указан, очищаются все**
+     *
+     * @example
+     * ```typescript
+     * promoter.unsubscribe("my-subscription"); // Удаление конкретной подписки
+     * promoter.unsubscribe(); // Очистка всех подписок
+     * ```
      */
-    unsub(key?: RID): boolean;
+    unsubscribe(key?: RID): void;
 }

package/dist/promoter.js

@@ -1,33 +1,40 @@
 /**
- * Класс для создания простого механизма подписок
+ * Простой механизм подписок
  */
 export class Promoter {
     __subs = new Map();
-    /**
-     * Вызывает подписчиков
-     */
-    notify(data) {
-        this.__subs.forEach(({ call, once }, key) => {
-            call(data);
+    notify(event) {
+        this.__subs.forEach(({ callback, once }, key) => {
+            callback(event);
             if (once)
                 this.__subs.delete(key);
         });
     }
     /**
-     * Подписка на события
+     * @param callback - Функция подписчика
+     * @param [options] - Опции запуска
+     * @param [options.once] - Одноразовая подписка
+     * @param [options.key=Symbol()] - Ключ подписчика
+     *
+     * @returns - Функция для отмены подписки
      */
-    sub(call, params = {}) {
-        const { key = Symbol(), once } = params;
-        this.__subs.set(key, { call, once });
+    subscribe(callback, options = {}) {
+        const { key = Symbol(), once } = options;
+        this.__subs.set(key, { callback, once });
         return () => this.__subs.delete(key);
     }
     /**
-     * Удаляет подписчика по ключу. Если не указан, очищаются все
+     * **Если ключ не указан, очищаются все**
+     *
+     * @example
+     * ```typescript
+     * promoter.unsubscribe("my-subscription"); // Удаление конкретной подписки
+     * promoter.unsubscribe(); // Очистка всех подписок
+     * ```
      */
-    unsub(key) {
-        if (key)
-            return this.__subs.delete(key);
-        this.__subs.clear();
-        return true;
+    unsubscribe(key) {
+        if (key === undefined)
+            return this.__subs.clear();
+        this.__subs.delete(key);
     }
 }

package/dist/random.d.ts

@@ -1,45 +1,44 @@
 /**
  * Генерирует случайный числовой код указанной длины.
- * Код состоит только из цифр и не может начинаться с нуля.
+ * Код состоит только из цифр и не может начинаться с нуля
  *
- * @param length - Длина генерируемого кода (по умолчанию 6)
- * @returns Строка с числовым кодом
+ * @param [length=6] - Длина генерируемого кода
  *
  * @example
  * ```typescript
- * rand(4); // "1234" (пример)
- * rand(6); // "123456" (пример)
- * rand(8); // "12345678" (пример)
+ * rand(4); // "1234"
+ * rand(); // "123456"
+ * rand(8); // "12345678"
  * ```
  */
 export declare const rand: (length?: number) => string;
 /**
- * Генерирует уникальный ID, состоящий из текущей временной метки и случайного кода.
- * Формат: `timestamp:randomCode`
+ * Генерирует уникальный ID, состоящий из {@link Timestamp} и случайного кода из {@link rand}
  *
- * @param length - Длина случайной части кода (по умолчанию 7)
- * @returns Уникальный ID в формате строки
+ * Формат: `${Date.now()}:${rand(length)}`
+ *
+ * @param [length=7] - Длина случайной части кода
  *
  * @example
  * ```typescript
- * randID(4); // "1696934400000:1234" (пример)
- * randID(6); // "1696934400000:123456" (пример)
+ * randID(4); // "1696934400000:1234"
+ * randID(6); // "1696934400000:123456"
  * ```
  */
 export declare const randID: (length?: number) => string;
 /**
- * Генерирует случайный UID (уникальный идентификатор) из буквенно-цифровых символов.
- * Может включать префикс таблицы для организации идентификаторов.
+ * Генерирует случайный UID из латиницы в нижнем регистре и цифр
+ *
+ * Формат: `prefix ? `${prefix}:${uid}` : uid`
  *
- * @param table - Префикс таблицы для организации UID (опционально)
- * @param length - Длина UID в символах (по умолчанию 20)
- * @returns Случайный UID в формате строки
+ * @param [prefix] - Префикс для категоризации UID (например таблица)
+ * @param [length=20] - Длина UID в символах
  *
  * @example
  * ```typescript
- * randUID(); // "a1b2c3d4e5f6g7h8i9j0" (пример)
- * randUID("user", 10); // "user:a1b2c3d4e5" (пример)
- * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8" (пример)
+ * randUID(); // "a1b2c3d4e5f6g7h8i9j0"
+ * randUID("user", 10); // "user:a1b2c3d4e5"
+ * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8"
  * ```
  */
-export declare const randUID: (table?: string, length?: number) => string;
+export declare const randUID: (prefix?: string, length?: number) => string;

package/dist/random.js

@@ -1,15 +1,14 @@
 /**
  * Генерирует случайный числовой код указанной длины.
- * Код состоит только из цифр и не может начинаться с нуля.
+ * Код состоит только из цифр и не может начинаться с нуля
  *
- * @param length - Длина генерируемого кода (по умолчанию 6)
- * @returns Строка с числовым кодом
+ * @param [length=6] - Длина генерируемого кода
  *
  * @example
  * ```typescript
- * rand(4); // "1234" (пример)
- * rand(6); // "123456" (пример)
- * rand(8); // "12345678" (пример)
+ * rand(4); // "1234"
+ * rand(); // "123456"
+ * rand(8); // "12345678"
  * ```
  */
 export const rand = (length = 6) => {
@@ -17,38 +16,38 @@ export const rand = (length = 6) => {
     return Math.floor(min + Math.random() * 9 * min).toString();
 };
 /**
- * Генерирует уникальный ID, состоящий из текущей временной метки и случайного кода.
- * Формат: `timestamp:randomCode`
+ * Генерирует уникальный ID, состоящий из {@link Timestamp} и случайного кода из {@link rand}
  *
- * @param length - Длина случайной части кода (по умолчанию 7)
- * @returns Уникальный ID в формате строки
+ * Формат: `${Date.now()}:${rand(length)}`
+ *
+ * @param [length=7] - Длина случайной части кода
  *
  * @example
  * ```typescript
- * randID(4); // "1696934400000:1234" (пример)
- * randID(6); // "1696934400000:123456" (пример)
+ * randID(4); // "1696934400000:1234"
+ * randID(6); // "1696934400000:123456"
  * ```
  */
 export const randID = (length = 7) => `${Date.now()}:${rand(length)}`;
 /**
- * Генерирует случайный UID (уникальный идентификатор) из буквенно-цифровых символов.
- * Может включать префикс таблицы для организации идентификаторов.
+ * Генерирует случайный UID из латиницы в нижнем регистре и цифр
+ *
+ * Формат: `prefix ? `${prefix}:${uid}` : uid`
  *
- * @param table - Префикс таблицы для организации UID (опционально)
- * @param length - Длина UID в символах (по умолчанию 20)
- * @returns Случайный UID в формате строки
+ * @param [prefix] - Префикс для категоризации UID (например таблица)
+ * @param [length=20] - Длина UID в символах
  *
  * @example
  * ```typescript
- * randUID(); // "a1b2c3d4e5f6g7h8i9j0" (пример)
- * randUID("user", 10); // "user:a1b2c3d4e5" (пример)
- * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8" (пример)
+ * randUID(); // "a1b2c3d4e5f6g7h8i9j0"
+ * randUID("user", 10); // "user:a1b2c3d4e5"
+ * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8"
  * ```
  */
-export const randUID = (table, length = 20) => {
-    const UID = "abcdefghijklmnopqrstuvwxyz0123456789"; // 36 символов
+export const randUID = (prefix, length = 20) => {
+    const UID = "abcdefghijklmnopqrstuvwxyz0123456789";
     let uid = "";
     for (let i = 0; i < length; i++)
         uid += UID[Math.floor(Math.random() * 36)];
-    return table ? `${table}:${uid}` : uid;
+    return prefix ? `${prefix}:${uid}` : uid;
 };

package/dist/rubles.d.ts

@@ -0,0 +1,24 @@
+import type { NumberFormatConfig } from "./phymath/format.js";
+import type { CanBeNullable } from "./types.js";
+/**
+ * Форматирование в RUB-формат с помощью {@link toNumberFormat}
+ *
+ * @example
+ * ```typescript
+ * formatRUB(1234); // "1 234 ₽"
+ * formatRUB(1234.5); // "1 234,50 ₽"
+ * formatRUB(1234.56); // "1 234,56 ₽"
+ * ```
+ */
+export declare const formatRUB: (amount: CanBeNullable<number | string>, config?: Omit<NumberFormatConfig, "postfix">) => string;
+/**
+ * Склонение слова "рубль" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralRUB(1); // "рубль"
+ * pluralRUB(3); // "рубля"
+ * pluralRUB(155); // "рублей"
+ * ```
+ */
+export declare const pluralRUB: (value: number) => string;

package/dist/rubles.js

@@ -0,0 +1,24 @@
+import { createValuePluralizer } from "./index.js";
+import { toNumberFormat } from "./phymath/format.js";
+/**
+ * Форматирование в RUB-формат с помощью {@link toNumberFormat}
+ *
+ * @example
+ * ```typescript
+ * formatRUB(1234); // "1 234 ₽"
+ * formatRUB(1234.5); // "1 234,50 ₽"
+ * formatRUB(1234.56); // "1 234,56 ₽"
+ * ```
+ */
+export const formatRUB = (amount, config = {}) => toNumberFormat(amount, { ...config, postfix: "₽" });
+/**
+ * Склонение слова "рубль" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralRUB(1); // "рубль"
+ * pluralRUB(3); // "рубля"
+ * pluralRUB(155); // "рублей"
+ * ```
+ */
+export const pluralRUB = createValuePluralizer("рубль", "рубля", "рублей");

package/dist/script.d.ts

@@ -1,21 +1,42 @@
-import type { Timestamp } from "./types.js";
 import type { ExecException } from "node:child_process";
 /**
- * Ищет значение флага в массиве аргументов процесса
- *
  * @param cmd - Команда, которой скрипт был запущен (`process.argv`)
  * @param name - Имя флага, который нужно найти
- * @param [strict=true] - Если `true`, выбрасывает ошибку, если флаг не найден. Если `false`, возвращает `null`
+ * @param [strict=true] - Выбрасывает ошибку, если флаг не найден
  *
- * @returns Значение флага (или `null`, если флаг не найден и `strict = false`)
  * @throws {Error} Если `strict = true` и флаг не найден
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "--name", "value"]
+ * getProcessFlag(process.argv, "--name"); // "value"
+ * getProcessFlag(process.argv, "--unknown", false); // null
+ * getProcessFlag(process.argv, "--unknown"); // Error
+ * ```
  */
 declare function getProcessFlag(cmd: string[], name: string, strict: boolean): string | null;
+/**
+ * @param cmd - Команда, которой скрипт был запущен (`process.argv`)
+ * @param name - Имя флага, который нужно найти
+ * @param [strict=true] - Выбрасывает ошибку, если флаг не найден
+ *
+ * @throws {Error} Если флаг не найден
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "--name", "value"]
+ * getProcessFlag(process.argv, "--name"); // "value"
+ * getProcessFlag(process.argv, "--unknown"); // Error
+ * ```
+ */
 declare function getProcessFlag(cmd: string[], name: string, strict?: true): string;
 export { getProcessFlag };
+/**
+ * Хуки логирования для {@link execute}
+ */
 export interface ExecuteLogger {
     /**
-     * Перед выполнением команды
+     * Перед выполнением
      */
     before?: (path: string) => string;
     /**
@@ -27,21 +48,47 @@ export interface ExecuteLogger {
      */
     ontimeout?: () => string;
 }
+/**
+ * Опции для {@link execute}
+ */
 export interface ExecuteOptions {
+    /**
+     * Хуки логирования выполнения команды
+     */
     logger?: ExecuteLogger;
     /**
-     * @default 5min
+     * Таймаут выполнения команды в миллисекундах
      */
-    timeout?: Timestamp | null;
+    timeout?: number | null;
 }
 /**
- * Запускает дочерний процесс с указанной командой в заданной директории
+ * Запускает команду через {@link exec} в указанной директории
  *
- * @param path - Директория, в которой будет выполнена команда
+ * @remarks При таймауте процесс завершается сигналом `SIGTERM`, но stdout/stderr могут быть выведены после отклонения промиса
+ *
+ * @param path - Путь к директории, в которой запускать команду
  * @param command - Команда для выполнения
- * @param logger - Хуки для логирования
- * @param [timeout=5min] - Таймаут выполнения команды в миллисекундах (по умолчанию 5 минут)
+ * @param [options] - Опции выполнения
+ * @param [options.logger] - Хуки логирования
+ * @param [options.timeout=5min] - Таймаут в миллисекундах или `null` без таймаута
+ *
+ * @throws {ExecException} Если команда завершается с ошибкой
+ * @throws {Error} Если истекает таймаут
+ *
+ * @example
+ * ```typescript
+ * await execute("/project/path", "pnpm install");
+ *
+ * await execute("/project/path", "pnpm run build", {
+ *   logger: {
+ *     before: (path) => `Запуск сборки в ${path}`,
+ *     onerror: (error) => `Ошибка сборки: ${error.message}`,
+ *     ontimeout: () => "Таймаут сборки"
+ *   },
+ *   timeout: 60000
+ * });
  *
- * @throws {Error} Если команда завершается с ошибкой или истекает таймаут
+ * await execute("/path", "long-running-command", { timeout: null | 0 });
+ * ```
  */
 export declare const execute: (path: string, command: string, { logger, timeout }?: ExecuteOptions) => Promise<void>;

package/dist/script.js

@@ -1,4 +1,20 @@
+import { MS_IN_MINUTE } from "./datetime/delta.js";
 import { exec } from "node:child_process";
+/**
+ * @param cmd - Команда, которой скрипт был запущен (`process.argv`)
+ * @param name - Имя флага, который нужно найти
+ * @param [strict=true] - Выбрасывает ошибку, если флаг не найден
+ *
+ * @throws {Error} Если `strict = true` и флаг не найден
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "--name", "value"]
+ * getProcessFlag(process.argv, "--name"); // "value"
+ * getProcessFlag(process.argv, "--unknown", false); // null
+ * getProcessFlag(process.argv, "--unknown"); // Error
+ * ```
+ */
 function getProcessFlag(cmd, name, strict = true) {
     const argv = cmd.slice(2);
     const index = argv.indexOf(name);
@@ -14,16 +30,36 @@ function getProcessFlag(cmd, name, strict = true) {
 }
 export { getProcessFlag };
 /**
- * Запускает дочерний процесс с указанной командой в заданной директории
+ * Запускает команду через {@link exec} в указанной директории
+ *
+ * @remarks При таймауте процесс завершается сигналом `SIGTERM`, но stdout/stderr могут быть выведены после отклонения промиса
  *
- * @param path - Директория, в которой будет выполнена команда
+ * @param path - Путь к директории, в которой запускать команду
  * @param command - Команда для выполнения
- * @param logger - Хуки для логирования
- * @param [timeout=5min] - Таймаут выполнения команды в миллисекундах (по умолчанию 5 минут)
+ * @param [options] - Опции выполнения
+ * @param [options.logger] - Хуки логирования
+ * @param [options.timeout=5min] - Таймаут в миллисекундах или `null` без таймаута
  *
- * @throws {Error} Если команда завершается с ошибкой или истекает таймаут
+ * @throws {ExecException} Если команда завершается с ошибкой
+ * @throws {Error} Если истекает таймаут
+ *
+ * @example
+ * ```typescript
+ * await execute("/project/path", "pnpm install");
+ *
+ * await execute("/project/path", "pnpm run build", {
+ *   logger: {
+ *     before: (path) => `Запуск сборки в ${path}`,
+ *     onerror: (error) => `Ошибка сборки: ${error.message}`,
+ *     ontimeout: () => "Таймаут сборки"
+ *   },
+ *   timeout: 60000
+ * });
+ *
+ * await execute("/path", "long-running-command", { timeout: null | 0 });
+ * ```
  */
-export const execute = async (path, command, { logger = {}, timeout = 5 * 60 * 1000 } = {}) => new Promise((resolve, reject) => {
+export const execute = async (path, command, { logger = {}, timeout = 5 * MS_IN_MINUTE } = {}) => new Promise((resolve, reject) => {
     if (logger.before)
         console.log(logger.before(path));
     let process = null;
@@ -34,14 +70,14 @@ export const execute = async (path, command, { logger = {}, timeout = 5 * 60 * 1
         clearTimeout(timer);
         timer = null;
     };
-    timer = timeout
-        ? setTimeout(() => {
+    if (timeout) {
+        timer = setTimeout(() => {
             process?.kill("SIGTERM");
             if (logger.ontimeout)
                 console.error(logger.ontimeout());
             reject(new Error("TIMEOUT"));
-        }, timeout)
-        : null;
+        }, timeout);
+    }
     process = exec(command, { cwd: path }, (error, stdout, stderr) => {
         cleanup();
         if (stderr)