@nemigo/helpers 0.13.2 → 1.5.0

package/dist/aggregator.d.ts

@@ -0,0 +1,33 @@
+import type { CanBePromise } from "./types.js";
+export type AFunc = () => CanBePromise;
+/**
+ * Aggregator для группового выполнения функций
+ *
+ * Позволяет собирать функции и выполнять их все вместе.
+ * Может использоваться для очистки, уведомлений, batch-операций и т.д.
+ *
+ * @example
+ * ```typescript
+ * const runner = new Aggregator();
+ * runner.add(() => console.log("First run"));
+ * runner.run();
+ * runner.add(() => console.log("Second run"));
+ * runner.run();
+ * ```
+ */
+export declare class Aggregator {
+    __calls: AFunc[];
+    /**
+     * @param calls - Начальные функции для выполнения
+     */
+    constructor(...calls: AFunc[]);
+    push(...calls: AFunc[]): this;
+    /**
+     * @param [promise=false] - Есть асинхронные функции и нужно дождаться их выполнения
+     */
+    run(promise?: false): void;
+    /**
+     * @param promise - Есть асинхронные функции и нужно дождаться их выполнения
+     */
+    run(promise: true): Promise<void>;
+}

package/dist/aggregator.js

@@ -0,0 +1,44 @@
+/**
+ * Aggregator для группового выполнения функций
+ *
+ * Позволяет собирать функции и выполнять их все вместе.
+ * Может использоваться для очистки, уведомлений, batch-операций и т.д.
+ *
+ * @example
+ * ```typescript
+ * const runner = new Aggregator();
+ * runner.add(() => console.log("First run"));
+ * runner.run();
+ * runner.add(() => console.log("Second run"));
+ * runner.run();
+ * ```
+ */
+export class Aggregator {
+    __calls = [];
+    /**
+     * @param calls - Начальные функции для выполнения
+     */
+    constructor(...calls) {
+        this.__calls = calls;
+    }
+    push(...calls) {
+        this.__calls.push(...calls);
+        return this;
+    }
+    /**
+     * @param [promise=false] - Есть асинхронные функции и нужно дождаться их выполнения
+     */
+    run(promise = false) {
+        if (promise) {
+            return (async () => {
+                await Promise.allSettled(this.__calls.map(async (f) => f()));
+                this.__calls.length = 0;
+            })();
+        }
+        else {
+            for (const call of this.__calls)
+                void call();
+            this.__calls.length = 0;
+        }
+    }
+}

package/dist/array.d.ts

@@ -0,0 +1,33 @@
+import type { CanBeArray, CanBeReadonlyArray } from "./types.js";
+/**
+ * Приведение значения к массиву
+ */
+export declare const arrayble: <T>(v: CanBeArray<T> | CanBeReadonlyArray<T>) => T[];
+/**
+ * Тип разделения для функции {@link partition}
+ */
+export interface Partition<T> {
+    /**
+     * Элементы, удовлетворяющие условию
+     */
+    result: T[];
+    /**
+     * Исключённые элементы
+     */
+    excluded: T[];
+}
+/**
+ * Разделяет массив на два по условию
+ */
+export declare const partition: <T>(arr: CanBeReadonlyArray<T>, filter: (item: T) => boolean, initial?: Partition<T>) => Partition<T>;
+/**
+ * Удаляет `null` и `undefined` и оставляет только уникальные строки
+ */
+export declare const setify: (arr: CanBeReadonlyArray<string | undefined | null>) => string[];
+/**
+ * Удаляет дубликаты объектов из массива на основе указанного ключа
+ *
+ * @param arr - Исходный массив объектов
+ * @param [key="id"] - Ключ, по которому будут удаляться дубликаты
+ */
+export declare const unify: <T, K extends keyof T>(arr: CanBeReadonlyArray<T>, key?: K) => T[];

package/dist/array.js

@@ -0,0 +1,24 @@
+/**
+ * Приведение значения к массиву
+ */
+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);
+//...
+/**
+ * Удаляет `null` и `undefined` и оставляет только уникальные строки
+ */
+export const setify = (arr) => [
+    ...new Set(arr.filter((item) => typeof item === "string")),
+];
+/**
+ * Удаляет дубликаты объектов из массива на основе указанного ключа
+ *
+ * @param arr - Исходный массив объектов
+ * @param [key="id"] - Ключ, по которому будут удаляться дубликаты
+ */
+export const unify = (arr, key = "id") => [
+    ...new Map(arr.map((item) => [item[key], item])).values(),
+];

package/dist/async/context.d.ts

@@ -0,0 +1,73 @@
+import type { CanBePromise } from "../types.js";
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Создание асинхронного контекста с транзакциями без явной передачи на основе {@link AsyncLocalStorage}
+ *
+ * @template TX - Тип операций в транзакции
+ *
+ * @example
+ * ```typescript
+ * class Database extends AsyncContext<Query> {
+ *   protected async submit(tx: Query[]): Promise<void> {
+ *     await database.executeBatch(tx);
+ *   }
+ * }
+ *
+ * const database = new Database();
+ * const result = await database.space(async (tx) => {
+ *   tx.push(new Query("INSERT ..."));
+ *   await nestedFunction();
+ *   return someOperation();
+ * });
+ *
+ * async function nestedFunction() {
+ *   const tx = database.getTX();
+ *   tx.push(new Query("UPDATE ..."));
+ * }
+ * ```
+ */
+export declare abstract class AsyncContext<TX> {
+    __async_storage: AsyncLocalStorage<TX[]>;
+    /**
+     * Получает текущий массив операций транзакции из асинхронного контекста
+     *
+     * Работает в любом месте цепочки асинхронных вызовов, запущенных внутри {@link space}
+     *
+     * @throws {Error} Если вызвано вне контекста space()
+     */
+    getTX(): TX[];
+    /**
+     * Создаёт асинхронное пространство транзакции
+     *
+     * Всё внутри `func` получает доступ к одной транзакции через {@link getTX}
+     *
+     * @param func - Функция для выполнения в транзакции
+     * @param [autoAfterCommit=true] - Автоматический вызов {@link commit} после завершения
+     */
+    space<T>(func: (tx: TX[]) => CanBePromise<T>, autoAfterCommit?: boolean): Promise<T>;
+    /**
+     * Выполняет накопленные операции и очищает транзакцию
+     *
+     * @remarks Можно вызвать во вложенных функциях, но это будет антипаттерн
+     *
+     * @throws {Error} Если вызвано вне контекста space()
+     *
+     * @example
+     * ```typescript
+     * await database.space(async (tx) => {
+     *   tx.push(operation1);
+     *
+     *   await database.commit(); // Выполняем operation1
+     *
+     *   tx.push(operation2); // operation2 будет уже в новой транзакции
+     * });
+     * ```
+     */
+    commit(): Promise<void>;
+    /**
+     * Выполняет накопленные операции (например, запись в БД, отправка в очередь и т.д.)
+     *
+     * @remarks `transaction.length = 0` не требуется — это делают вызывающие методы после
+     */
+    abstract __submit(transaction: TX[]): Promise<void>;
+}

package/dist/async/context.js

@@ -0,0 +1,90 @@
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Создание асинхронного контекста с транзакциями без явной передачи на основе {@link AsyncLocalStorage}
+ *
+ * @template TX - Тип операций в транзакции
+ *
+ * @example
+ * ```typescript
+ * class Database extends AsyncContext<Query> {
+ *   protected async submit(tx: Query[]): Promise<void> {
+ *     await database.executeBatch(tx);
+ *   }
+ * }
+ *
+ * const database = new Database();
+ * const result = await database.space(async (tx) => {
+ *   tx.push(new Query("INSERT ..."));
+ *   await nestedFunction();
+ *   return someOperation();
+ * });
+ *
+ * async function nestedFunction() {
+ *   const tx = database.getTX();
+ *   tx.push(new Query("UPDATE ..."));
+ * }
+ * ```
+ */
+export class AsyncContext {
+    __async_storage = new AsyncLocalStorage();
+    /**
+     * Получает текущий массив операций транзакции из асинхронного контекста
+     *
+     * Работает в любом месте цепочки асинхронных вызовов, запущенных внутри {@link space}
+     *
+     * @throws {Error} Если вызвано вне контекста space()
+     */
+    getTX() {
+        const ctx = this.__async_storage.getStore();
+        if (ctx)
+            return ctx;
+        throw new Error("getTX() called outside of space() context");
+    }
+    /**
+     * Создаёт асинхронное пространство транзакции
+     *
+     * Всё внутри `func` получает доступ к одной транзакции через {@link getTX}
+     *
+     * @param func - Функция для выполнения в транзакции
+     * @param [autoAfterCommit=true] - Автоматический вызов {@link commit} после завершения
+     */
+    async space(func, autoAfterCommit = true) {
+        const ctx = this.__async_storage.getStore();
+        if (ctx)
+            return func(ctx);
+        const transaction = [];
+        const result = await this.__async_storage.run(transaction, () => func(transaction));
+        if (autoAfterCommit && transaction.length > 0) {
+            await this.__submit(transaction);
+            transaction.length = 0;
+        }
+        return result;
+    }
+    /**
+     * Выполняет накопленные операции и очищает транзакцию
+     *
+     * @remarks Можно вызвать во вложенных функциях, но это будет антипаттерн
+     *
+     * @throws {Error} Если вызвано вне контекста space()
+     *
+     * @example
+     * ```typescript
+     * await database.space(async (tx) => {
+     *   tx.push(operation1);
+     *
+     *   await database.commit(); // Выполняем operation1
+     *
+     *   tx.push(operation2); // operation2 будет уже в новой транзакции
+     * });
+     * ```
+     */
+    async commit() {
+        const transaction = this.__async_storage.getStore();
+        if (!transaction)
+            throw new Error("commit() called outside of space() context");
+        if (transaction.length > 0) {
+            await this.__submit(transaction);
+            transaction.length = 0;
+        }
+    }
+}

package/dist/async/future.d.ts

@@ -0,0 +1,54 @@
+import type { CanBePromise, IntervalType, RID, TimeoutType } from "../types.js";
+/**
+ * Типы фьючерса из {@link Future}:
+ * - `"timer"` — Однократный
+ * - `"interval"` — Повторяющийся
+ */
+export type FutureType = "timer" | "interval";
+/**
+ * Опции запуска фьючерса из {@link Future}
+ */
+export interface FutureRunOptions {
+    type?: FutureType;
+    key?: RID;
+    delay?: number;
+}
+type InternalFuture = {
+    type: "timer";
+    id: TimeoutType;
+} | {
+    type: "interval";
+    id: IntervalType;
+};
+/**
+ * Управление таймерами и интервалами
+ */
+export declare class Future {
+    delay: number;
+    /**
+     * @param [delay=5min] - Задержка по умолчанию
+     */
+    constructor(delay?: number);
+    __entries: Map<RID, InternalFuture>;
+    __delete(key: RID, entry: InternalFuture): void;
+    /**
+     * @param key - Ключ фьючерса. Если не указан — **очищаются все**
+     */
+    clear(key?: RID): void;
+    has(key: RID): FutureType | undefined;
+    /**
+     * Очищает существующий фьючерс по ключу (если он был) и запускает новый
+     *
+     * @param func - Функция для выполнения
+     * @param [options] - Опции запуска
+     * @param [options.type="timer"] - Тип фьючерса
+     * @param [options.key=Symbol()] - Ключ фьючерса
+     * @param [options.delay=this.delay] - Задержка в миллисекундах
+     *
+     * @return Функция для очистки
+     *
+     * @remarks Ошибки полностью игнорируются
+     */
+    run(func: () => CanBePromise, { type, key: __key, delay }?: FutureRunOptions): () => void;
+}
+export {};

package/dist/async/future.js

@@ -0,0 +1,71 @@
+import { MS_IN_MINUTE } from "../datetime/delta.js";
+/**
+ * Управление таймерами и интервалами
+ */
+export class Future {
+    delay;
+    /**
+     * @param [delay=5min] - Задержка по умолчанию
+     */
+    constructor(delay = 5 * MS_IN_MINUTE) {
+        this.delay = delay;
+    }
+    __entries = new Map();
+    __delete(key, entry) {
+        entry.type === "timer" ? clearTimeout(entry.id) : clearInterval(entry.id);
+        this.__entries.delete(key);
+    }
+    /**
+     * @param key - Ключ фьючерса. Если не указан — **очищаются все**
+     */
+    clear(key) {
+        if (key === undefined) {
+            for (const [k, entry] of this.__entries)
+                this.__delete(k, entry);
+        }
+        else {
+            const entry = this.__entries.get(key);
+            if (entry)
+                this.__delete(key, entry);
+        }
+    }
+    has(key) {
+        return this.__entries.get(key)?.type;
+    }
+    /**
+     * Очищает существующий фьючерс по ключу (если он был) и запускает новый
+     *
+     * @param func - Функция для выполнения
+     * @param [options] - Опции запуска
+     * @param [options.type="timer"] - Тип фьючерса
+     * @param [options.key=Symbol()] - Ключ фьючерса
+     * @param [options.delay=this.delay] - Задержка в миллисекундах
+     *
+     * @return Функция для очистки
+     *
+     * @remarks Ошибки полностью игнорируются
+     */
+    run(func, { type = "timer", key: __key, delay = this.delay } = {}) {
+        if (__key !== undefined)
+            this.clear(__key);
+        const key = __key ?? Symbol();
+        let id;
+        if (type === "timer") {
+            const futures = async () => {
+                try {
+                    await func();
+                }
+                finally {
+                    this.__entries.delete(key);
+                }
+            };
+            id = setTimeout(() => void futures(), delay);
+        }
+        else {
+            id = setInterval(() => void func(), delay);
+        }
+        const entry = { type, id };
+        this.__entries.set(key, entry);
+        return () => this.__delete(key, entry);
+    }
+}

package/dist/async/index.d.ts

@@ -1,40 +1,69 @@
-import type { Timestamp } from "../types.js";
+import type { AnyFunc, Args, CanBePromise, Return } from "../types.js";
 /**
- * Создаёт задержку на указанное количество миллисекунд
+ * Промис из {@link createManualPromise}
  */
-export declare const delay: (ms: Timestamp, success?: boolean) => Promise<void>;
+export interface ManualPromise<T = void, E = Error> {
+    promise: Promise<T>;
+    resolve: (result: T) => void;
+    reject: (err: E) => void;
+}
+export declare const createManualPromise: <T = void, E = Error>() => ManualPromise<T, E>;
+/**
+ * Создаёт промис, завершающийся через заданное время
+ *
+ * @param ms - Время задержки в миллисекундах
+ * @param [success=true] - Завершать успехом или отклонять
+ *
+ * @remarks При `success = false` промис отклоняется с ошибкой `"delay rejected"`
+ */
+export declare const delay: (ms: number, success?: boolean) => Promise<void>;
 /**
  * Создаёт 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 declare const debounce: <T extends (...args: any[]) => any>(call: T, delay: Timestamp) => ((...args: Parameters<T>) => void);
+export declare const debounce: <F extends AnyFunc>(func: F, ms: number) => ((...args: Args<F>) => void);
 /**
- * Создаёт функцию-замыкание, которое гарантирует (старается), что переданная функция `call`
- * будет вызвана не чаще одного раза в заданный интервал времени.
- *
- * mode = `"delay"`
- *   - первый вызов откладывается на `ms`
- *   - повторные вызовы до старта игнорируются, аргументы обновляются
- *   - все ждут одного промисса
- *
- * mode = `"urgent"`:
- *   - первый вызов исполняется сразу
- *   - повторные вызовы возвращают тот же промисс в течение `ms` (даже после завершения)
- *   - после `ms` можно снова вызвать
+ * Режимы троттлинга для {@link throttle}:
+ * - `"delay"`:
+ *   * Первый вызов откладывается на `ms`
+ *   * Повторные вызовы до старта игнорируются
+ *   * Аргументы обновляются
+ * - `"urgent"`:
+ *   * Первый вызов исполняется сразу
+ *   * Повторные вызовы возвращают тот же промис в течение `ms`
+ *   * Аргументы обновляются, но не влияют, если функция уже выполняется
  */
-export declare const throttle: <F extends (...args: any[]) => any>(call: F, mode: "urgent" | "delay", ms: number) => ((...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>);
+export type ThrottleMode = "urgent" | "delay";
 /**
- * Создаёт функцию-замыкание, которая гарантирует однократное выполнение асинхронной операции
+ * Создаёт throttle-функцию, которая вызывает переданную функцию не чаще одного раза в заданный интервал времени
  *
- * При первом вызове запускает переданный `call` и сохраняет его результат.
- * Все последующие вызовы возвращают сохранённый результат без повторного выполнения операции.
- * Если вызов происходит во время выполнения, возвращает тот же промисс, вместо создания нового
+ * @param func - Функция для троттлинга
+ * @param [mode="urgent"] - Режим троттлинга
+ * @param [ms=250] - Интервал времени в миллисекундах
  *
- * @param call - Асинхронная функция, результат которой нужно кешировать
- * @returns Функция, возвращающая закешированный результат после первого успешного выполнения
+ * @throws {unknown} Ошибки функции прокидываются в промис
+ *
+ * @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 declare const throttle: <F extends AnyFunc>(func: F, mode?: "urgent" | "delay", ms?: number) => ((...args: Args<F>) => Promise<Awaited<Return<F>>>);
+export type BoundaryFallback<Fallback> = Fallback | ((err: unknown) => CanBePromise<Fallback>);
+/**
+ * Приведение коллбэка к промису с отловом ошибок и fallback-значением
  */
-export declare const createPromiseTrap: <T>(call: () => Promise<T>) => () => Promise<T>;
+export declare const boundary: <Result = undefined, Fallback = Result>(func: () => CanBePromise<Result>, fallback?: BoundaryFallback<Fallback>) => Promise<Result | Fallback>;