@nemigo/helpers 0.0.13 → 0.0.19

package/dist/datetime.d.ts

@@ -0,0 +1,44 @@
+import type { Timestamp } from "./types.js";
+/**
+ * Русифицированные названия месяцев в родительском падеже
+ */
+export declare const months: string[];
+/**
+ * Русифицированные сокращённые названия месяцев в родительском падеже
+ */
+export declare const abbs: string[];
+/**
+ * Шаблонизатор вывода даты и времени из {@link Timestamp}
+ *
+ * TS - секунды
+ *
+ * TM - минуты
+ *
+ * DD - дни
+ *
+ * DM - месяц числом
+ *
+ * DFM - месяц полным названием
+ *
+ * DAM - месяц сокращённым названием
+ *
+ * DY - год
+ *
+ * @example
+ * const formatted = dateTimeFormatter(new Date(), 'DD.DM.DY TH:TM:TS');
+ * console.log(formatted); // "09.10.2023 14:30:59"
+ */
+export declare const formatDateTime: (datetime?: Date | Timestamp | string, format?: string) => string;
+/**
+ * Конвертирует строковые представления даты и времени в {@link Timestamp}
+ *
+ * @param date - Строка даты в формате "DD.MM.YYYY"
+ * @param [time="00:00"] - Строка времени в формате "HH:MM"
+ *
+ * @returns TimeStamp соответствующий указанной дате и времени или 0 при неверном формате
+ *
+ * @example
+ * const timestamp = toTimeStamp("11.02.2012", "13:45");
+ * console.log(timestamp); // Выведет {@link Timestamp} для "11.02.2012 13:45"
+ */
+export declare const toTimeStamp: (date: string, time?: string) => Timestamp | 0;

package/dist/datetime.js

@@ -0,0 +1,109 @@
+import { pad } from "./index.js";
+/**
+ * Русифицированные названия месяцев в родительском падеже
+ */
+export const months = [
+    "января",
+    "февраля",
+    "марта",
+    "апреля",
+    "мая",
+    "июня",
+    "июля",
+    "августа",
+    "сентября",
+    "октября",
+    "ноября",
+    "декабря",
+];
+/**
+ * Русифицированные сокращённые названия месяцев в родительском падеже
+ */
+export const abbs = [
+    "янв",
+    "фев",
+    "марта",
+    "апр",
+    "мая",
+    "июня",
+    "июля",
+    "авг",
+    "сен",
+    "окт",
+    "ноя",
+    "дек",
+];
+/**
+ * Шаблонизатор вывода даты и времени из {@link Timestamp}
+ *
+ * TS - секунды
+ *
+ * TM - минуты
+ *
+ * DD - дни
+ *
+ * DM - месяц числом
+ *
+ * DFM - месяц полным названием
+ *
+ * DAM - месяц сокращённым названием
+ *
+ * DY - год
+ *
+ * @example
+ * const formatted = dateTimeFormatter(new Date(), 'DD.DM.DY TH:TM:TS');
+ * console.log(formatted); // "09.10.2023 14:30:59"
+ */
+export const formatDateTime = (datetime = Date.now(), format = "DD.DM.DY TH:TM") => {
+    const date = new Date(datetime);
+    const replacements = {
+        TS: pad(date.getSeconds()),
+        TM: pad(date.getMinutes()),
+        TH: pad(date.getHours()),
+        //...
+        DD: pad(date.getDate()),
+        DM: pad(date.getMonth() + 1),
+        DFM: months[date.getMonth()],
+        DAM: abbs[date.getMonth()],
+        DY: date.getFullYear().toString(),
+    };
+    const result = [];
+    let i = 0;
+    while (i < format.length) {
+        let found = false;
+        for (const key in replacements) {
+            if (format.startsWith(key, i)) {
+                result.push(replacements[key]);
+                i += key.length;
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            result.push(format[i]);
+            i++;
+        }
+    }
+    return result.join("");
+};
+/**
+ * Конвертирует строковые представления даты и времени в {@link Timestamp}
+ *
+ * @param date - Строка даты в формате "DD.MM.YYYY"
+ * @param [time="00:00"] - Строка времени в формате "HH:MM"
+ *
+ * @returns TimeStamp соответствующий указанной дате и времени или 0 при неверном формате
+ *
+ * @example
+ * const timestamp = toTimeStamp("11.02.2012", "13:45");
+ * console.log(timestamp); // Выведет {@link Timestamp} для "11.02.2012 13:45"
+ */
+export const toTimeStamp = (date, time = "00:00") => {
+    const [day, month, year] = date.split(".").map(Number);
+    const [hours, minutes] = time.split(":").map(Number);
+    // Проверка на корректность ввода (если хотя бы одно значение не число)
+    // prettier-ignore
+    if ([day, month, year, hours, minutes].some(isNaN))
+        return 0;
+    return new Date(year, month - 1, day, hours, minutes).valueOf();
+};

package/dist/format.d.ts

@@ -0,0 +1,31 @@
+import type { CanBeNullable } from "./types.js";
+interface FormatNumberConfig {
+    /**
+     * @default 2
+     */
+    fraction?: number;
+    /**
+     * @default "---"
+     */
+    fallback?: string;
+    /**
+     * @example "₽"
+     */
+    postfix?: string;
+    /**
+     * - "always" - "0" для всех исключительных ситуаций
+     * - "value" - "0" только при значении равном нулю, иначе `fallback`
+     * - "never" - `fallback` всегда
+     *
+     * @default value
+     */
+    zero?: "always" | "value" | "never";
+}
+export declare const FormatNumberRegExp: RegExp;
+/**
+ * Форматирование числа по тысячам
+ *
+ * @example "1 234" или "1 234,56"
+ */
+export declare const formatNumber: (amount: CanBeNullable<number | string>, { fraction, fallback, zero, postfix }?: FormatNumberConfig) => string;
+export {};

package/dist/format.js

@@ -0,0 +1,20 @@
+import { caseNumber } from "./cases.js";
+import { toRound } from "./phymath.js";
+export const FormatNumberRegExp = /\B(?=(\d{3})+(?!\d))/g;
+/**
+ * Форматирование числа по тысячам
+ *
+ * @example "1 234" или "1 234,56"
+ */
+export const formatNumber = (amount, { fraction = 2, fallback = "---", zero = "value", postfix } = {}) => caseNumber(amount, (v) => {
+    if (v === undefined)
+        return zero === "always" ? (postfix ? "0 " + postfix : "0") : fallback;
+    if (v === 0)
+        return zero === "never" ? fallback : postfix ? "0 " + postfix : "0";
+    if (fraction === 0)
+        return Math.round(v).toString().replace(FormatNumberRegExp, " ");
+    const { 0: integer, 1: fractional = "" } = toRound(v, fraction).toString().split(".");
+    const result = integer.replace(FormatNumberRegExp, " ");
+    const formatted = fractional ? `${result},${fractional}` : result;
+    return postfix ? formatted + " " + postfix : formatted;
+});

package/dist/html.d.ts

@@ -0,0 +1,58 @@
+import type { CanBeNullable, CanBePromise, KEYS } from "./types";
+/**
+ * Проверка по глобальному `window`
+ */
+export declare const isSSR: boolean;
+/**
+ * Предотвращает дефолтное поведение события и останавливает всплытие
+ */
+export declare const preventStop: (e: Event) => void;
+/**
+ * Создаёт обработчик события с {@link preventStop}, который выполняется всегда.
+ * Коллбэк выполняется только, если load вернёт `false` (при его наличии)
+ */
+export declare const preventStopHook: <T extends Event = Event>(call?: CanBeNullable<(e: T) => CanBePromise>, load?: () => boolean | undefined) => ((e: T) => void);
+/**
+ * Возвращает обработчик клавиатурных событий, который:
+ *
+ * 1. Если `usePreventStop === true`, вызывает {@link preventStop}
+ * 2. Если load вернёт `false` (при его наличии), то выполнение остановится
+ * 3. Вызывает переданный **prepare-коллбэк** (при его наличии), если он вернёт `false`, то выполнение остановится
+ * 4. Вызывает основной коллбэк только при нажатии `Enter`.
+ */
+export declare const enterKeyHook: <T extends KeyboardEvent = KeyboardEvent>(call?: CanBeNullable<(e: T) => CanBePromise>, config?: {
+    usePreventStop?: "enter" | boolean | ((e: T, isEnter: boolean) => boolean);
+    prepare?: (e: T) => CanBePromise<boolean>;
+    load?: () => boolean | undefined;
+}) => (e: T) => void;
+/**
+ * Создаёт обработчик событий для указанного элемента или окна
+ *
+ * @template T - Тип события из `WindowEventMap`
+ * @template E - Тип объекта события (по умолчанию `WindowEventMap[T]`)
+ *
+ * @param {T} event - Ключ события
+ * @param {(e: E) => CanBePromise} call - Функция-обработчик события
+ * @param {AddEventListenerOptions} [options] - Дополнительные параметры
+ * @param {HTMLElement | Window} [target=window] - Целевой элемент для привязки события
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export declare const createEventListener: <const M = WindowEventMap, const T extends KEYS<M> = KEYS<M>, const E = M[T]>(event: T, call: (e: E) => CanBePromise, options?: AddEventListenerOptions, target?: HTMLElement | Window | Document) => (() => void);
+/**
+ * Убирает все выделения текста на странице
+ */
+export declare const unselect: () => void;
+/**
+ * Создаёт once-обработчик события "mousedown" с {@link unselect}
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export declare const unselectByMousedown: () => (() => void);
+/**
+ * Преобразование `{@link FormData}` в объект
+ *
+ * @param form - данные формы
+ * @param multi - поддержка массивов значений
+ */
+export declare const formon: <D = any>(form: FormData, multi?: boolean) => D;

package/dist/html.js

@@ -0,0 +1,113 @@
+/**
+ * Проверка по глобальному `window`
+ */
+export const isSSR = typeof window === "undefined";
+/**
+ * Предотвращает дефолтное поведение события и останавливает всплытие
+ */
+export const preventStop = (e) => (e.preventDefault(), e.stopPropagation());
+/**
+ * Создаёт обработчик события с {@link preventStop}, который выполняется всегда.
+ * Коллбэк выполняется только, если load вернёт `false` (при его наличии)
+ */
+export const preventStopHook = (call, load) => (e) => {
+    preventStop(e);
+    if (!load || !load())
+        call?.(e);
+};
+//...
+/**
+ * Возвращает обработчик клавиатурных событий, который:
+ *
+ * 1. Если `usePreventStop === true`, вызывает {@link preventStop}
+ * 2. Если load вернёт `false` (при его наличии), то выполнение остановится
+ * 3. Вызывает переданный **prepare-коллбэк** (при его наличии), если он вернёт `false`, то выполнение остановится
+ * 4. Вызывает основной коллбэк только при нажатии `Enter`.
+ */
+export const enterKeyHook = (call, config = { usePreventStop: "enter" }) => (e) => {
+    const isEnter = e.key === "Enter";
+    if (config?.usePreventStop === "enter") {
+        if (isEnter)
+            preventStop(e);
+    }
+    else {
+        if (config?.usePreventStop !== undefined) {
+            if (typeof config?.usePreventStop === "boolean") {
+                if (config?.usePreventStop)
+                    preventStop(e);
+            }
+            else {
+                if (config?.usePreventStop(e, isEnter))
+                    preventStop(e);
+            }
+        }
+    }
+    if (config?.load?.())
+        return;
+    if (config?.prepare) {
+        Promise.resolve(config?.prepare?.(e)).then((next) => {
+            if (next && isEnter)
+                call?.(e);
+        });
+    }
+    else {
+        if (isEnter)
+            call?.(e);
+    }
+};
+//...
+/**
+ * Создаёт обработчик событий для указанного элемента или окна
+ *
+ * @template T - Тип события из `WindowEventMap`
+ * @template E - Тип объекта события (по умолчанию `WindowEventMap[T]`)
+ *
+ * @param {T} event - Ключ события
+ * @param {(e: E) => CanBePromise} call - Функция-обработчик события
+ * @param {AddEventListenerOptions} [options] - Дополнительные параметры
+ * @param {HTMLElement | Window} [target=window] - Целевой элемент для привязки события
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export const createEventListener = (event, call, options = {}, target = window) => {
+    target.addEventListener(event, call, options);
+    return () => target.removeEventListener(event, call);
+};
+//...
+/**
+ * Убирает все выделения текста на странице
+ */
+export const unselect = () => document.getSelection()?.removeAllRanges();
+/**
+ * Создаёт once-обработчик события "mousedown" с {@link unselect}
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export const unselectByMousedown = () => createEventListener("mousedown", unselect, { once: true });
+//...
+/**
+ * Преобразование `{@link FormData}` в объект
+ *
+ * @param form - данные формы
+ * @param multi - поддержка массивов значений
+ */
+export const formon = (form, multi = false) => {
+    if (multi) {
+        const result = {};
+        for (const { 0: key, 1: value } of form.entries()) {
+            if (result[key] !== undefined) {
+                if (!Array.isArray(result[key])) {
+                    result[key] = [result[key]];
+                }
+                result[key].push(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    else {
+        return Object.fromEntries(form.entries());
+    }
+};

package/dist/humanly.d.ts

@@ -0,0 +1,5 @@
+export type RU_CASES = "nominative" | "genitive" | "dative" | "accusative" | "ablative";
+/**
+ * Форма слова 'рубль' в правильном падеже и числе в зависимости от количества
+ */
+export declare const Rubles: (value: number, form?: RU_CASES) => string;

package/dist/humanly.js

@@ -0,0 +1,46 @@
+//...
+/**
+ * Основные формы слова 'рубль'
+ */
+const RublesMainSwitch = (form) => {
+    switch (form) {
+        case "dative":
+            return "рублям";
+        case "ablative":
+            return "рублями";
+        default:
+            return "рублей";
+    }
+};
+/**
+ * Форма слова 'рубль' в правильном падеже и числе в зависимости от количества
+ */
+export const Rubles = (value, form = "nominative") => {
+    const lastTwoDigits = Math.abs(value % 100);
+    if (lastTwoDigits > 4 && lastTwoDigits < 21)
+        return RublesMainSwitch(form);
+    const lastDigit = Math.abs(value % 10);
+    if (lastDigit >= 2 && lastDigit <= 4) {
+        switch (form) {
+            case "nominative":
+            case "accusative":
+                return "рубля";
+            default:
+                return RublesMainSwitch(form);
+        }
+    }
+    if (lastDigit === 1) {
+        switch (form) {
+            case "nominative":
+            case "accusative":
+                return "рубль";
+            case "genitive":
+                return "рубля";
+            case "dative":
+                return "рублю";
+            case "ablative":
+                return "рублём";
+        }
+    }
+    return RublesMainSwitch(form);
+};

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { CanBeArray } from "./types.js";
+/**
+ * Добавляет ведущие нули к числу для достижения указанной длины
+ *
+ * @example pad(123, 5) => "00123"
+ */
+export declare const pad: (v: number, l?: number) => string;
+/**
+ * JSON-клонирование объектов посредством `JSON.parse(JSON.stringify(v))`
+ * Если значение не `object` вернётся как есть
+ */
+export declare const parsify: <T>(v: T) => T;
+/**
+ * Приведение значения к массиву
+ */
+export declare const arrayble: <T>(v: CanBeArray<T>) => T[];
+/**
+ * Тип разделения для функции {@link partition}
+ */
+export interface Partition<T> {
+    /**
+     * Элементы, удовлетворяющие условию
+     */
+    result: T[];
+    /**
+     * Исключённые элементы
+     */
+    excluded: T[];
+}
+/**
+ * Разделяет массив на два по условию
+ */
+export declare const partition: <T>(arr: T[], filter: (item: T) => boolean, initial?: Partition<T>) => Partition<T>;

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Добавляет ведущие нули к числу для достижения указанной длины
+ *
+ * @example pad(123, 5) => "00123"
+ */
+export const pad = (v, l = 2) => String(v).padStart(l, "0");
+/**
+ * JSON-клонирование объектов посредством `JSON.parse(JSON.stringify(v))`
+ * Если значение не `object` вернётся как есть
+ */
+export const parsify = (v) => {
+    if (typeof v !== "object")
+        return v;
+    return JSON.parse(JSON.stringify(v));
+};
+/**
+ * Приведение значения к массиву
+ */
+export const arrayble = (v) => (Array.isArray(v) ? v : [v]);
+/**
+ * Разделяет массив на два по условию
+ */
+export const partition = (arr, filter, initial = { result: [], excluded: [] }) => arr.reduce((acc, item) => (acc[filter(item) ? "result" : "excluded"].push(item), acc), initial);

package/dist/queue.d.ts

@@ -0,0 +1,35 @@
+import type { Timestamp } from "./types.js";
+/**
+ * Абстрактный класс очереди
+ *
+ * @template T - Тип элементов в очереди
+ */
+export declare abstract class Queue<T> {
+    _queue: T[];
+    _delay: number;
+    private timeout;
+    /**
+     * @param [delay=25] - Задержка (в миллисекундах) между обработкой элементов очереди
+     */
+    constructor(delay?: Timestamp);
+    /**
+     * Добавляет элемент в очередь и запускает обработку
+     *
+     * @param item - Элемент для добавления в очередь
+     */
+    protected push(item: T): void;
+    /**
+     * Запускает обработку очереди с задержкой
+     */
+    private run;
+    /**
+     * Метод для обработки элемента очереди
+     *
+     * @param item - Элемент для обработки
+     */
+    protected abstract handle(item: T): void;
+    /**
+     * Сброс очереди
+     */
+    reset(): void;
+}

package/dist/queue.js

@@ -0,0 +1,48 @@
+/**
+ * Абстрактный класс очереди
+ *
+ * @template T - Тип элементов в очереди
+ */
+export class Queue {
+    _queue = [];
+    _delay;
+    timeout = 0;
+    // noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+    /**
+     * @param [delay=25] - Задержка (в миллисекундах) между обработкой элементов очереди
+     */
+    constructor(delay = 25) {
+        this._delay = delay;
+    }
+    /**
+     * Добавляет элемент в очередь и запускает обработку
+     *
+     * @param item - Элемент для добавления в очередь
+     */
+    push(item) {
+        this._queue.push(item);
+        this.run();
+    }
+    /**
+     * Запускает обработку очереди с задержкой
+     */
+    run() {
+        this.reset();
+        this.timeout = setTimeout(() => {
+            if (this._queue.length === 0)
+                return this.reset();
+            const item = this._queue.shift();
+            this.handle(item);
+            this._queue.length > 0 ? this.run() : this.reset();
+        }, this._delay);
+    }
+    /**
+     * Сброс очереди
+     */
+    reset() {
+        if (this.timeout)
+            clearTimeout(this.timeout);
+        this.timeout = 0;
+        this._queue.length = 0;
+    }
+}

package/dist/string.d.ts

@@ -14,10 +14,30 @@ export declare const spaceRegExp: RegExp;
  * Заменяет все двойные, тройные и т. д. пробелы на один
  */
 export declare const spaceClean: (v?: string) => string;
+/**
+ * Очистка от плейсхолдеров
+ */
+export declare const clearPH: (str?: string, placeholder?: string | RegExp) => string;
 /**
  * Приводит первый символ слова к верхнему регистру
  */
 export declare const toCapital: (word?: string) => string;
+/**
+ * Приводит первый символ каждого слова к верхнему регистру
+ */
+export declare const toCapitalMap: (str?: string) => string;
+/**
+ * Повторяет строку указанное количество раз с разделителем
+ *
+ * @param {string} str - Исходная строка
+ * @param {number} length - Количество повторений
+ * @param {string} [separator=""] - Разделитель между повторениями (по умолчанию пустая строка)
+ */
+export declare const repeat: (str: string, length: number, separator?: string) => string;
+/**
+ * Приводит всё к нижнему регистру и корректирует пробелы
+ */
+export declare const toFlat: (str?: string) => string;
 /**
  * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
  */

package/dist/string.js

@@ -15,12 +15,33 @@ export const spaceRegExp = /\s+/g;
  * Заменяет все двойные, тройные и т. д. пробелы на один
  */
 export const spaceClean = (v = "") => v.replace(spaceRegExp, " ").trim();
+/**
+ * Очистка от плейсхолдеров
+ */
+export const clearPH = (str = "", placeholder = "_") => str.replaceAll(placeholder, "");
 //...
 /**
  * Приводит первый символ слова к верхнему регистру
  */
 export const toCapital = (word = "") => word.charAt(0).toUpperCase() + word.slice(1);
+/**
+ * Приводит первый символ каждого слова к верхнему регистру
+ */
+export const toCapitalMap = (str = "") => str.split(" ").map(toCapital).join(" ");
 //...
+/**
+ * Повторяет строку указанное количество раз с разделителем
+ *
+ * @param {string} str - Исходная строка
+ * @param {number} length - Количество повторений
+ * @param {string} [separator=""] - Разделитель между повторениями (по умолчанию пустая строка)
+ */
+export const repeat = (str, length, separator = "") => Array.from({ length }).fill(str).join(separator);
+//...
+/**
+ * Приводит всё к нижнему регистру и корректирует пробелы
+ */
+export const toFlat = (str = "") => spaceClean(str.toLowerCase());
 /**
  * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/helpers",
-	"version": "0.0.13",
+	"version": "0.0.19",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -15,6 +15,10 @@
 		"format": "prettier --write ./"
 	},
 	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
 		"./async": {
 			"types": "./dist/async.d.ts",
 			"default": "./dist/async.js"
@@ -27,6 +31,10 @@
 			"types": "./dist/clean.d.ts",
 			"default": "./dist/clean.js"
 		},
+		"./datetime": {
+			"types": "./dist/datetime.d.ts",
+			"default": "./dist/datetime.js"
+		},
 		"./explorer": {
 			"types": "./dist/explorer.d.ts",
 			"default": "./dist/explorer.js"
@@ -35,6 +43,18 @@
 			"types": "./dist/files.d.ts",
 			"default": "./dist/files.js"
 		},
+		"./format": {
+			"types": "./dist/format.d.ts",
+			"default": "./dist/format.js"
+		},
+		"./html": {
+			"types": "./dist/html.d.ts",
+			"default": "./dist/html.js"
+		},
+		"./humanly": {
+			"types": "./dist/humanly.d.ts",
+			"default": "./dist/humanly.js"
+		},
 		"./lens": {
 			"types": "./dist/lens.d.ts",
 			"default": "./dist/lens.js"
@@ -47,6 +67,10 @@
 			"types": "./dist/phymath.d.ts",
 			"default": "./dist/phymath.js"
 		},
+		"./queue": {
+			"types": "./dist/queue.d.ts",
+			"default": "./dist/queue.js"
+		},
 		"./random": {
 			"types": "./dist/random.d.ts",
 			"default": "./dist/random.js"
@@ -55,6 +79,10 @@
 			"types": "./dist/script.d.ts",
 			"default": "./dist/script.js"
 		},
+		"./string": {
+			"types": "./dist/string.d.ts",
+			"default": "./dist/string.js"
+		},
 		"./types": {
 			"types": "./dist/types.d.ts",
 			"default": "./dist/types.js"
@@ -64,10 +92,19 @@
 			"default": "./dist/url.js"
 		}
 	},
+	"peerDependencies": {
+		"zod": "^4.0.0"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		}
+	},
 	"dependencies": {
 		"@std/msgpack": "jsr:^1.0.0"
 	},
 	"devDependencies": {
-		"@nemigo/configs": "workspace:*"
+		"@nemigo/configs": "workspace:*",
+		"zod": "4.1.5"
 	}
 }