@nemigo/helpers 0.13.2 → 1.5.0

package/dist/clean.d.ts

@@ -1,37 +1,55 @@
+/**
+ * Рекурсивно очищает массив от "пустых" значений.
+ * Использует внутри {@link deepCleanObject}
+ *
+ * - Не изменяет исходный массив и объекты внутри
+ * - Удаляет значения: `null`, `undefined`, пустые строки `""`
+ * - После очистки удаляет объекты и массивы, ставшие пустыми
+ *
+ * @example
+ * ```typescript
+ * const array = [1, null, "", { a: "", b: 2 }, undefined];
+ * const cleanedArray = deepCleanArray(array);
+ * console.log(cleanedArray); // [1, { b: 2 }]
+ * ```
+ */
+export declare const deepCleanArray: <T = unknown>(array: T[]) => T[];
 /**
  * Глубоко очищает объект (включая массивы) от "пустых" значений с созданием копии.
- * Удаляет значения: `null`, `undefined`, пустые строки `""`.
- * После очистки удаляет объекты и массивы, ставшие пустыми.
- * Не изменяет исходный объект.
+ * Использует внутри {@link deepCleanArray}
+ *
+ * - Не изменяет исходный объект и объекты внутри
+ * - Удаляет значения: `null`, `undefined`, пустые строки `""`
+ * - После очистки удаляет объекты и массивы, ставшие пустыми
  *
- * @template O - Тип исходного объекта
- * @param data - Объект или значение для очистки
- * @returns Очищенная копия объекта или исходное значение, если это не объект
+ * @remarks **НЕ** предназначен для работы с декларативными методами (могут потерять `this`)
  *
  * @example
  * ```typescript
- * const original = {
- *   a: 1,
- *   b: null,
- *   c: {
- *     d: '',
- *     e: { f: undefined },
- *     g: [1, null, '', { h: undefined }]
+ * const obj = {
+ *   users: [
+ *     { name: "John", age: 30, email: "" },
+ *     { name: "", age: null, email: "test@example.com" },
+ *     { name: "Alice", age: 25, email: undefined }
+ *   ],
+ *   settings: {
+ *     theme: "dark",
+ *     notifications: null,
+ *     preferences: {}
  *   }
  * };
  *
- * const cleaned = deepObjectClean(original);
- * console.log(cleaned); // { a: 1 }
- * console.log(original); // Исходный объект не изменен
- *
- * // Работа с массивами
- * const array = [1, null, '', { a: '', b: 2 }, undefined];
- * const cleanedArray = deepObjectClean(array);
- * console.log(cleanedArray); // [1, { b: 2 }]
- *
- * // Примитивы возвращаются без изменений
- * deepObjectClean("hello"); // "hello"
- * deepObjectClean(null); // null
+ * const cleaned = deepObjectClean(obj);
+ * // {
+ * //   users: [
+ * //     { name: "John", age: 30 },
+ * //     { email: "test@example.com" },
+ * //     { name: "Alice", age: 25 }
+ * //   ],
+ * //   settings: {
+ * //     theme: "dark"
+ * //   }
+ * // }
  * ```
  */
-export declare const deepObjectClean: <O>(data: O) => O;
+export declare const deepCleanObject: <O = unknown>(data: O) => O;

package/dist/clean.js

@@ -1,63 +1,88 @@
+/**
+ * Рекурсивно очищает массив от "пустых" значений.
+ * Использует внутри {@link deepCleanObject}
+ *
+ * - Не изменяет исходный массив и объекты внутри
+ * - Удаляет значения: `null`, `undefined`, пустые строки `""`
+ * - После очистки удаляет объекты и массивы, ставшие пустыми
+ *
+ * @example
+ * ```typescript
+ * const array = [1, null, "", { a: "", b: 2 }, undefined];
+ * const cleanedArray = deepCleanArray(array);
+ * console.log(cleanedArray); // [1, { b: 2 }]
+ * ```
+ */
+export const deepCleanArray = (array) => array.reduce((acc, value) => {
+    // Пропускаем явно пустые примитивы
+    if (value === "" || value === null || value === undefined)
+        return acc;
+    // Рекурсивно обрабатываем объекты и массивы
+    if (typeof value === "object") {
+        const cleaned = deepCleanObject(value);
+        // Проверяем не стал ли объект/массив пустым после очистки
+        if (Array.isArray(cleaned) && cleaned.length > 0) {
+            acc.push(cleaned);
+        }
+        else if (!Array.isArray(cleaned) && Object.keys(cleaned).length > 0) {
+            acc.push(cleaned);
+        }
+    }
+    else {
+        // Сохраняем непустые примитивы
+        acc.push(value);
+    }
+    return acc;
+}, []);
 /**
  * Глубоко очищает объект (включая массивы) от "пустых" значений с созданием копии.
- * Удаляет значения: `null`, `undefined`, пустые строки `""`.
- * После очистки удаляет объекты и массивы, ставшие пустыми.
- * Не изменяет исходный объект.
+ * Использует внутри {@link deepCleanArray}
  *
- * @template O - Тип исходного объекта
- * @param data - Объект или значение для очистки
- * @returns Очищенная копия объекта или исходное значение, если это не объект
+ * - Не изменяет исходный объект и объекты внутри
+ * - Удаляет значения: `null`, `undefined`, пустые строки `""`
+ * - После очистки удаляет объекты и массивы, ставшие пустыми
+ *
+ * @remarks **НЕ** предназначен для работы с декларативными методами (могут потерять `this`)
  *
  * @example
  * ```typescript
- * const original = {
- *   a: 1,
- *   b: null,
- *   c: {
- *     d: '',
- *     e: { f: undefined },
- *     g: [1, null, '', { h: undefined }]
+ * const obj = {
+ *   users: [
+ *     { name: "John", age: 30, email: "" },
+ *     { name: "", age: null, email: "test@example.com" },
+ *     { name: "Alice", age: 25, email: undefined }
+ *   ],
+ *   settings: {
+ *     theme: "dark",
+ *     notifications: null,
+ *     preferences: {}
  *   }
  * };
  *
- * const cleaned = deepObjectClean(original);
- * console.log(cleaned); // { a: 1 }
- * console.log(original); // Исходный объект не изменен
- *
- * // Работа с массивами
- * const array = [1, null, '', { a: '', b: 2 }, undefined];
- * const cleanedArray = deepObjectClean(array);
- * console.log(cleanedArray); // [1, { b: 2 }]
- *
- * // Примитивы возвращаются без изменений
- * deepObjectClean("hello"); // "hello"
- * deepObjectClean(null); // null
+ * const cleaned = deepObjectClean(obj);
+ * // {
+ * //   users: [
+ * //     { name: "John", age: 30 },
+ * //     { email: "test@example.com" },
+ * //     { name: "Alice", age: 25 }
+ * //   ],
+ * //   settings: {
+ * //     theme: "dark"
+ * //   }
+ * // }
  * ```
  */
-export const deepObjectClean = (data) => {
+export const deepCleanObject = (data) => {
     if (typeof data !== "object" || data === null)
         return data;
-    if (Array.isArray(data)) {
-        return data.reduce((acc, value) => {
-            if (value !== "" && value !== null && value !== undefined) {
-                if (typeof value === "object") {
-                    const cleaned = deepObjectClean(value);
-                    if (Object.keys(cleaned).length !== 0)
-                        acc.push(cleaned);
-                }
-                else {
-                    acc.push(value);
-                }
-            }
-            return acc;
-        }, []);
-    }
+    if (Array.isArray(data))
+        return deepCleanArray(data);
     const result = {};
     for (const key in data) {
         const value = data[key];
         if (value !== "" && value !== null && value !== undefined) {
             if (typeof value === "object") {
-                const cleaned = deepObjectClean(value);
+                const cleaned = deepCleanObject(value);
                 if (Object.keys(cleaned).length !== 0)
                     result[key] = cleaned;
             }

package/dist/color/types.d.ts

@@ -0,0 +1,31 @@
+import type { Cortege } from "../types.js";
+export type RGB = [r: number, g: number, b: number] | Cortege<3>;
+export type RGBA = [r: number, g: number, b: number, a: number] | Cortege<4>;
+/**
+ * - h: оттенок, 0-360
+ * - s: насыщенность, 0-100
+ * - l: яркость, 0-100
+ */
+export type HSL = [h: number, s: number, l: number] | Cortege<3>;
+/**
+ * - h: оттенок, 0-360
+ * - s: насыщенность, 0-100
+ * - l: яркость, 0-100
+ * - a: альфа, 0-1
+ */
+export type HSLA = [h: number, s: number, l: number, a: number] | Cortege<4>;
+/**
+ * - h: оттенок, 0-360
+ * - s: насыщенность, 0-100
+ * - v: значение, 0-100
+ */
+export type HSV = [h: number, s: number, v: number] | Cortege<3>;
+/**
+ * - h: оттенок, 0-360
+ * - s: насыщенность, 0-100
+ * - v: значение, 0-100
+ * - a: альфа, 0-1
+ */
+export type HSVA = [h: number, s: number, v: number, a: number] | Cortege<4>;
+export type HEX = string;
+export type HEXA = string;

package/dist/color/types.js

@@ -0,0 +1 @@
+export {};

package/dist/datetime/delta.d.ts

@@ -0,0 +1,28 @@
+import type { RoundMethod } from "../phymath/index.js";
+import type { Timestamp } from "../types.js";
+export declare const MS_IN_SECOND = 1000;
+export declare const MS_IN_MINUTE: number;
+export declare const MS_IN_HOUR: number;
+export declare const MS_IN_DAY: number;
+export declare const MS_IN_WEEK: number;
+export declare const formatPerformanceDelta: (start: Timestamp, end?: Timestamp) => string;
+/**
+ * Дельта-объект времени для {@link timeDeltaObjectToTimestamp}
+ */
+export interface TimeDeltaObject {
+    w?: number;
+    d?: number;
+    h?: number;
+    m?: number;
+    s?: number;
+    ms?: number;
+}
+/**
+ * Опции для {@link timeDeltaObjectToTimestamp}
+ */
+export interface TimeDeltaDeltaObjectToTimestampOptions {
+    round_key?: keyof TimeDeltaObject;
+    round_method?: RoundMethod;
+    in_seconds?: boolean;
+}
+export declare const timeDeltaObjectToTimestamp: (obj: TimeDeltaObject, options?: TimeDeltaDeltaObjectToTimestampOptions) => number;

package/dist/datetime/delta.js

@@ -0,0 +1,65 @@
+import { round } from "../phymath/index.js";
+export const MS_IN_SECOND = 1000;
+export const MS_IN_MINUTE = 60 * MS_IN_SECOND;
+export const MS_IN_HOUR = 60 * MS_IN_MINUTE;
+export const MS_IN_DAY = 24 * MS_IN_HOUR;
+export const MS_IN_WEEK = 7 * MS_IN_DAY;
+export const formatPerformanceDelta = (start, end = Date.now()) => {
+    const diff = end - start;
+    if (diff < 1000)
+        return diff + "ms";
+    return diff / 1000 + "s";
+};
+export const timeDeltaObjectToTimestamp = (obj, options = {}) => {
+    const { round_key, round_method, in_seconds = false } = options;
+    // Вычисляем общее время в миллисекундах
+    let totalMs = 0;
+    if (obj.w)
+        totalMs += obj.w * MS_IN_WEEK;
+    if (obj.d)
+        totalMs += obj.d * MS_IN_DAY;
+    if (obj.h)
+        totalMs += obj.h * MS_IN_HOUR;
+    if (obj.m)
+        totalMs += obj.m * MS_IN_MINUTE;
+    if (obj.s)
+        totalMs += obj.s * MS_IN_SECOND;
+    if (obj.ms)
+        totalMs += obj.ms;
+    // Применяем округление если указано
+    if (round_key) {
+        let unitValue;
+        switch (round_key) {
+            case "w":
+                unitValue = MS_IN_WEEK;
+                break;
+            case "d":
+                unitValue = MS_IN_DAY;
+                break;
+            case "h":
+                unitValue = MS_IN_HOUR;
+                break;
+            case "m":
+                unitValue = MS_IN_MINUTE;
+                break;
+            case "s":
+                unitValue = MS_IN_SECOND;
+                break;
+            case "ms":
+                unitValue = 1;
+                break;
+            default:
+                unitValue = 1;
+        }
+        // Преобразуем в нужные единицы, округляем и возвращаем к миллисекундам
+        const valueInUnits = totalMs / unitValue;
+        const roundedValue = round(valueInUnits, 0, round_method);
+        totalMs = roundedValue * unitValue;
+    }
+    // Если нужен результат в секундах
+    if (in_seconds) {
+        const seconds = totalMs / MS_IN_SECOND;
+        return round(seconds, 0, round_method);
+    }
+    return totalMs;
+};

package/dist/datetime/format.d.ts

@@ -0,0 +1,53 @@
+import type { DateTime } from "../types.js";
+/**
+ * Полные названия месяцев на русском языке (родительный падеж)
+ */
+export declare const months: string[];
+/**
+ * Сокращенные названия месяцев на русском языке
+ */
+export declare const abbs: string[];
+/**
+ * Шаблонизатор для форматирования даты и времени
+ *
+ * **Поддерживаемые токены:**
+ * - `TS` - секунды (00-59)
+ * - `TM` - минуты (00-59)
+ * - `TH` - часы (00-23)
+ * - `DD` - день месяца (01-31)
+ * - `DM` - месяц числом (01-12)
+ * - `DFM` - месяц полным названием (января, февраля, ...)
+ * - `DAM` - месяц сокращённым названием (янв, фев, ...)
+ * - `DY` - год (4 цифры)
+ *
+ * @param datetime - Дата и время для форматирования
+ * @param [format="DD.DM.DY TH:TM"] - Шаблон форматирования с токенами
+ * @param [timezone] - Часовой пояс в часах относительно UTC
+ *
+ * @example
+ * ```typescript
+ * // Базовое использование
+ * formatDateTime(new Date(), "DD.DM.DY TH:TM:TS");
+ * // "09.10.2023 14:30:59"
+ *
+ * // Форматирование с полными названиями месяцев
+ * formatDateTime(Date.now(), "DD DFM DY");
+ * // "09 октября 2023"
+ *
+ * // Сокращенные названия месяцев
+ * formatDateTime("2023-12-25", "DD DAM DY");
+ * // "25 дек 2023"
+ *
+ * // С указанием в нужном часовом поясе
+ * formatDateTime(Date.now(), "DD.DM.DY TH:TM", 3); // По МСК
+ * // "09.10.2023 17:30" (если по UTC время 14:30)
+ * ```
+ */
+export declare const formatDateTime: (datetime?: DateTime, format?: string, timezone?: number) => string;
+/**
+ * Готовый пресет {@link formatDateTime} для форматирования в московском часовом поясе (МСК +3)
+ *
+ * @param datetime - Дата и время для форматирования
+ * @param [format="DD.DM.DY TH:TM (МСК)"] - Шаблон форматирования с токенами
+ */
+export declare const formatMSK: (datetime?: DateTime, format?: string) => string;

package/dist/datetime/format.js

@@ -0,0 +1,119 @@
+import { MS_IN_MINUTE } from "./delta.js";
+import { pad } from "../index.js";
+/**
+ * Полные названия месяцев на русском языке (родительный падеж)
+ */
+export const months = [
+    "января",
+    "февраля",
+    "марта",
+    "апреля",
+    "мая",
+    "июня",
+    "июля",
+    "августа",
+    "сентября",
+    "октября",
+    "ноября",
+    "декабря",
+];
+/**
+ * Сокращенные названия месяцев на русском языке
+ */
+export const abbs = [
+    "янв",
+    "фев",
+    "марта",
+    "апр",
+    "мая",
+    "июня",
+    "июля",
+    "авг",
+    "сен",
+    "окт",
+    "ноя",
+    "дек",
+];
+/**
+ * Шаблонизатор для форматирования даты и времени
+ *
+ * **Поддерживаемые токены:**
+ * - `TS` - секунды (00-59)
+ * - `TM` - минуты (00-59)
+ * - `TH` - часы (00-23)
+ * - `DD` - день месяца (01-31)
+ * - `DM` - месяц числом (01-12)
+ * - `DFM` - месяц полным названием (января, февраля, ...)
+ * - `DAM` - месяц сокращённым названием (янв, фев, ...)
+ * - `DY` - год (4 цифры)
+ *
+ * @param datetime - Дата и время для форматирования
+ * @param [format="DD.DM.DY TH:TM"] - Шаблон форматирования с токенами
+ * @param [timezone] - Часовой пояс в часах относительно UTC
+ *
+ * @example
+ * ```typescript
+ * // Базовое использование
+ * formatDateTime(new Date(), "DD.DM.DY TH:TM:TS");
+ * // "09.10.2023 14:30:59"
+ *
+ * // Форматирование с полными названиями месяцев
+ * formatDateTime(Date.now(), "DD DFM DY");
+ * // "09 октября 2023"
+ *
+ * // Сокращенные названия месяцев
+ * formatDateTime("2023-12-25", "DD DAM DY");
+ * // "25 дек 2023"
+ *
+ * // С указанием в нужном часовом поясе
+ * formatDateTime(Date.now(), "DD.DM.DY TH:TM", 3); // По МСК
+ * // "09.10.2023 17:30" (если по UTC время 14:30)
+ * ```
+ */
+export const formatDateTime = (datetime = Date.now(), format = "DD.DM.DY TH:TM", timezone) => {
+    const base = new Date(datetime);
+    const useTimezone = timezone !== undefined;
+    const shiftMinutes = useTimezone ? Math.round(timezone * 60) : 0;
+    const shifted = useTimezone ? new Date(base.valueOf() + shiftMinutes * MS_IN_MINUTE) : base;
+    const seconds = useTimezone ? shifted.getUTCSeconds() : shifted.getSeconds();
+    const minutes = useTimezone ? shifted.getUTCMinutes() : shifted.getMinutes();
+    const hours = useTimezone ? shifted.getUTCHours() : shifted.getHours();
+    const day = useTimezone ? shifted.getUTCDate() : shifted.getDate();
+    const monthIndex = useTimezone ? shifted.getUTCMonth() : shifted.getMonth();
+    const year = useTimezone ? shifted.getUTCFullYear() : shifted.getFullYear();
+    const replacements = {
+        TS: pad(seconds),
+        TM: pad(minutes),
+        TH: pad(hours),
+        DD: pad(day),
+        DM: pad(monthIndex + 1),
+        DFM: months[monthIndex],
+        DAM: abbs[monthIndex],
+        DY: year.toString(),
+    };
+    const result = [];
+    let position = 0;
+    while (position < format.length) {
+        let tokenFound = false;
+        for (const token in replacements) {
+            if (format.startsWith(token, position)) {
+                result.push(replacements[token]);
+                position += token.length;
+                tokenFound = true;
+                break;
+            }
+        }
+        if (!tokenFound) {
+            result.push(format[position]);
+            position++;
+        }
+    }
+    return result.join("");
+};
+/**
+ * Готовый пресет {@link formatDateTime} для форматирования в московском часовом поясе (МСК +3)
+ *
+ * @param datetime - Дата и время для форматирования
+ * @param [format="DD.DM.DY TH:TM (МСК)"] - Шаблон форматирования с токенами
+ */
+export const formatMSK = (datetime, format = "DD.DM.DY TH:TM (МСК)") => formatDateTime(datetime, format, 3);

package/dist/datetime/index.d.ts

@@ -0,0 +1,6 @@
+export declare const isEqualDay: (a: Date, b: Date) => boolean;
+export declare const isToday: (date: Date) => boolean;
+export declare const isYesterday: (date: Date) => boolean;
+export declare const isDayBeforeYesterday: (date: Date) => boolean;
+export declare const isTomorrow: (date: Date) => boolean;
+export declare const isDayAfterTomorrow: (date: Date) => boolean;

package/dist/datetime/index.js

@@ -0,0 +1,22 @@
+export const isEqualDay = (a, b) => a.toDateString() === b.toDateString();
+export const isToday = (date) => isEqualDay(date, new Date());
+export const isYesterday = (date) => {
+    const target = new Date();
+    target.setDate(target.getDate() - 1);
+    return isEqualDay(date, target);
+};
+export const isDayBeforeYesterday = (date) => {
+    const target = new Date();
+    target.setDate(target.getDate() - 2);
+    return isEqualDay(date, target);
+};
+export const isTomorrow = (date) => {
+    const target = new Date();
+    target.setDate(target.getDate() + 1);
+    return isEqualDay(date, target);
+};
+export const isDayAfterTomorrow = (date) => {
+    const target = new Date();
+    target.setDate(target.getDate() + 2);
+    return isEqualDay(date, target);
+};

package/dist/datetime/plural.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Склонение слова "секунда" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralSeconds(1); // "секунда"
+ * pluralSeconds(3); // "секунды"
+ * pluralSeconds(155); // "секунд"
+ * ```
+ */
+export declare const pluralSeconds: (value: number) => string;
+/**
+ * Склонение слова "минута" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralMinutes(1); // "минута"
+ * pluralMinutes(3); // "минуты"
+ * pluralMinutes(155); // "минут"
+ * ```
+ */
+export declare const pluralMinutes: (value: number) => string;
+/**
+ * Склонение слова "час" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralHours(1); // "час"
+ * pluralHours(3); // "часа"
+ * pluralHours(155); // "часов"
+ * ```
+ */
+export declare const pluralHours: (value: number) => string;
+/**
+ * Склонение слова "день" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralDays(1); // "день"
+ * pluralDays(3); // "дня"
+ * pluralDays(155); // "дней"
+ * ```
+ */
+export declare const pluralDays: (value: number) => string;
+/**
+ * Склонение слова "неделя" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralWeeks(1); // "неделя"
+ * pluralWeeks(3); // "недели"
+ * pluralWeeks(155); // "недель"
+ * ```
+ */
+export declare const pluralWeeks: (value: number) => string;
+/**
+ * Склонение слова "месяц" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralMonths(1); // "месяц"
+ * pluralMonths(3); // "месяца"
+ * pluralMonths(155); // "месяцев"
+ * ```
+ */
+export declare const pluralMonths: (value: number) => string;
+/**
+ * Склонение слова "год" в зависимости от числа
+ *
+ * @example
+ * ```typescript
+ * pluralYears(1); // "год"
+ * pluralYears(3); // "года"
+ * pluralYears(155); // "лет"
+ * ```
+ */
+export declare const pluralYears: (value: number) => string;