@nemigo/helpers 0.0.9 → 0.0.13

package/dist/async.d.ts

@@ -0,0 +1,42 @@
+import type { Timestamp } from "./types.js";
+/**
+ * Создаёт задержку на указанное количество миллисекунд
+ *
+ * @param ms - Количество миллисекунд для задержки
+ */
+export declare const delay: (ms: Timestamp) => Promise<void>;
+/**
+ * Создаёт debounce-функцию, которая откладывает выполнение до тех пор, пока не пройдёт указанное время без новых вызовов
+ *
+ * @param call - Функция для debounce
+ * @param delay - Задержка в миллисекундах
+ *
+ * @returns Функция с debounce
+ */
+export declare const debounce: <T extends (...args: any[]) => any>(call: T, delay: Timestamp) => ((...args: Parameters<T>) => void);
+/**
+ * Создаёт функцию-замыкание, которое гарантирует (старается), что переданная функция `call`
+ * будет вызвана не чаще одного раза в заданный интервал времени.
+ *
+ * mode = `"delay"`
+ *   - первый вызов откладывается на `ms`
+ *   - повторные вызовы до старта игнорируются, аргументы обновляются
+ *   - все ждут одного промисса
+ *
+ * mode = `"urgent"`:
+ *   - первый вызов исполняется сразу
+ *   - повторные вызовы возвращают тот же промиcс в течение `ms` (даже после завершения)
+ *   - после `ms` можно снова вызвать
+ */
+export declare const trottling: <F extends (...args: any[]) => any>(call: F, mode: "urgent" | "delay", ms: number) => ((...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>);
+/**
+ * Создаёт функцию-замыкание, которая гарантирует однократное выполнение асинхронной операции
+ *
+ * При первом вызове запускает переданный `call` и сохраняет его результат.
+ * Все последующие вызовы возвращают сохранённый результат без повторного выполнения операции.
+ * Если вызов происходит во время выполнения, возвращает тот же промисс, вместо создания нового
+ *
+ * @param call - Асинхронная функция, результат которой нужно кешировать
+ * @returns Функция, возвращающая закешированный результат после первого успешного выполнения
+ */
+export declare const createPromiseTrap: <T>(call: () => Promise<T>) => () => Promise<T>;

package/dist/async.js

@@ -0,0 +1,95 @@
+/**
+ * Создаёт задержку на указанное количество миллисекунд
+ *
+ * @param ms - Количество миллисекунд для задержки
+ */
+export const delay = (ms) => new Promise((ready) => setTimeout(ready, ms));
+//...
+/**
+ * Создаёт debounce-функцию, которая откладывает выполнение до тех пор, пока не пройдёт указанное время без новых вызовов
+ *
+ * @param call - Функция для debounce
+ * @param delay - Задержка в миллисекундах
+ *
+ * @returns Функция с debounce
+ */
+export const debounce = (call, delay) => {
+    let timeout;
+    return (...args) => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(() => call(...args), delay);
+    };
+};
+/**
+ * Создаёт функцию-замыкание, которое гарантирует (старается), что переданная функция `call`
+ * будет вызвана не чаще одного раза в заданный интервал времени.
+ *
+ * mode = `"delay"`
+ *   - первый вызов откладывается на `ms`
+ *   - повторные вызовы до старта игнорируются, аргументы обновляются
+ *   - все ждут одного промисса
+ *
+ * mode = `"urgent"`:
+ *   - первый вызов исполняется сразу
+ *   - повторные вызовы возвращают тот же промиcс в течение `ms` (даже после завершения)
+ *   - после `ms` можно снова вызвать
+ */
+export const trottling = (call, mode, ms) => {
+    let _promise = null;
+    let _args = [];
+    return (...args) => {
+        _args = args;
+        if (_promise)
+            return _promise;
+        let resolver;
+        let rejecter;
+        _promise = new Promise((resolve, reject) => {
+            resolver = resolve;
+            rejecter = reject;
+        });
+        const reset = () => (_promise = null);
+        if (mode === "delay") {
+            setTimeout(() => {
+                call(..._args)
+                    .then(resolver)
+                    .catch(rejecter)
+                    .finally(reset);
+            }, ms);
+        }
+        else {
+            call(..._args)
+                .then(resolver)
+                .catch(rejecter)
+                .finally(delay(ms).then(reset));
+        }
+        return _promise;
+    };
+};
+//...
+/**
+ * Создаёт функцию-замыкание, которая гарантирует однократное выполнение асинхронной операции
+ *
+ * При первом вызове запускает переданный `call` и сохраняет его результат.
+ * Все последующие вызовы возвращают сохранённый результат без повторного выполнения операции.
+ * Если вызов происходит во время выполнения, возвращает тот же промисс, вместо создания нового
+ *
+ * @param call - Асинхронная функция, результат которой нужно кешировать
+ * @returns Функция, возвращающая закешированный результат после первого успешного выполнения
+ */
+export const createPromiseTrap = (call) => {
+    const mark = Symbol();
+    let value = mark;
+    let promise = null;
+    return () => {
+        if (value !== mark)
+            return value;
+        if (!promise) {
+            promise = call().then((result) => {
+                value = result;
+                return result;
+            });
+        }
+        return promise;
+    };
+};

package/dist/files.d.ts

@@ -0,0 +1 @@
+export declare const fileToBase64: (file: File) => Promise<string>;

package/dist/files.js

@@ -0,0 +1,6 @@
+export const fileToBase64 = (file) => new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+});

package/dist/phymath.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Приведение -/+ 0 к 0
+ */
+export declare const toZero: (value: number) => number;
+/**
+ * Округляет число до заданного количества знаков после запятой
+ *
+ * Если переданное значение является `NaN` возвращает 0
+ *
+ * @param {number} value - Число для округления
+ * @param {number} [fraction=2] - Количество знаков после запятой
+ * @returns {number} Округленное число
+ */
+export declare const toRound: (value: number, fraction?: number) => number;
+/**
+ * Вычисляет сумму всех переданных аргументов
+ *
+ * Сумма округляется с использованием функции {@link toRound}
+ *
+ * @param {...number} args - Числа для суммирования
+ * @returns {number} Округленная сумма переданных чисел (или 0)
+ */
+export declare const sum: (...args: number[]) => number;
+/**
+ * Вычисляет произведение всех переданных аргументов
+ *
+ * Произведение округляется с использованием функции {@link toRound}
+ *
+ * @param {...number} args - Числа для перемножения.
+ * @returns {number} Округленное произведение переданных чисел (или 1)
+ */
+export declare const mult: (...args: number[]) => number;
+/**
+ * Ограничивает значение в заданном диапазоне [min, max]
+ *
+ * Если значение меньше min, вернёт min. Если больше max — вернёт max.
+ * Иначе возвращает само значение без изменений.
+ *
+ * @param {number} v - Исходное значение для ограничения
+ * @param {number} min - Нижняя граница диапазона
+ * @param {number} max - Верхняя граница диапазона
+ *
+ * @returns {number} Значение, ограниченное диапазоном [min, max]
+ */
+export declare const clamp: (v: number, min: number, max: number) => number;

package/dist/phymath.js

@@ -0,0 +1,50 @@
+/**
+ * Приведение -/+ 0 к 0
+ */
+export const toZero = (value) => (value === 0 ? 0 : value);
+/**
+ * Округляет число до заданного количества знаков после запятой
+ *
+ * Если переданное значение является `NaN` возвращает 0
+ *
+ * @param {number} value - Число для округления
+ * @param {number} [fraction=2] - Количество знаков после запятой
+ * @returns {number} Округленное число
+ */
+export const toRound = (value, fraction = 2) => {
+    if (isNaN(value) || value === 0)
+        return 0;
+    return Number(value.toFixed(fraction));
+};
+//...
+/**
+ * Вычисляет сумму всех переданных аргументов
+ *
+ * Сумма округляется с использованием функции {@link toRound}
+ *
+ * @param {...number} args - Числа для суммирования
+ * @returns {number} Округленная сумма переданных чисел (или 0)
+ */
+export const sum = (...args) => toRound(args.reduce((acc, v) => acc + v, 0));
+/**
+ * Вычисляет произведение всех переданных аргументов
+ *
+ * Произведение округляется с использованием функции {@link toRound}
+ *
+ * @param {...number} args - Числа для перемножения.
+ * @returns {number} Округленное произведение переданных чисел (или 1)
+ */
+export const mult = (...args) => toRound(args.reduce((acc, v) => acc * v, 1));
+/**
+ * Ограничивает значение в заданном диапазоне [min, max]
+ *
+ * Если значение меньше min, вернёт min. Если больше max — вернёт max.
+ * Иначе возвращает само значение без изменений.
+ *
+ * @param {number} v - Исходное значение для ограничения
+ * @param {number} min - Нижняя граница диапазона
+ * @param {number} max - Верхняя граница диапазона
+ *
+ * @returns {number} Значение, ограниченное диапазоном [min, max]
+ */
+export const clamp = (v, min, max) => Math.max(Math.min(v, max), min);

package/dist/string.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Регулярное выражение для захвата всех нецифровых символов из строки
+ */
+export declare const oDigitRegExp: RegExp;
+/**
+ * Чистка строки от всего, кроме цифр
+ */
+export declare const oDigitClean: (v?: string) => string;
+/**
+ * Регулярное выражение для захвата пробелов
+ */
+export declare const spaceRegExp: RegExp;
+/**
+ * Заменяет все двойные, тройные и т. д. пробелы на один
+ */
+export declare const spaceClean: (v?: string) => string;
+/**
+ * Приводит первый символ слова к верхнему регистру
+ */
+export declare const toCapital: (word?: string) => string;
+/**
+ * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
+ */
+export declare const cyrillicToLatinMap: Map<string, string>;
+/**
+ * Функция для создания *slug* (фрагмента URL) сущности
+ */
+export declare const toSlug: (text: string, separator?: string) => string;

package/dist/string.js

@@ -0,0 +1,96 @@
+/**
+ * Регулярное выражение для захвата всех нецифровых символов из строки
+ */
+export const oDigitRegExp = /\D/g;
+/**
+ * Чистка строки от всего, кроме цифр
+ */
+export const oDigitClean = (v = "") => v.replace(oDigitRegExp, "");
+//...
+/**
+ * Регулярное выражение для захвата пробелов
+ */
+export const spaceRegExp = /\s+/g;
+/**
+ * Заменяет все двойные, тройные и т. д. пробелы на один
+ */
+export const spaceClean = (v = "") => v.replace(spaceRegExp, " ").trim();
+//...
+/**
+ * Приводит первый символ слова к верхнему регистру
+ */
+export const toCapital = (word = "") => word.charAt(0).toUpperCase() + word.slice(1);
+//...
+/**
+ * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
+ */
+export const cyrillicToLatinMap = new Map([
+    ["а", "a"],
+    ["б", "b"],
+    ["в", "v"],
+    ["г", "g"],
+    ["д", "d"],
+    ["е", "e"],
+    ["ё", "yo"],
+    ["ж", "zh"],
+    ["з", "z"],
+    ["и", "i"],
+    ["й", "y"],
+    ["к", "k"],
+    ["л", "l"],
+    ["м", "m"],
+    ["н", "n"],
+    ["о", "o"],
+    ["п", "p"],
+    ["р", "r"],
+    ["с", "s"],
+    ["т", "t"],
+    ["у", "u"],
+    ["ф", "f"],
+    ["х", "h"],
+    ["ц", "ts"],
+    ["ч", "ch"],
+    ["ш", "sh"],
+    ["щ", "sch"],
+    ["ъ", ""],
+    ["ы", "y"],
+    ["ь", ""],
+    ["э", "e"],
+    ["ю", "yu"],
+    ["я", "ya"],
+]);
+/**
+ * Функция для создания *slug* (фрагмента URL) сущности
+ */
+export const toSlug = (text, separator = "-") => {
+    let acc = "";
+    let wasSpace = false;
+    for (const _char of text.split("")) {
+        const char = _char.toLowerCase();
+        const code = char.charCodeAt(0);
+        // Кириллица (а-я, ё)
+        if ((code >= 1072 && code <= 1103) || code === 1105) {
+            acc += cyrillicToLatinMap.get(char) || char;
+            wasSpace = false;
+        }
+        // Латиница (a-z)
+        else if (code >= 97 && code <= 122) {
+            acc += char;
+            wasSpace = false;
+        }
+        // Цифры (0-9)
+        else if (code >= 48 && code <= 57) {
+            acc += char;
+            wasSpace = false;
+        }
+        // Пробел или другие символы, которые нужно заменить на separator
+        else {
+            if (!wasSpace && acc.length > 0) {
+                acc += separator;
+                wasSpace = true;
+            }
+        }
+    }
+    // Убираем завершающий separator, если он есть
+    return acc.endsWith(separator) ? acc.slice(0, -1) : acc;
+};

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Дата и время в формате UNIX
+ */
+export type Timestamp = number;
+/**
+ * Идентификатор чего-либо для рантайма (например, для кэша)
+ */
+export type RID = string | number | symbol;
+/**
+ * Обобщённый тип таймеров
+ */
+export type TimeoutType = ReturnType<typeof setTimeout>;
+/**
+ * Обобщённый тип интервалов
+ */
+export type IntervalType = ReturnType<typeof setInterval>;
+/**
+ * Массив в массиве
+ */
+export type Matrix<T = unknown> = T[][];
+/**
+ * Значение может быть `null` или `undefined`
+ */
+export type CanBeNullable<T = unknown> = T | null | undefined;
+/**
+ * Значение может быть массивом или одиночным элементом
+ */
+export type CanBeArray<T = unknown> = T | T[];
+/**
+ * Значение может быть промиссом
+ */
+export type CanBePromise<T = unknown> = T | Promise<T>;
+/**
+ * Исключение `undefined`
+ */
+export type Exist<T> = Exclude<T, undefined>;
+/**
+ * Только строковые ключи объектов
+ */
+export type KEYS<O> = keyof O extends infer Key ? (Key extends string ? Key : never) : never;
+/**
+ * Рекурсивный {@link Partial}
+ */
+export type DeepPartial<O> = {
+    [K in keyof O]?: O[K] extends object | undefined ? DeepPartial<O[K]> : O[K];
+};
+/**
+ * Рекурсивный {@link Required}
+ */
+export type DeepRequired<O> = {
+    [K in keyof O]-?: O[K] extends object | undefined ? DeepRequired<NonNullable<O[K]>> : O[K];
+};
+/**
+ * Получение тип элемента массива
+ */
+export type ArrayElement<T> = T extends (infer U)[] ? U : never;
+/**
+ * - ASC - по возрастанию
+ * - DESC - по убыванию
+ */
+export type SortDirection = "ASC" | "DESC";

package/dist/types.js

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

package/dist/url.d.ts

@@ -0,0 +1,61 @@
+import type { CanBeNullable } from "./types.js";
+/**
+ * Возможные значения параметра для {@link pushParams} и {@link clearParams}
+ */
+export type ParamValue = CanBeNullable<string | number | boolean>;
+/**
+ * KV-параметры для URL для {@link pushParams} и {@link clearParams}
+ */
+export type ParamKV<V extends ParamValue = ParamValue> = {
+    key: string;
+    value?: V;
+};
+/**
+ * Параметры для URL для {@link pushParams} и {@link clearParams}
+ */
+export type Params<V extends ParamValue = ParamValue> = CanBeNullable<string | ParamKV<V>>[];
+/**
+ * Добавляет параметры в URL
+ *
+ * Для каждого параметра из массива:
+ * - Если параметр равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, то в строке запроса добавляется параметр с ключом равным значению строки и значением `"true"`
+ * - Если параметр является объектом с ключом и значением, то, если значение не `undefined` и не является объектом, оно приводится к строке и устанавливается в качестве значения
+ *
+ * **Небезопасное поведение:**
+ * - При передаче параметра типа `string` он добавляется как `?param1&param2` (без значения, то есть без `true`)
+ * - При передаче параметра, значение которого равно `true` или пустой строке, параметр добавляется без значения
+ *
+ * @param url - URL, в который будут добавлены параметры
+ * @param params - Массив параметров
+ * @param [unsafe=false] - Небезопасное поведение
+ */
+export declare const pushParams: (url: URL, params: Params, unsafe?: boolean) => URL;
+export type StrictPushParams = Required<ParamKV<string | boolean | number>>[];
+/**
+ * Объединяет массивы параметров для {@link pushParams} в один массив, исключая дубликаты
+ *
+ * @param args - Массивы параметров для объединения
+ * @returns Массив параметров без дубликатов
+ */
+export declare const mergePushParams: (...args: Params[]) => StrictPushParams;
+/**
+ * Удаляет из URL параметры
+ *
+ * Для каждого элемента массива:
+ * - Если параметр отсутствует или равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, из URL удаляется параметр с таким именем
+ * - Если параметр является объектом с ключом (`key`), из URL удаляется параметр с этим ключом
+ *
+ * @param url - URL, из которого будут удалены параметры
+ * @param params - Массив параметров для удаления
+ */
+export declare const clearParams: (url: URL, params: Params) => URL;
+export type StrictClearParams = string[];
+/**
+ * Объединяет массивы параметров для {@link clearParams} в один массив, исключая дубликаты
+ *
+ * @param args - Массивы параметров для объединения
+ * @returns Массив параметров без дубликатов
+ */
+export declare const mergeClearParams: (...args: Params[]) => StrictClearParams;

package/dist/url.js

@@ -0,0 +1,137 @@
+//...
+/**
+ * Добавляет параметры в URL
+ *
+ * Для каждого параметра из массива:
+ * - Если параметр равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, то в строке запроса добавляется параметр с ключом равным значению строки и значением `"true"`
+ * - Если параметр является объектом с ключом и значением, то, если значение не `undefined` и не является объектом, оно приводится к строке и устанавливается в качестве значения
+ *
+ * **Небезопасное поведение:**
+ * - При передаче параметра типа `string` он добавляется как `?param1&param2` (без значения, то есть без `true`)
+ * - При передаче параметра, значение которого равно `true` или пустой строке, параметр добавляется без значения
+ *
+ * @param url - URL, в который будут добавлены параметры
+ * @param params - Массив параметров
+ * @param [unsafe=false] - Небезопасное поведение
+ */
+export const pushParams = (url, params, unsafe = false) => {
+    for (const param of params) {
+        if (!param)
+            continue;
+        if (typeof param === "string") {
+            // Если unsafe === true, добавляем параметр без значения, иначе - как "true"
+            url.searchParams.set(param, unsafe ? "" : "true");
+            continue;
+        }
+        if (!param?.key)
+            continue;
+        if (typeof param.value !== "object") {
+            if (unsafe && (param?.value === undefined || param.value === true || param.value === "")) {
+                url.searchParams.set(param.key, "");
+            }
+            else {
+                url.searchParams.set(param.key, String(param.value));
+            }
+        }
+    }
+    if (unsafe) {
+        const splitted = url.href.split("?");
+        if (splitted[1]) {
+            splitted[1] = splitted[1].replaceAll("=&", "&");
+            if (splitted[1].endsWith("="))
+                splitted[1] = splitted[1].slice(0, splitted[1].length - 1);
+        }
+        url.href = splitted.join("?");
+    }
+    return url;
+};
+/**
+ * Объединяет массивы параметров для {@link pushParams} в один массив, исключая дубликаты
+ *
+ * @param args - Массивы параметров для объединения
+ * @returns Массив параметров без дубликатов
+ */
+export const mergePushParams = (...args) => {
+    const acc = [];
+    for (const params of args) {
+        for (const param of params) {
+            if (!param)
+                continue;
+            if (typeof param === "string") {
+                const existed = acc.find((v) => v.key === param);
+                if (existed)
+                    existed.value = true;
+                else
+                    acc.push({ key: param, value: true });
+                continue;
+            }
+            if (!param?.key)
+                continue;
+            if (typeof param?.value !== "object") {
+                const existed = acc.find((v) => v.key === param.key);
+                if (param.value === undefined || param.value === true || param.value === "") {
+                    if (existed)
+                        existed.value = true;
+                    else
+                        acc.push({ key: param.key, value: true });
+                }
+                else {
+                    if (existed)
+                        existed.value = String(param.value);
+                    else
+                        acc.push({ key: param.key, value: param.value });
+                }
+            }
+        }
+    }
+    return acc;
+};
+//...
+/**
+ * Удаляет из URL параметры
+ *
+ * Для каждого элемента массива:
+ * - Если параметр отсутствует или равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, из URL удаляется параметр с таким именем
+ * - Если параметр является объектом с ключом (`key`), из URL удаляется параметр с этим ключом
+ *
+ * @param url - URL, из которого будут удалены параметры
+ * @param params - Массив параметров для удаления
+ */
+export const clearParams = (url, params) => {
+    for (const param of params) {
+        if (!param)
+            continue;
+        if (typeof param === "string") {
+            url.searchParams.delete(param);
+            continue;
+        }
+        if (param?.key)
+            url.searchParams.delete(param.key);
+    }
+    return url;
+};
+/**
+ * Объединяет массивы параметров для {@link clearParams} в один массив, исключая дубликаты
+ *
+ * @param args - Массивы параметров для объединения
+ * @returns Массив параметров без дубликатов
+ */
+export const mergeClearParams = (...args) => {
+    const acc = [];
+    for (const params of args) {
+        for (const param of params) {
+            if (!param)
+                continue;
+            if (typeof param === "string") {
+                if (!acc.includes(param))
+                    acc.push(param);
+                continue;
+            }
+            if (param.key && !acc.includes(param.key))
+                acc.push(param.key);
+        }
+    }
+    return acc;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/helpers",
-	"version": "0.0.9",
+	"version": "0.0.13",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -15,6 +15,10 @@
 		"format": "prettier --write ./"
 	},
 	"exports": {
+		"./async": {
+			"types": "./dist/async.d.ts",
+			"default": "./dist/async.js"
+		},
 		"./cases": {
 			"types": "./dist/cases.d.ts",
 			"default": "./dist/cases.js"
@@ -27,6 +31,10 @@
 			"types": "./dist/explorer.d.ts",
 			"default": "./dist/explorer.js"
 		},
+		"./files": {
+			"types": "./dist/files.d.ts",
+			"default": "./dist/files.js"
+		},
 		"./lens": {
 			"types": "./dist/lens.d.ts",
 			"default": "./dist/lens.js"
@@ -35,6 +43,10 @@
 			"types": "./dist/msgpack.d.ts",
 			"default": "./dist/msgpack.js"
 		},
+		"./phymath": {
+			"types": "./dist/phymath.d.ts",
+			"default": "./dist/phymath.js"
+		},
 		"./random": {
 			"types": "./dist/random.d.ts",
 			"default": "./dist/random.js"
@@ -42,6 +54,14 @@
 		"./script": {
 			"types": "./dist/script.d.ts",
 			"default": "./dist/script.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts",
+			"default": "./dist/types.js"
+		},
+		"./url": {
+			"types": "./dist/url.d.ts",
+			"default": "./dist/url.js"
 		}
 	},
 	"dependencies": {