@nemigo/helpers 0.13.3 → 1.5.0

package/dist/types.d.ts

@@ -1,68 +1,187 @@
 export type * from "./phymath/types.js";
-import type { ZIP } from "./zipper.js";
-export type { ZIP };
+export type { ZIP } from "./zipper.js";
 /**
- * Дата и время в формате UNIX
+ * Просто алиас к {@link Parameters}
  */
-export type Timestamp = number;
+export type Args<F extends (...args: any[]) => any> = Parameters<F>;
+/**
+ * Просто алиас к {@link ReturnType}
+ */
+export type Return<F extends (...args: any[]) => any> = ReturnType<F>;
+/**
+ * Любая функция, полезна для дженириков
+ */
+export type AnyFunc = (...args: any[]) => any;
+/**
+ * Производная функция от {@link AnyFunc}, полезна для дженириков
+ */
+export type FuncCopy<F extends AnyFunc> = (...args: Args<F>) => Return<F>;
+/**
+ * Любая функция с `this`, полезна для дженириков
+ */
+export type AnyThisFunc<This> = (this: This, ...args: any[]) => any;
 /**
- * Идентификатор чего-либо для рантайма (например, для кэша)
+ * Производная функция от {@link AnyThisFunc}, полезна для дженириков
+ */
+export type ThisFuncCopy<This, F extends AnyThisFunc<This>> = (this: This, ...args: Args<F>) => Return<F>;
+/**
+ * Идентификатор чего-либо для использования в рантайме (например, для кэша или ключей Map/Set)
  */
 export type RID = string | number | symbol;
 /**
- * Обобщённый тип таймеров
+ * Значение, которое может быть сериализовано в JSON
  */
-export type TimeoutType = ReturnType<typeof setTimeout>;
+export type Serializable = object | null | string | number | boolean;
 /**
- * Обобщённый тип интервалов
+ * Интерфейс всех состояний
  */
-export type IntervalType = ReturnType<typeof setInterval>;
+export interface IState<V> {
+    get(): V;
+    set(v: V): void;
+}
 /**
- * Массив в массиве
+ * Интерфейс для хранения чего-нибудь
  */
-export type Matrix<T = unknown> = T[][];
+export interface Dictionary<K = any, V = any> {
+    get(key: K): V | undefined;
+    set(key: K, v: V): void;
+}
 /**
- * Значение может быть `null` или `undefined`
+ * Дата и время в формате Unix (количество миллисекунд с 1 января 1970 года)
+ */
+export type Timestamp = number;
+/**
+ * Все форматы даты и времени
+ */
+export type DateTime = Date | Timestamp | string;
+/**
+ * Расширенный {@link Timestamp} с информацией о часовом поясе (обычно в котором надо отобразить)
+ *
+ * @example
+ * ```typescript
+ * // Московское время (UTC+3)
+ * { zone: 3, stamp: 1703510400000 }
+ *
+ * // Тихоокеанское время (UTC-8)
+ * { zone: -8, stamp: 1703510400000 }
+ * ```
+ */
+export interface ZoneStamp {
+    /**
+     * Часовой пояс в формате смещения от UTC (в часах)
+     */
+    zone: number;
+    /**
+     * Дата и время в формате {@link Timestamp}
+     */
+    stamp: Timestamp;
+}
+/**
+ * Обобщённый тип таймеров (возвращаемое значение {@link setTimeout})
+ */
+export type TimeoutType = Return<typeof setTimeout>;
+/**
+ * Обобщённый тип интервалов (возвращаемое значение {@link setInterval})
+ */
+export type IntervalType = Return<typeof setInterval>;
+/**
+ * Получение типа элемента массива
+ *
+ * @example
+ * ```typescript
+ * type NumbersArray = number[];
+ * type NumberElement = ArrayElement<NumbersArray>; // number
+ *
+ * type UsersArray = User[];
+ * type UserElement = ArrayElement<UsersArray>; // User
+ *
+ * type Mixed = ArrayElement<(string | number)[]>; // string | number
+ * ```
+ */
+export type ArrayElement<T> = T extends (infer U)[] ? U : never;
+/**
+ * Массив с ожидаемым `length` для построения других дженериков
+ *
+ * @remarks Это не совсем настоящий кортеж, совмещайте с настоящим для полноценной типизации
+ *
+ * @example
+ * ```typescript
+ * type Vector2D = [number, number] | Cortege<2>;
+ * ```
+ */
+export type Cortege<L extends number, V = number> = {
+    length: L;
+} & Array<V>;
+/**
+ * Двумерный массив (массив в массиве)
  */
-export type CanBeNullable<T = unknown> = T | null | undefined;
+export type Matrix<V = unknown> = V[][];
 /**
  * Значение может быть массивом или одиночным элементом
  */
-export type CanBeArray<T = unknown> = T | T[];
+export type CanBeArray<V = unknown> = V | V[];
 /**
  * Массив может быть readonly
  */
-export type CanBeReadonly<T = unknown> = readonly T[] | T[];
+export type CanBeReadonlyArray<V = unknown> = readonly V[] | V[];
 /**
- * Значение может быть промиссом
+ * Значение может быть `null` или `undefined`
  */
-export type CanBePromise<T = unknown> = T | Promise<T>;
+export type CanBeNullable<V = unknown> = V | null | undefined;
 /**
- * Исключение `undefined`
+ * Значение может быть промисом
+ */
+export type CanBePromise<V = void> = V | Promise<V>;
+/**
+ * Исключает `undefined` из типа
  */
 export type Exist<T> = Exclude<T, undefined>;
 /**
- * Только строковые ключи объектов
+ * Получение только строковых ключей
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   func: () => Iterator<string>;
+ * }
+ *
+ * type UserKeys = KEYS<User>; // "id" | "name"
+ * ```
  */
 export type KEYS<O> = keyof O extends infer Key ? (Key extends string ? Key : never) : never;
+/**
+ * Примитив для всех записей с идентификатором
+ */
+export interface RecordPrimitive {
+    /**
+     * Уникальный идентификатор записи:
+     * - UID, если запись из БД
+     * - {@link ZIP}, если генерируется из данных записи
+     * - Возможны иные варианты по контексту
+     */
+    id: string;
+}
 /**
  * Рекурсивный {@link Partial}
+ *
+ * @remarks Криво работает с функциональными методами и **НЕ** имеет защиты от бесконечных рекурсий
  */
 export type DeepPartial<O> = {
     [K in keyof O]?: O[K] extends object | undefined ? DeepPartial<O[K]> : O[K];
 };
 /**
  * Рекурсивный {@link Required}
+ *
+ * @remarks Криво работает с функциональными методами и **НЕ** имеет защиты от бесконечных рекурсий
  */
 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 - по убыванию
+ * Направление сортировки:
+ * - `ASC` — по возрастанию
+ * - `DESC` — по убыванию
  */
 export type SortDirection = "ASC" | "DESC";

package/dist/url/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Извлекает доменную часть ({@link URL.origin})
+ */
+export declare const extractUrlOrigin: (url: URL | string) => string;
+/**
+ * Возвращает текущий URL из {@link window.location}
+ */
+export declare const getCurrentUrl: () => URL;
+/**
+ * Преобразует абсолютный URL в относительный (без {@link URL.origin})
+ */
+export declare const toRelativeUrl: (url: URL) => string;

package/dist/url/index.js

@@ -0,0 +1,17 @@
+/**
+ * Извлекает доменную часть ({@link URL.origin})
+ */
+export const extractUrlOrigin = (url) => {
+    if (url instanceof URL)
+        return url.origin;
+    const { origin } = new URL(url);
+    return origin;
+};
+/**
+ * Возвращает текущий URL из {@link window.location}
+ */
+export const getCurrentUrl = () => new URL(window.location.href);
+/**
+ * Преобразует абсолютный URL в относительный (без {@link URL.origin})
+ */
+export const toRelativeUrl = (url) => url.toString().replace(url.origin, "");

package/dist/url/params.d.ts

@@ -0,0 +1,141 @@
+import type { CanBeNullable } from "../types.js";
+/**
+ * Возможные значения параметра для {@link pushUrlParams} и {@link clearUrlParams}
+ */
+export type UrlParamValue = CanBeNullable<string | number | boolean>;
+/**
+ * KV-параметры для URL для {@link pushUrlParams} и {@link clearUrlParams}
+ */
+export type UrlParamKV<V extends UrlParamValue = UrlParamValue> = {
+    key: string;
+    value?: V;
+};
+/**
+ * Параметры для URL для {@link pushUrlParams} и {@link clearUrlParams}
+ */
+export type UrlParams<V extends UrlParamValue = UrlParamValue> = CanBeNullable<string | UrlParamKV<V>>[];
+/**
+ * Добавляет параметры в URL
+ *
+ * Для каждого параметра из массива:
+ *
+ * - Если параметр равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, то в строке запроса добавляется параметр с ключом равным значению строки и значением `"true"`
+ * - Если параметр является объектом с ключом и значением, то, если значение не `undefined` и не является объектом, оно приводится к строке и
+ *   устанавливается в качестве значения
+ *
+ * **Небезопасное поведение (unsafe=true):**
+ *
+ * - При передаче параметра типа `string` он добавляется как `?param1&param2` (без значения)
+ * - При передаче параметра, значение которого равно `true` или пустой строке, параметр добавляется без значения
+ * - Автоматически очищает пустые значения (`=&` → `&`, `param=` → `param`)
+ *
+ * @param url - URL, в который будут добавлены параметры
+ * @param params - Массив параметров
+ * @param [unsafe=false] - Небезопасное поведение
+ *
+ * @example
+ * ```typescript
+ * const url = new URL("https://example.com");
+ *
+ * // Безопасное поведение (по умолчанию)
+ * pushUrlParams(url, [
+ *   "sort",
+ *   { key: "page", value: 1 },
+ *   { key: "search", value: "hello" }
+ * ]);
+ * // Результат: https://example.com?sort=true&page=1&search=hello
+ *
+ * // Небезопасное поведение
+ * pushUrlParams(url, [
+ *   "sort",
+ *   { key: "filter", value: true },
+ *   { key: "empty", value: "" }
+ * ], true);
+ * // Результат: https://example.com?sort&filter&empty
+ *
+ * // Смешанные параметры
+ * pushUrlParams(url, [
+ *   "active",
+ *   { key: "id", value: 123 },
+ *   { key: "debug", value: false },
+ *   null, // игнорируется
+ *   undefined // игнорируется
+ * ]);
+ * // Результат: https://example.com?active=true&id=123&debug=false
+ * ```
+ */
+export declare const pushUrlParams: (url: URL, params: UrlParams, unsafe?: boolean) => void;
+/**
+ * Строгий тип параметров для {@link pushUrlParams} (все поля обязательны)
+ */
+export type StrictPushUrlParams = Required<UrlParamKV<string | boolean | number>>[];
+/**
+ * Объединяет массивы параметров для {@link pushUrlParams} в один массив, исключая дубликаты
+ *
+ * При конфликте параметров с одинаковыми ключами:
+ * - Последнее значение имеет приоритет
+ * - Параметры без значений (`true`) заменяются на параметры со значениями
+ *
+ * @example
+ * ```typescript
+ * const params1 = ["sort", { key: "page", value: 1 }];
+ * const params2 = [{ key: "page", value: 2 }, { key: "filter", value: "active" }];
+ *
+ * const merged = mergePushUrlParams(params1, params2);
+ * // Результат: [
+ * //   { key: "sort", value: true },
+ * //   { key: "page", value: 2 },
+ * //   { key: "filter", value: "active" }
+ * // ]
+ * ```
+ */
+export declare const mergePushUrlParams: (...args: UrlParams[]) => StrictPushUrlParams;
+/**
+ * Удаляет из URL параметры
+ *
+ * Для каждого элемента массива:
+ *
+ * - Если параметр отсутствует или равен `null` или `undefined`, он пропускается
+ * - Если параметр имеет тип `string`, из URL удаляется параметр с таким именем
+ * - Если параметр является объектом с ключом (`key`), из URL удаляется параметр с этим ключом
+ *
+ * @example
+ * ```typescript
+ * const url = new URL("https://example.com?page=1&sort=name&filter=active");
+ *
+ * // Удаление параметров
+ * clearUrlParams(url, [
+ *   "page",
+ *   { key: "sort" },
+ *   { key: "nonexistent" } // безопасно игнорируется
+ * ]);
+ * // Результат: https://example.com?filter=active
+ *
+ * // Удаление всех параметров определенного типа
+ * clearUrlParams(url, [
+ *   "filter",
+ *   "search",
+ *   "category"
+ * ]);
+ * ```
+ */
+export declare const clearUrlParams: (url: URL, params: UrlParams) => void;
+/**
+ * Строгий тип параметров для {@link clearUrlParams} (только ключи)
+ */
+export type StrictClearUrlParams = string[];
+/**
+ * Объединяет массивы параметров для {@link clearUrlParams} в один массив, исключая дубликаты
+ *
+ * @example
+ * ```typescript
+ * const params1 = ["page", "sort"];
+ * const params2 = ["sort", "filter"]; // дубликат "sort" будет удален
+ * const params3 = [{ key: "search" }];
+ *
+ * const merged = mergeClearUrlParams(params1, params2, params3);
+ * // Результат: ["page", "sort", "filter", "search"]
+ * ```
+ */
+export declare const mergeClearUrlParams: (...args: UrlParams[]) => StrictClearUrlParams;

package/dist/{url.js → url/params.js}

@@ -3,24 +3,59 @@
  * Добавляет параметры в URL
  *
  * Для каждого параметра из массива:
+ *
  * - Если параметр равен `null` или `undefined`, он пропускается
  * - Если параметр имеет тип `string`, то в строке запроса добавляется параметр с ключом равным значению строки и значением `"true"`
- * - Если параметр является объектом с ключом и значением, то, если значение не `undefined` и не является объектом, оно приводится к строке и устанавливается в качестве значения
+ * - Если параметр является объектом с ключом и значением, то, если значение не `undefined` и не является объектом, оно приводится к строке и
+ *   устанавливается в качестве значения
+ *
+ * **Небезопасное поведение (unsafe=true):**
  *
- * **Небезопасное поведение:**
- * - При передаче параметра типа `string` он добавляется как `?param1&param2` (без значения, то есть без `true`)
+ * - При передаче параметра типа `string` он добавляется как `?param1&param2` (без значения)
  * - При передаче параметра, значение которого равно `true` или пустой строке, параметр добавляется без значения
+ * - Автоматически очищает пустые значения (`=&` → `&`, `param=` → `param`)
  *
  * @param url - URL, в который будут добавлены параметры
  * @param params - Массив параметров
  * @param [unsafe=false] - Небезопасное поведение
+ *
+ * @example
+ * ```typescript
+ * const url = new URL("https://example.com");
+ *
+ * // Безопасное поведение (по умолчанию)
+ * pushUrlParams(url, [
+ *   "sort",
+ *   { key: "page", value: 1 },
+ *   { key: "search", value: "hello" }
+ * ]);
+ * // Результат: https://example.com?sort=true&page=1&search=hello
+ *
+ * // Небезопасное поведение
+ * pushUrlParams(url, [
+ *   "sort",
+ *   { key: "filter", value: true },
+ *   { key: "empty", value: "" }
+ * ], true);
+ * // Результат: https://example.com?sort&filter&empty
+ *
+ * // Смешанные параметры
+ * pushUrlParams(url, [
+ *   "active",
+ *   { key: "id", value: 123 },
+ *   { key: "debug", value: false },
+ *   null, // игнорируется
+ *   undefined // игнорируется
+ * ]);
+ * // Результат: https://example.com?active=true&id=123&debug=false
+ * ```
  */
-export const pushParams = (url, params, unsafe = false) => {
+export const pushUrlParams = (url, params, unsafe = false) => {
     for (const param of params) {
         if (!param)
             continue;
         if (typeof param === "string") {
-            // Если unsafe === true, добавляем параметр без значения, иначе - как "true"
+            // Если unsafe === true, добавляем параметр без значения, иначе — как "true"
             url.searchParams.set(param, unsafe ? "" : "true");
             continue;
         }
@@ -44,15 +79,28 @@ export const pushParams = (url, params, unsafe = false) => {
         }
         url.href = splitted.join("?");
     }
-    return url;
 };
 /**
- * Объединяет массивы параметров для {@link pushParams} в один массив, исключая дубликаты
+ * Объединяет массивы параметров для {@link pushUrlParams} в один массив, исключая дубликаты
  *
- * @param args - Массивы параметров для объединения
- * @returns Массив параметров без дубликатов
+ * При конфликте параметров с одинаковыми ключами:
+ * - Последнее значение имеет приоритет
+ * - Параметры без значений (`true`) заменяются на параметры со значениями
+ *
+ * @example
+ * ```typescript
+ * const params1 = ["sort", { key: "page", value: 1 }];
+ * const params2 = [{ key: "page", value: 2 }, { key: "filter", value: "active" }];
+ *
+ * const merged = mergePushUrlParams(params1, params2);
+ * // Результат: [
+ * //   { key: "sort", value: true },
+ * //   { key: "page", value: 2 },
+ * //   { key: "filter", value: "active" }
+ * // ]
+ * ```
  */
-export const mergePushParams = (...args) => {
+export const mergePushUrlParams = (...args) => {
     const acc = [];
     for (const params of args) {
         for (const param of params) {
@@ -92,14 +140,32 @@ export const mergePushParams = (...args) => {
  * Удаляет из URL параметры
  *
  * Для каждого элемента массива:
+ *
  * - Если параметр отсутствует или равен `null` или `undefined`, он пропускается
  * - Если параметр имеет тип `string`, из URL удаляется параметр с таким именем
  * - Если параметр является объектом с ключом (`key`), из URL удаляется параметр с этим ключом
  *
- * @param url - URL, из которого будут удалены параметры
- * @param params - Массив параметров для удаления
+ * @example
+ * ```typescript
+ * const url = new URL("https://example.com?page=1&sort=name&filter=active");
+ *
+ * // Удаление параметров
+ * clearUrlParams(url, [
+ *   "page",
+ *   { key: "sort" },
+ *   { key: "nonexistent" } // безопасно игнорируется
+ * ]);
+ * // Результат: https://example.com?filter=active
+ *
+ * // Удаление всех параметров определенного типа
+ * clearUrlParams(url, [
+ *   "filter",
+ *   "search",
+ *   "category"
+ * ]);
+ * ```
  */
-export const clearParams = (url, params) => {
+export const clearUrlParams = (url, params) => {
     for (const param of params) {
         if (!param)
             continue;
@@ -110,15 +176,21 @@ export const clearParams = (url, params) => {
         if (param.key)
             url.searchParams.delete(param.key);
     }
-    return url;
 };
 /**
- * Объединяет массивы параметров для {@link clearParams} в один массив, исключая дубликаты
+ * Объединяет массивы параметров для {@link clearUrlParams} в один массив, исключая дубликаты
+ *
+ * @example
+ * ```typescript
+ * const params1 = ["page", "sort"];
+ * const params2 = ["sort", "filter"]; // дубликат "sort" будет удален
+ * const params3 = [{ key: "search" }];
  *
- * @param args - Массивы параметров для объединения
- * @returns Массив параметров без дубликатов
+ * const merged = mergeClearUrlParams(params1, params2, params3);
+ * // Результат: ["page", "sort", "filter", "search"]
+ * ```
  */
-export const mergeClearParams = (...args) => {
+export const mergeClearUrlParams = (...args) => {
     const acc = [];
     for (const params of args) {
         for (const param of params) {

package/dist/url/slug.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Карта для транслитерации кириллических символов в латинские.
+ * Содержит соответствия для всех букв русского алфавита в нижнем регистре.
+ * Используется в функции {@link toSlug} для создания URL-friendly строк
+ *
+ * @example
+ * ```typescript
+ * cyrillicToLatinMap.get("а"); // "a"
+ * cyrillicToLatinMap.get("ё"); // "yo"
+ * cyrillicToLatinMap.get("ъ"); // ""
+ * ```
+ */
+export declare const cyrillicToLatinMap: Map<string, string>;
+/**
+ * Конвертирует кириллицу в латиницу, удаляет специальные символы, нормализует пробелы и заменяет их на разделитель
+ *
+ * @param str - Строка для преобразования в slug
+ * @param [separator="-"] - Разделитель для замены пробелов
+ *
+ * @example
+ * ```typescript
+ * toSlug("Привет, мир!"); // "privet-mir"
+ * toSlug("JavaScript Programming"); // "javascript-programming"
+ * toSlug("Café & Restaurant", "_"); // "cafe_restaurant"
+ * toSlug("Специальные символы!!!", "."); // "specialnye-simvoly"
+ * ```
+ */
+export declare const toSlug: (str: string, separator?: string) => string;