@nemigo/helpers 0.13.3 → 1.5.0

package/dist/async/index.js

@@ -1,93 +1,98 @@
+export const createManualPromise = () => {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { resolve, promise, reject };
+};
+//...
 /**
- * Создаёт задержку на указанное количество миллисекунд
+ * Создаёт промис, завершающийся через заданное время
+ *
+ * @param ms - Время задержки в миллисекундах
+ * @param [success=true] - Завершать успехом или отклонять
+ *
+ * @remarks При `success = false` промис отклоняется с ошибкой `"delay rejected"`
  */
-export const delay = (ms, success = true) => new Promise((resolve, reject) => setTimeout(success ? resolve : reject, ms));
+export const delay = (ms, success = true) => new Promise((resolve, reject) => setTimeout(() => (success ? resolve() : reject(new Error("delay rejected"))), ms));
 /**
  * Создаёт debounce-функцию, которая откладывает выполнение до тех пор, пока не пройдёт указанное время без новых вызовов
  *
- * @param call - Функция для debounce
- * @param delay - Задержка в миллисекундах
+ * @remarks Ошибки полностью игнорируются
+ * @remarks Если нужен результат, используйте {@link throttle}
  *
- * @returns Функция с debounce
+ * @example
+ * ```typescript
+ * const debouncedMethod = debounce(this.method.bind(this), 200);
+ * const debouncedFunc = debounce((value: string) => func(value), 300);
+ * ```
  */
-export const debounce = (call, delay) => {
+export const debounce = (func, ms) => {
     let timeout;
     return (...args) => {
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (timeout)
             clearTimeout(timeout);
-        timeout = setTimeout(() => call(...args), delay);
+        timeout = setTimeout(() => void func(...args), ms);
     };
 };
 /**
- * Создаёт функцию-замыкание, которое гарантирует (старается), что переданная функция `call`
- * будет вызвана не чаще одного раза в заданный интервал времени.
+ * Создаёт throttle-функцию, которая вызывает переданную функцию не чаще одного раза в заданный интервал времени
+ *
+ * @param func - Функция для троттлинга
+ * @param [mode="urgent"] - Режим троттлинга
+ * @param [ms=250] - Интервал времени в миллисекундах
  *
- * mode = `"delay"`
- *   - первый вызов откладывается на `ms`
- *   - повторные вызовы до старта игнорируются, аргументы обновляются
- *   - все ждут одного промисса
+ * @throws {unknown} Ошибки функции прокидываются в промис
  *
- * mode = `"urgent"`:
- *   - первый вызов исполняется сразу
- *   - повторные вызовы возвращают тот же промисс в течение `ms` (даже после завершения)
- *   - после `ms` можно снова вызвать
+ * @example
+ * ```typescript
+ * const throttledScroll = throttle((position) => saveScrollPosition(position), "delay", 100);
+ * window.addEventListener("scroll", () => void throttledScroll(window.scrollY)); // выполнится через 100 ms с самым последним scrollY
+ *
+ * const throttledFetch = throttle((id: string) => fetch(`/api/data/${id}`).then(r => r.json()), "urgent", 500);
+ * const result1 = await throttledFetch("123"); // Выполняется сразу с "123"
+ * const result2 = await throttledFetch("456"); // Возвращает тот же промис с "123"
+ * ```
  */
-export const throttle = (call, mode, ms) => {
-    let _promise = null;
+export const throttle = (func, mode = "urgent", ms = 250) => {
+    let _promise;
     let _args = [];
+    const call = async () => await func(..._args);
+    const reset = () => (_promise = null);
     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);
+        const { resolve, reject, promise } = createManualPromise();
+        _promise = promise;
         if (mode === "delay") {
             setTimeout(() => {
-                call(..._args)
-                    .then(resolver)
-                    .catch(rejecter)
-                    .finally(reset);
+                call().then(resolve).catch(reject).finally(reset);
             }, ms);
         }
         else {
-            call(..._args)
-                .then(resolver)
-                .catch(rejecter)
-                .finally(delay(ms).then(reset));
+            call()
+                .then(resolve)
+                .catch(reject)
+                .finally(() => void delay(ms).then(reset));
         }
         return _promise;
     };
 };
-//...
 /**
- * Создаёт функцию-замыкание, которая гарантирует однократное выполнение асинхронной операции
- *
- * При первом вызове запускает переданный `call` и сохраняет его результат.
- * Все последующие вызовы возвращают сохранённый результат без повторного выполнения операции.
- * Если вызов происходит во время выполнения, возвращает тот же промисс, вместо создания нового
- *
- * @param call - Асинхронная функция, результат которой нужно кешировать
- * @returns Функция, возвращающая закешированный результат после первого успешного выполнения
+ * Приведение коллбэка к промису с отловом ошибок и fallback-значением
  */
-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;
-            });
+export const boundary = async (func, fallback) => {
+    try {
+        return await func();
+    }
+    catch (e) {
+        if (typeof fallback === "function") {
+            // @ts-expect-error <тут не типизировать>
+            return fallback(e);
         }
-        return promise;
-    };
+        return fallback;
+    }
 };

package/dist/async/loader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Тип хука, возвращаемый методом {@link Loader.hook}
+ */
+export type LoaderHook = ReturnType<Loader["hook"]>;
+/**
+ * Менеджер состояния выполнения для асинхронных операций
+ *
+ * Отслеживает активность через очередь промисов: состояние `true`, пока есть незавершённые промисы.
+ * Использует версионирование, чтобы избежать гонок при быстрых последовательных вызовах
+ */
+export declare class Loader {
+    __heap: Promise<unknown>[];
+    __version: number;
+    __onchange: (v: boolean) => void;
+    constructor(onchange: (v: boolean) => void);
+    reset(): void;
+    __reset(version: number): void;
+    __check(version: number): void;
+    __awaiter(version: number): void;
+    /**
+     * Добавляет промис в очередь отслеживания
+     *
+     * @example
+     * ```typescript
+     * async function fetchData() {
+     *   const promise = fetch("/api/data");
+     *   loader.push(promise);
+     *   const data = await promise;
+     *   return data;
+     * }
+     * ```
+     */
+    push(promise: Promise<any>): void;
+    /**
+     * Создаёт хук: возвращает функцию, которая завершает отслеживание при вызове
+     *
+     * Внутри создаётся промис, добавляемый в очередь. Вызов возвращённой функции разрешает его
+     *
+     * @example
+     * ```typescript
+     * const complete = loader.hook();
+     * try {
+     *   await someAsyncOperation();
+     * } finally {
+     *   complete();
+     * }
+     * ```
+     */
+    hook(): () => void;
+    /**
+     * Выполняет функцию и автоматически отслеживает её промис
+     *
+     * @param func — Асинхронная функция для выполнения
+     * @param [external] — Опциональный коллбэк для синхронного уведомления о начале/завершении
+     *
+     * @throws {unknown} Ошибки промиса функции
+     *
+     * @example
+     * ```typescript
+     * async function fetchData() {
+     *   const data = await loader.run(() => fetch("/api/data"));
+     *   return data;
+     * }
+     * ```
+     */
+    run<T = any>(func: () => Promise<T>, external?: (v: boolean) => void): Promise<T>;
+}

package/dist/async/loader.js

@@ -0,0 +1,101 @@
+import { createManualPromise } from "./index.js";
+/**
+ * Менеджер состояния выполнения для асинхронных операций
+ *
+ * Отслеживает активность через очередь промисов: состояние `true`, пока есть незавершённые промисы.
+ * Использует версионирование, чтобы избежать гонок при быстрых последовательных вызовах
+ */
+export class Loader {
+    __heap = [];
+    __version = 0;
+    __onchange;
+    constructor(onchange) {
+        this.__onchange = onchange;
+    }
+    reset() {
+        this.__onchange(false);
+        this.__version = 0;
+        this.__heap = [];
+    }
+    //...
+    __reset(version) {
+        if (this.__version !== version)
+            return;
+        this.reset();
+    }
+    __check(version) {
+        if (this.__heap.length === 0)
+            return this.reset();
+        void Promise.allSettled(this.__heap).then(() => this.__reset(version));
+    }
+    __awaiter(version) {
+        this.__onchange(true);
+        this.__check(version);
+    }
+    //...
+    /**
+     * Добавляет промис в очередь отслеживания
+     *
+     * @example
+     * ```typescript
+     * async function fetchData() {
+     *   const promise = fetch("/api/data");
+     *   loader.push(promise);
+     *   const data = await promise;
+     *   return data;
+     * }
+     * ```
+     */
+    push(promise) {
+        this.__version++;
+        this.__heap.push(promise);
+        this.__awaiter(this.__version);
+    }
+    /**
+     * Создаёт хук: возвращает функцию, которая завершает отслеживание при вызове
+     *
+     * Внутри создаётся промис, добавляемый в очередь. Вызов возвращённой функции разрешает его
+     *
+     * @example
+     * ```typescript
+     * const complete = loader.hook();
+     * try {
+     *   await someAsyncOperation();
+     * } finally {
+     *   complete();
+     * }
+     * ```
+     */
+    hook() {
+        const { promise, resolve } = createManualPromise();
+        this.push(promise);
+        return resolve;
+    }
+    /**
+     * Выполняет функцию и автоматически отслеживает её промис
+     *
+     * @param func — Асинхронная функция для выполнения
+     * @param [external] — Опциональный коллбэк для синхронного уведомления о начале/завершении
+     *
+     * @throws {unknown} Ошибки промиса функции
+     *
+     * @example
+     * ```typescript
+     * async function fetchData() {
+     *   const data = await loader.run(() => fetch("/api/data"));
+     *   return data;
+     * }
+     * ```
+     */
+    async run(func, external) {
+        external?.(true);
+        try {
+            const promise = func();
+            this.push(promise);
+            return await promise;
+        }
+        finally {
+            external?.(false);
+        }
+    }
+}

package/dist/async/queue.d.ts

@@ -0,0 +1,51 @@
+import type { CanBePromise, TimeoutType } from "../types.js";
+export type QueueHandler<T> = (item: T, abort: () => void) => CanBePromise;
+/**
+ * Асинхронная очередь с последовательной обработкой и возможностью прерывания
+ *
+ * Элементы обрабатываются **по одному**, с заданной задержкой между ними.
+ * Обработка останавливается, если очередь пуста, и возобновляется при новом `push`.
+ * Функция-обработчик получает `abort`, чтобы прервать дальнейшую обработку (например, при ошибке).
+ *
+ * @template T - Тип элементов в очереди
+ *
+ * @example
+ * ```typescript
+ * const queue = new Queue(async (url, abort) => {
+ *   try {
+ *     await fetch(url);
+ *   } catch (e) {
+ *     abort(); // прекращает обработку оставшихся URL
+ *   }
+ * }, 50);
+ *
+ * queue.push("https://example.com/1");
+ * queue.push("https://example.com/2");
+ * ```
+ */
+export declare class Queue<T> {
+    delay: number;
+    __queue: T[];
+    __timeout: TimeoutType | 0;
+    __handle: QueueHandler<T>;
+    /**
+     * @param handle - Основная функция для обработки очереди
+     * @param [delay=25] - Задержка (в миллисекундах) между обработкой элементов очереди
+     */
+    constructor(handle: QueueHandler<T>, delay?: number);
+    /**
+     * Добавляет элемент в очередь и запускает обработку
+     *
+     * @param item - Элемент для добавления в очередь
+     * @param [run=true] - Запуск выполнения через {@link run}
+     */
+    push(item: T, run?: boolean): void;
+    /**
+     * @param [delay=this.delay] - Задержка перед запуском шага очереди
+     *
+     * @remarks Саморекурсивно
+     */
+    run(delay?: number): void;
+    stop(): void;
+    reset(): void;
+}

package/dist/async/queue.js

@@ -0,0 +1,84 @@
+/**
+ * Асинхронная очередь с последовательной обработкой и возможностью прерывания
+ *
+ * Элементы обрабатываются **по одному**, с заданной задержкой между ними.
+ * Обработка останавливается, если очередь пуста, и возобновляется при новом `push`.
+ * Функция-обработчик получает `abort`, чтобы прервать дальнейшую обработку (например, при ошибке).
+ *
+ * @template T - Тип элементов в очереди
+ *
+ * @example
+ * ```typescript
+ * const queue = new Queue(async (url, abort) => {
+ *   try {
+ *     await fetch(url);
+ *   } catch (e) {
+ *     abort(); // прекращает обработку оставшихся URL
+ *   }
+ * }, 50);
+ *
+ * queue.push("https://example.com/1");
+ * queue.push("https://example.com/2");
+ * ```
+ */
+export class Queue {
+    delay;
+    __queue = [];
+    __timeout = 0;
+    __handle;
+    /**
+     * @param handle - Основная функция для обработки очереди
+     * @param [delay=25] - Задержка (в миллисекундах) между обработкой элементов очереди
+     */
+    constructor(handle, delay = 25) {
+        this.__handle = handle;
+        this.delay = delay;
+    }
+    /**
+     * Добавляет элемент в очередь и запускает обработку
+     *
+     * @param item - Элемент для добавления в очередь
+     * @param [run=true] - Запуск выполнения через {@link run}
+     */
+    push(item, run = true) {
+        this.__queue.push(item);
+        if (run)
+            this.run();
+    }
+    /**
+     * @param [delay=this.delay] - Задержка перед запуском шага очереди
+     *
+     * @remarks Саморекурсивно
+     */
+    run(delay = this.delay) {
+        this.stop();
+        const start = async () => {
+            if (this.__queue.length === 0)
+                return this.stop();
+            const item = this.__queue.shift();
+            let aborted = false;
+            try {
+                await this.__handle(item, () => (aborted = true));
+            }
+            finally {
+                if (!aborted)
+                    this.__queue.length > 0 ? this.run() : this.stop();
+            }
+        };
+        if (delay) {
+            this.__timeout = setTimeout(() => void start(), delay);
+        }
+        else {
+            void start();
+        }
+    }
+    stop() {
+        if (this.__timeout)
+            clearTimeout(this.__timeout);
+        this.__timeout = 0;
+    }
+    reset() {
+        this.stop();
+        this.__queue.length = 0;
+    }
+}

package/dist/cases.d.ts

@@ -1,30 +1,40 @@
-export type CaseResult<V, T> = (value: V | undefined, mutate: boolean) => T;
 /**
- * Отлов строковых значений
+ * Результат обработки значения в case-функциях
  *
- * - `string` → `string`, `false`
- * - `number` → `string`, `true`
- * - `NaN` → `undefined`, `false`
- * - `ETC` → `undefined`, `false`
+ * @template V - Тип преобразованного значения
+ * @template T - Тип возвращаемого значения
+ *
+ * @param value - Преобразованное значение или undefined если преобразование невозможно
+ * @param mutated - Флаг указывающий было ли значение преобразовано (true) или осталось исходным (false)
+ */
+export type CaseResult<V, T> = (value: V | undefined, mutated: boolean) => T;
+/**
+ * Преобразует значение к строке
+ *
+ * - `string` → исходная строка, `mutated: false`
+ * - `number` → строка, `mutated: true`
+ * - `NaN` → `undefined`, `mutated: false`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export declare const caseString: <T>(value: unknown, call: CaseResult<string, T>) => T;
+export declare const caseString: <T>(value: unknown, callback: CaseResult<string, T>) => T;
 /**
- * Отлов числовых значений
+ * Преобразует значение к числу
  *
- * - `number` → `number`, `false`
- * - `string` → `number`, `true`
- * - `NaN` → `undefined`, `false`
- * - `ETC` → `undefined`, `false`
+ * - `number` (не NaN) → исходное число, `mutated: false`
+ * - `string` (числовая строка) → число, `mutated: true`
+ * - `number` (NaN) → `undefined`, `mutated: false`
+ * - `string` (пустая или нечисловая) → `undefined`, `mutated: false`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export declare const caseNumber: <T>(value: unknown, call: CaseResult<number, T>) => T;
+export declare const caseNumber: <T>(value: unknown, callback: CaseResult<number, T>) => T;
 /**
- * Отлов булевых значений
+ * Преобразует значение к булеву типу
  *
- * - `boolean` -> `boolean`, `false`
- * - `"false"` -> `boolean`, `true`
- * - `"true"` -> `boolean`, `true`
- * - `0` -> `boolean`, `true`
- * - `1` -> `boolean`, `true`
- * - `ETC` → `undefined`, `false`
+ * - `boolean` → исходное значение, `mutated: false`
+ * - `number` (0) → `false`, `mutated: true`
+ * - `number` (1) → `true`, `mutated: true`
+ * - `string` ("false") → `false`, `mutated: true`
+ * - `string` ("true") → `true`, `mutated: true`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export declare const caseBoolean: <T>(value: unknown, call: CaseResult<boolean, T>) => T;
+export declare const caseBoolean: <T>(value: unknown, callback: CaseResult<boolean, T>) => T;

package/dist/cases.js

@@ -1,69 +1,73 @@
 /**
- * Отлов строковых значений
+ * Преобразует значение к строке
  *
- * - `string` → `string`, `false`
- * - `number` → `string`, `true`
- * - `NaN` → `undefined`, `false`
- * - `ETC` → `undefined`, `false`
+ * - `string` → исходная строка, `mutated: false`
+ * - `number` → строка, `mutated: true`
+ * - `NaN` → `undefined`, `mutated: false`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export const caseString = (value, call) => {
+export const caseString = (value, callback) => {
     switch (typeof value) {
         case "string":
-            return call(value, false);
+            return callback(value, false);
         case "number":
             if (!isNaN(value))
-                return call(String(value), true);
+                return callback(String(value), true);
     }
-    return call(undefined, false);
+    return callback(undefined, false);
 };
 /**
- * Отлов числовых значений
+ * Преобразует значение к числу
  *
- * - `number` → `number`, `false`
- * - `string` → `number`, `true`
- * - `NaN` → `undefined`, `false`
- * - `ETC` → `undefined`, `false`
+ * - `number` (не NaN) → исходное число, `mutated: false`
+ * - `string` (числовая строка) → число, `mutated: true`
+ * - `number` (NaN) → `undefined`, `mutated: false`
+ * - `string` (пустая или нечисловая) → `undefined`, `mutated: false`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export const caseNumber = (value, call) => {
+export const caseNumber = (value, callback) => {
     switch (typeof value) {
         case "number":
-            return call(isNaN(value) ? undefined : value, false);
+            return callback(isNaN(value) ? undefined : value, false);
         case "string": {
             const trimmed = value.trim();
-            const number = Number(trimmed);
-            if (!isNaN(number) && value !== "")
-                return call(number, true);
+            // Проверяем что строка не пустая и преобразуется в валидное число
+            if (trimmed !== "") {
+                const number = Number(trimmed);
+                if (!isNaN(number))
+                    return callback(number, true);
+            }
         }
     }
-    return call(undefined, false);
+    return callback(undefined, false);
 };
 /**
- * Отлов булевых значений
+ * Преобразует значение к булеву типу
  *
- * - `boolean` -> `boolean`, `false`
- * - `"false"` -> `boolean`, `true`
- * - `"true"` -> `boolean`, `true`
- * - `0` -> `boolean`, `true`
- * - `1` -> `boolean`, `true`
- * - `ETC` → `undefined`, `false`
+ * - `boolean` → исходное значение, `mutated: false`
+ * - `number` (0) → `false`, `mutated: true`
+ * - `number` (1) → `true`, `mutated: true`
+ * - `string` ("false") → `false`, `mutated: true`
+ * - `string` ("true") → `true`, `mutated: true`
+ * - `ETC` → `undefined`, `mutated: false`
  */
-export const caseBoolean = (value, call) => {
+export const caseBoolean = (value, callback) => {
     switch (typeof value) {
         case "boolean":
-            return call(value, false);
+            return callback(value, false);
         case "number":
             if (value === 0)
-                return call(false, true);
+                return callback(false, true);
             if (value === 1)
-                return call(true, true);
+                return callback(true, true);
             break;
         case "string": {
-            const flat = value.trim().toLowerCase();
-            if (flat === "false")
-                return call(false, true);
-            if (flat === "true")
-                return call(true, true);
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "false")
+                return callback(false, true);
+            if (normalized === "true")
+                return callback(true, true);
         }
     }
-    return call(undefined, false);
+    return callback(undefined, false);
 };