@nemigo/helpers 0.3.3 → 0.4.0

package/dist/cookie.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Параметры создания куки для {@link CookieCTX}
+ */
+export interface CookieParams {
+    /**
+     * Срок действия куки в днях
+     *
+     * @default 15
+     */
+    days?: number;
+    /**
+     * - Strict: Куки будут отправляться только при навигации внутри сайта
+     * - Lax: Куки доступны для навигации с одного сайта на другой
+     * - None: Куки доступны для всех запросов, требуется параметр Secure
+     *
+     * @default "Lax"
+     */
+    policy?: "Strict" | "Lax" | "None";
+}
+/**
+ * Серверные readonly-куки для {@link CookieCTX}
+ */
+export interface ServerCookie {
+    name: string;
+    value: string;
+}
+export interface ICookieCTX {
+    /**
+     * Инициализирует серверные куки
+     */
+    init(cookies: ServerCookie[]): void;
+    /**
+     * Устанавливает куку. На сервере игнорируется
+     */
+    set(name: string, value: string, params: CookieParams): void;
+    /**
+     * Получает значение куки по его названию
+     *
+     * @param name - Название куки
+     * @returns Значение куки или undefined, если кука не найдена
+     */
+    get(name: string): string | undefined;
+    /**
+     * Удаляет куку по имени. На сервере игнорируется
+     */
+    delete(name: string): void;
+    /**
+     * Очищает серверные куки
+     */
+    clear(): void;
+}
+export declare class CookieCTX implements ICookieCTX {
+    private server;
+    constructor(cookies?: ServerCookie[]);
+    init(cookies?: ServerCookie[]): void;
+    get(name: string): string | undefined;
+    set(name: string, value: string, params?: CookieParams): void;
+    delete(name: string): void;
+    clear(): void;
+}

package/dist/cookie.js

@@ -0,0 +1,48 @@
+import { isSSR } from "./html.js";
+export class CookieCTX {
+    server = new Map();
+    constructor(cookies) {
+        this.init(cookies);
+    }
+    init(cookies = []) {
+        for (const item of cookies)
+            this.server.set(item.name, item.value);
+    }
+    get(name) {
+        const encoded = encodeURIComponent(name);
+        if (isSSR)
+            return this.server.get(encoded);
+        const key = encoded + "=";
+        const cookies = document.cookie.split(";");
+        for (const item of cookies) {
+            const cookie = item.trim();
+            if (cookie.startsWith(key)) {
+                const value = cookie.substring(key.length);
+                return decodeURIComponent(value);
+            }
+        }
+    }
+    set(name, value, params = {}) {
+        if (isSSR)
+            return;
+        const { days = 15, policy = "Lax" } = params;
+        const date = new Date();
+        date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
+        const expires = `expires=${date.toUTCString()}`;
+        const encoded = {
+            name: encodeURIComponent(name),
+            value: encodeURIComponent(value),
+        };
+        const result = `${encoded.name}=${encoded.value};${expires};path=/;SameSite=${policy}`;
+        document.cookie = policy === "None" ? result + ";Secure" : result;
+    }
+    delete(name) {
+        if (isSSR)
+            return;
+        const encodedName = encodeURIComponent(name);
+        document.cookie = `${encodedName}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`;
+    }
+    clear() {
+        this.server.clear();
+    }
+}

package/dist/datetime.js

@@ -99,9 +99,7 @@ export const formatDateTime = (datetime = Date.now(), format = "DD.DM.DY TH:TM")
  * const timestamp = toTimeStamp("11.02.2012", "13:45");
  * console.log(timestamp); // Выведет {@link Timestamp} для "11.02.2012 13:45"
  */
-export const toTimeStamp = 
-// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-(date, time = "00:00") => {
+export const toTimeStamp = (date, time = "00:00") => {
     const [day, month, year] = date.split(".").map(Number);
     const [hours, minutes] = time.split(":").map(Number);
     // Проверка на корректность ввода (если хотя бы одно значение не число)

package/dist/emitter.d.ts

@@ -0,0 +1,28 @@
+import { Promoter } from "./promoter.js";
+import type { RID } from "./types.js";
+/**
+ * Класс `Emitter` реализует простую систему событийного взаимодействия.
+ * Позволяет подписываться на события, уведомлять и удалять обработчики
+ *
+ * @template Events - Схема событий вида `{ [key]: data }`
+ */
+export declare class Emitter<Events extends object> extends Promoter<{
+    type: keyof Events;
+    data: Events[keyof Events];
+}> {
+    /**
+     * Вызывает все обработчики, связанные с указанным событием
+     */
+    dispatch<K extends keyof Events>(target: K, data: Events[K]): void;
+    /**
+     * Добавляет обработчик для события
+     */
+    on<K extends keyof Events>(event: K, call: (data: Events[K]) => void, params?: {
+        key?: RID;
+        once?: boolean;
+    }): () => void;
+    /**
+     * Удаляет обработчик события по ключу. Если не указан, очищаются все обработчики
+     */
+    un(key?: RID): boolean;
+}

package/dist/emitter.js

@@ -0,0 +1,33 @@
+import { Promoter } from "./promoter.js";
+/**
+ * Класс `Emitter` реализует простую систему событийного взаимодействия.
+ * Позволяет подписываться на события, уведомлять и удалять обработчики
+ *
+ * @template Events - Схема событий вида `{ [key]: data }`
+ */
+export class Emitter extends Promoter {
+    /**
+     * Вызывает все обработчики, связанные с указанным событием
+     */
+    dispatch(target, data) {
+        super.notify({ type: target, data });
+    }
+    /**
+     * Добавляет обработчик для события
+     */
+    on(event, call, params = {}) {
+        const { key = Symbol(), once } = params;
+        return super.sub((payload) => {
+            if (payload.type === event) {
+                // @ts-expect-error <оно не может корректно сузить тип>
+                call(payload.data);
+            }
+        }, { key, once });
+    }
+    /**
+     * Удаляет обработчик события по ключу. Если не указан, очищаются все обработчики
+     */
+    un(key) {
+        return super.unsub(key);
+    }
+}

package/dist/explorer.d.ts

@@ -12,3 +12,69 @@ import type { PathLike, Stats } from "node:fs";
 declare function exists(path: PathLike, expected?: "file" | "folder", strict?: boolean): Promise<Stats | null>;
 declare function exists(path: PathLike, expected: "file" | "folder" | undefined, strict: true): Promise<Stats>;
 export { exists };
+/**
+ * Опции для функции {@link remove}
+ */
+export interface RemoveOptions {
+    /**
+     * Если `true` и это была не пустая папка, бросит ошибку.
+     * Параметр `expected` приводится к `"folder"`
+     *
+     * @default false
+     */
+    empty?: boolean;
+    /**
+     * Проверка перед удалением
+     *
+     * @default undefined
+     */
+    expected?: "file" | "folder";
+}
+/**
+ * Удаляет файл или папку по указанному пути
+ *
+ * @param path - Путь к файлу или папке
+ * @param options - Опции поведения {@link RemoveOptions}
+ *
+ * @returns {@link Stats}, если путь существовал и был удалён, иначе `null`
+ * @throws {Error} Если путь не существует или не соответствует ожидаемому типу
+ */
+export declare function remove(path: PathLike, options?: RemoveOptions): Promise<Stats | null>;
+/**
+ * Опции для функции {@link remake}
+ */
+export interface RemakeOptions {
+    /**
+     * Если `true` и это была не пустая папка, бросит ошибку
+     *
+     * @default false
+     */
+    empty?: boolean;
+    /**
+     * Если `false` и нет родительской папки, бросит ошибку
+     *
+     * @default true
+     */
+    recursive?: boolean;
+}
+/**
+ * Удаляет (если существовала) и заново создаёт папку по указанному пути
+ *
+ * @param path - Путь к папке
+ * @param options - Опции поведения {@link RemakeOptions}
+ *
+ * @returns {@link Stats}, если папка существовала и была удалена, иначе `null`
+ * @throws {Error} Если путь не существует или не является папкой
+ */
+export declare function remake(path: PathLike, options?: RemakeOptions): Promise<Stats | null>;
+/**
+ * Сравнивает содержимое файла с ожидаемым значением
+ *
+ * @param path - Путь к файлу
+ * @param expected - Ожидаемое содержимое файла
+ * @param [strict=true] - Если `true`, выбрасывает ошибку, если файл не существует. Если `false`, возвращает `false`
+ *
+ * @returns `true`, если содержимое файла совпадает с ожидаемым, иначе `false`
+ * @throws {Error} Если `strict = true` и файл не существует
+ */
+export declare function compare(path: PathLike, expected: string, strict?: boolean): Promise<boolean>;

package/dist/explorer.js

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 async function exists(path, expected, strict = false) {
     let existed;
     try {
@@ -19,3 +19,65 @@ async function exists(path, expected, strict = false) {
     return existed;
 }
 export { exists };
+/**
+ * Удаляет файл или папку по указанному пути
+ *
+ * @param path - Путь к файлу или папке
+ * @param options - Опции поведения {@link RemoveOptions}
+ *
+ * @returns {@link Stats}, если путь существовал и был удалён, иначе `null`
+ * @throws {Error} Если путь не существует или не соответствует ожидаемому типу
+ */
+export async function remove(path, options = {}) {
+    const { empty = false, expected } = options;
+    let existed;
+    if (empty) {
+        existed = await exists(path, "folder");
+        if (!existed)
+            return null;
+        const entries = await readdir(path, { withFileTypes: true });
+        if (entries.length > 0) {
+            throw new Error(`Ожидалось, что папка "${path}" будет пуста`);
+        }
+    }
+    else {
+        existed = await exists(path, expected);
+        if (!existed)
+            return null;
+    }
+    await rm(path, { recursive: true });
+    return existed;
+}
+/**
+ * Удаляет (если существовала) и заново создаёт папку по указанному пути
+ *
+ * @param path - Путь к папке
+ * @param options - Опции поведения {@link RemakeOptions}
+ *
+ * @returns {@link Stats}, если папка существовала и была удалена, иначе `null`
+ * @throws {Error} Если путь не существует или не является папкой
+ */
+export async function remake(path, options = {}) {
+    const { empty = false, recursive = true } = options;
+    const existed = await remove(path, { empty, expected: "folder" });
+    await mkdir(path, { recursive });
+    return existed;
+}
+//...
+/**
+ * Сравнивает содержимое файла с ожидаемым значением
+ *
+ * @param path - Путь к файлу
+ * @param expected - Ожидаемое содержимое файла
+ * @param [strict=true] - Если `true`, выбрасывает ошибку, если файл не существует. Если `false`, возвращает `false`
+ *
+ * @returns `true`, если содержимое файла совпадает с ожидаемым, иначе `false`
+ * @throws {Error} Если `strict = true` и файл не существует
+ */
+export async function compare(path, expected, strict = true) {
+    const existed = await exists(path, "file", strict);
+    if (!existed)
+        return false;
+    const content = await readFile(path, "utf-8");
+    return content === expected;
+}

package/dist/files.d.ts

@@ -1 +1,14 @@
 export declare const fileToBase64: (file: File) => Promise<string>;
+/**
+ * Проверяет, является ли файл изображением (исключая SVG)
+ *
+ * @para file - Объект файла
+ * @returns true, если файл является изображением
+ */
+export declare const isImage: (file: File) => boolean;
+/**
+ * Преобразует размер файла в человекочитаемый формат
+ *
+ * @param size - Размер файла в байтах
+ */
+export declare const getFileSize: (size: number) => string;

package/dist/files.js

@@ -4,3 +4,38 @@ export const fileToBase64 = (file) => new Promise((resolve, reject) => {
     reader.onerror = reject;
     reader.readAsDataURL(file);
 });
+//...
+/**
+ * Проверяет, является ли файл изображением (исключая SVG)
+ *
+ * @para file - Объект файла
+ * @returns true, если файл является изображением
+ */
+export const isImage = (file) => file.type.startsWith("image/") && !file.type.includes("svg");
+//...
+const UNITS = [
+    "B",
+    "kB",
+    "MB",
+    "GB",
+    "TB",
+    "PB",
+    "EB",
+    "ZB",
+    "YB",
+];
+/**
+ * Преобразует размер файла в человекочитаемый формат
+ *
+ * @param size - Размер файла в байтах
+ */
+export const getFileSize = (size) => {
+    const bytes = Math.round(size);
+    if (bytes === 0)
+        return "0 B";
+    if (bytes < 1000)
+        return bytes.toString() + " B";
+    const exponent = Math.min(Math.floor(Math.log10(bytes) / 3), UNITS.length - 1);
+    const result = bytes / 1000 ** exponent;
+    return Math.round(result) + " " + UNITS[exponent];
+};

package/dist/future.d.ts

@@ -0,0 +1,50 @@
+import type { CanBePromise, RID, Timestamp } from "./types.js";
+/**
+ * Тип фьючерса: таймер или интервал
+ */
+export type FutureType = "timer" | "interval";
+/**
+ * Фьючерс для {@link Future}
+ */
+export interface FutureOptions {
+    /**
+     * Тип фьючерса
+     *
+     * @default {@link FutureType}
+     */
+    type?: FutureType;
+    /**
+     * Уникальный ключ фьючерса
+     */
+    key?: RID;
+    /**
+     * Задержка ({@link Timestamp}). Если не указана, используется значение по умолчанию
+     */
+    delay?: number;
+}
+/**
+ * Класс для управления таймерами и интервалами
+ */
+export declare class Future {
+    readonly delay: Timestamp;
+    /**
+     * @param [delay=5min] - Задержка по умолчанию
+     */
+    constructor(delay?: Timestamp);
+    private timers;
+    private intervals;
+    private get;
+    /**
+     * Очищает таймеры или интервалы
+     */
+    clear(type?: FutureType, key?: RID): void;
+    /**
+     * Сброс фьючерса
+     */
+    private reset;
+    /**
+     * Удаляет предыдущий фьючерс по ключу (если он был) и стартует новый.
+     * Функция будет обёрнута в {@link boundary} при вызове
+     */
+    run(call: () => CanBePromise, { type, key, delay }?: FutureOptions): void;
+}

package/dist/future.js

@@ -0,0 +1,59 @@
+//...
+/**
+ * Класс для управления таймерами и интервалами
+ */
+export class Future {
+    delay = 5 * 60 * 1000;
+    /**
+     * @param [delay=5min] - Задержка по умолчанию
+     */
+    constructor(delay = 5 * 60 * 1000) {
+        this.delay = delay;
+    }
+    timers = new Map();
+    intervals = new Map();
+    get(type) {
+        if (type === "timer")
+            return this.timers;
+        return this.intervals;
+    }
+    /**
+     * Очищает таймеры или интервалы
+     */
+    clear(type, key) {
+        if (type) {
+            const map = this.get(type);
+            key ? this.reset(type, map, key) : map.clear();
+        }
+        else {
+            this.timers.clear();
+            this.intervals.clear();
+        }
+    }
+    /**
+     * Сброс фьючерса
+     */
+    reset(type, map, key) {
+        const id = map.get(key);
+        if (!id)
+            return;
+        type === "timer" ? clearTimeout(id) : clearInterval(id);
+        map.delete(key);
+    }
+    /**
+     * Удаляет предыдущий фьючерс по ключу (если он был) и стартует новый.
+     * Функция будет обёрнута в {@link boundary} при вызове
+     */
+    run(call, { type = "timer", key = Symbol(), delay = this.delay } = {}) {
+        if (type === "timer") {
+            this.reset(type, this.timers, key);
+            const timer = setTimeout(call, delay);
+            this.timers.set(key, timer);
+        }
+        else {
+            this.reset(type, this.intervals, key);
+            const timer = setInterval(call, delay);
+            this.intervals.set(key, timer);
+        }
+    }
+}

package/dist/html.d.ts

@@ -49,6 +49,31 @@ export declare const unselect: () => void;
  * @returns Функция для удаления обработчика события
  */
 export declare const unselectByMousedown: () => (() => void);
+declare global {
+    interface WindowEventMap {
+        rescroll: CustomEvent;
+    }
+}
+/**
+ * Создаёт обработчик события "rescroll" для прокрутки элемента наверх с плавной анимацией
+ *
+ * @param {HTMLElement} [element=document.documentElement] - Элемент, для которого привязывается обработчик
+ * @param {EventListenerOptions} [options] - Дополнительные параметры
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export declare const createRescrollListener: (element?: HTMLElement, options?: EventListenerOptions) => (() => void);
+/**
+ * Генерирует и пробрасывает событие "rescroll" на указанный элемент или окно
+ *
+ * @param {HTMLElement | Window} [element=window] - Элемент или окно, на которое будет отправлено событие
+ * @returns {boolean} Возвращает результат метода dispatchEvent
+ */
+export declare const rescrollDispatch: (element?: HTMLElement | Window) => boolean;
+/**
+ * Автоматически изменяет высоту текстового поля (`textarea`) в зависимости от его содержимого
+ */
+export declare const autoAreaHeight: (area?: HTMLTextAreaElement) => void;
 /**
  * Преобразование `{@link FormData}` в объект
  *

package/dist/html.js

@@ -84,6 +84,37 @@ export const unselect = () => document.getSelection()?.removeAllRanges();
  * @returns Функция для удаления обработчика события
  */
 export const unselectByMousedown = () => createEventListener("mousedown", unselect, { once: true });
+/**
+ * Создаёт обработчик события "rescroll" для прокрутки элемента наверх с плавной анимацией
+ *
+ * @param {HTMLElement} [element=document.documentElement] - Элемент, для которого привязывается обработчик
+ * @param {EventListenerOptions} [options] - Дополнительные параметры
+ *
+ * @returns Функция для удаления обработчика события
+ */
+export const createRescrollListener = (element = document.documentElement, options) => createEventListener("rescroll", 
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+() => element?.scrollTo?.({ top: 0, behavior: "smooth" }), options);
+/**
+ * Генерирует и пробрасывает событие "rescroll" на указанный элемент или окно
+ *
+ * @param {HTMLElement | Window} [element=window] - Элемент или окно, на которое будет отправлено событие
+ * @returns {boolean} Возвращает результат метода dispatchEvent
+ */
+export const rescrollDispatch = (element = window) => 
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+element?.dispatchEvent?.(new CustomEvent("rescroll"));
+//...
+/**
+ * Автоматически изменяет высоту текстового поля (`textarea`) в зависимости от его содержимого
+ */
+export const autoAreaHeight = (area) => {
+    if (!area)
+        return;
+    area.style.height = "auto";
+    area.style.height = `${area.scrollHeight}px`;
+    area.scrollTop = area.scrollHeight;
+};
 //...
 /**
  * Преобразование `{@link FormData}` в объект

package/dist/humanly.d.ts

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

package/dist/humanly.js

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

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export declare const parsify: <T>(v: T) => T;
  * Приведение значения к массиву
  */
 export declare const arrayble: <T>(v: CanBeArray<T>) => T[];
+export declare const isObject: (obj: unknown) => obj is object;
+export declare const isSameType: <A = unknown>(a: A, b: unknown) => b is A;
 /**
  * Тип разделения для функции {@link partition}
  */
@@ -31,3 +33,17 @@ export interface Partition<T> {
  * Разделяет массив на два по условию
  */
 export declare const partition: <T>(arr: T[], filter: (item: T) => boolean, initial?: Partition<T>) => Partition<T>;
+/**
+ * Удаляет `null` и `undefined` и оставляет только уникальные строки
+ */
+export declare const setify: (arr: (string | undefined | null)[]) => string[];
+/**
+ * Удаляет дубликаты объектов из массива на основе указанного ключа
+ *
+ * @template T - Тип элементов массива
+ * @template K - Ключ объекта, по которому определяется уникальность
+ * @param {T[]} arr - Исходный массив объектов
+ * @param {K} [key="id"] - Ключ, по которому будут удаляться дубликаты
+ * @returns {T[]} Новый массив без дубликатов
+ */
+export declare const unify: <T, K extends keyof T>(arr: T[], key?: K) => T[];

package/dist/index.js

@@ -17,7 +17,25 @@ export const parsify = (v) => {
  * Приведение значения к массиву
  */
 export const arrayble = (v) => (Array.isArray(v) ? v : [v]);
+//...
+export const isObject = (obj) => obj !== null && typeof obj === "object";
+export const isSameType = (a, b) => Object.prototype.toString.call(a) === Object.prototype.toString.call(b);
 /**
  * Разделяет массив на два по условию
  */
 export const partition = (arr, filter, initial = { result: [], excluded: [] }) => arr.reduce((acc, item) => (acc[filter(item) ? "result" : "excluded"].push(item), acc), initial);
+//...
+/**
+ * Удаляет `null` и `undefined` и оставляет только уникальные строки
+ */
+export const setify = (arr) => [...new Set(arr.filter((item) => typeof item === "string"))];
+/**
+ * Удаляет дубликаты объектов из массива на основе указанного ключа
+ *
+ * @template T - Тип элементов массива
+ * @template K - Ключ объекта, по которому определяется уникальность
+ * @param {T[]} arr - Исходный массив объектов
+ * @param {K} [key="id"] - Ключ, по которому будут удаляться дубликаты
+ * @returns {T[]} Новый массив без дубликатов
+ */
+export const unify = (arr, key = "id") => [...new Map(arr.map((item) => [item[key], item])).values()];