@endge/utils 0.24.13 → 0.25.3

package/dist/collection/RingBuffer.d.ts

@@ -0,0 +1,12 @@
+export declare class RingBuffer<T> {
+    private readonly _cap;
+    private readonly _buf;
+    private _head;
+    private _len;
+    constructor(capacity: number);
+    get capacity(): number;
+    get length(): number;
+    push(value: T): void;
+    clear(): void;
+    toArray(): Array<T>;
+}

package/dist/collection/collection.d.ts

@@ -0,0 +1,51 @@
+import { CollectionEntity, CollectionEvents } from './collection.types';
+import { ChangeNotifier } from '../events/ChangeNotifier';
+/**
+ * Описывает ответственность Collection в архитектуре проекта.
+ */
+export declare class Collection<T extends CollectionEntity> extends ChangeNotifier {
+    private items;
+    private indices;
+    private rootIds;
+    private bus;
+    /**
+     * Создает экземпляр Collection и подготавливает базовое состояние.
+     */
+    constructor(initialItems?: Array<T>);
+    /**
+     * Выполняет действие add в рамках ответственности Collection.
+     */
+    add(items: T | Array<T>): void;
+    /**
+     * Удаляет сущность из runtime-коллекции Collection.
+     */
+    remove(arg: string | T | Array<string | T>): void;
+    /**
+     * Обновляет runtime-состояние Collection.
+     */
+    update(itemOrItems: T | Array<T>): void;
+    /**
+     * Возвращает значение состояния Collection.
+     */
+    get(arg: string | Partial<T>): T | undefined;
+    /**
+     * Создает runtime-сущность Collection.
+     */
+    private createIndex;
+    /**
+     * Возвращает реактивный массив всех элементов.
+     */
+    get all(): Array<T>;
+    /**
+     * Возвращает массив корневых элементов (без parentId).
+     */
+    get allRoot(): Array<T>;
+    /**
+     * Обрабатывает входящее событие Collection.
+     */
+    on<K extends keyof CollectionEvents<T>>(event: K, cb: (payload: CollectionEvents<T>[K]) => void): void;
+    /**
+     * Выполняет действие off в рамках ответственности Collection.
+     */
+    off<K extends keyof CollectionEvents<T>>(event: K, cb: (payload: CollectionEvents<T>[K]) => void): void;
+}

package/dist/collection/collection.types.d.ts

@@ -0,0 +1,35 @@
+export interface CollectionEntity {
+    id: string;
+    parentId?: string | null;
+}
+export declare enum Events {
+    Add = "add",
+    Remove = "remove",
+    Update = "update",
+    IndexCreate = "indexCreate"
+}
+export interface CollectionEvents<T extends CollectionEntity> {
+    [Events.Add]: Array<T>;
+    [Events.Remove]: Array<T>;
+    [Events.Update]: Array<T>;
+    [Events.IndexCreate]: keyof T;
+}
+export interface IndexCollectionEntity<ID = string | null> {
+    id: ID;
+    index: number;
+    filteredIndex: number;
+}
+export interface CollectionOptions<T extends IndexCollectionEntity<ID>, ID = string | null> {
+    sortFn: (a: T, b: T) => number;
+    filterFn: (item: T) => boolean;
+    indexEnabled: boolean;
+    filterIndexEnabled: boolean;
+}
+export interface ReadonlyIndexCollection<T extends IndexCollectionEntity<ID>, ID = string | null> {
+    get: (id: ID) => T | undefined;
+    all: () => ReadonlyArray<T>;
+    size: () => number;
+    unfiltered: () => ReadonlyArray<T>;
+    has: (id: ID) => boolean;
+    forEach: (callback: (item: T) => void) => void;
+}

package/dist/collection/indexed-collection.d.ts

@@ -0,0 +1,140 @@
+import { CollectionOptions, IndexCollectionEntity } from './collection.types';
+import { OneOrMany } from '../tools/tools.types';
+/**
+ * Высокопроизводительная IndexedCollection
+ *
+ * Цели:
+ * - O(1) добавление, удаление и доступ по id
+ * - O(1) обновление membership фильтра (dense массив + swap-remove)
+ * - Ленивый sort, полный пересчет только по запросу
+ * - Инкрементальная поддержка filteredList (swap-remove) при включенном filterIndexEnabled
+ *
+ * Важно:
+ * - При sort list меняется порядок -> filteredList должен быть пересобран (иначе он останется в старом порядке).
+ * - При изменении filterFn можно пересобрать filteredList без пересортировки list.
+ */
+export declare class IndexedCollection<T extends IndexCollectionEntity<ID>, ID = string | null> {
+    private list;
+    private filteredList;
+    private map;
+    private indexById;
+    private dirtySort;
+    private dirtyFilter;
+    private sortFn?;
+    private filterFn?;
+    private indexEnabled;
+    private filterIndexEnabled;
+    /**
+     * Создает экземпляр IndexedCollection и подготавливает базовое состояние.
+     */
+    constructor(opts?: Partial<CollectionOptions<T, ID>> | null);
+    /**
+     * Выполняет действие options в рамках ответственности IndexedCollection.
+     */
+    options(opts: Partial<CollectionOptions<T, ID>>): this;
+    /**
+     * Выполняет действие markDirty в рамках ответственности IndexedCollection.
+     */
+    markDirty(opts: {
+        filter?: boolean;
+        sort?: boolean;
+    }): void;
+    /**
+     * Выполняет действие ensure в рамках ответственности IndexedCollection.
+     */
+    ensure(): void;
+    /**
+     * Выполняет действие ensureSorted в рамках ответственности IndexedCollection.
+     */
+    ensureSorted(): void;
+    /**
+     * Выполняет действие ensureFiltered в рамках ответственности IndexedCollection.
+     */
+    ensureFiltered(): void;
+    /**
+     * Выполняет действие add в рамках ответственности IndexedCollection.
+     */
+    add(items: OneOrMany<T>): void;
+    /**
+     * Удаляет сущность из runtime-коллекции IndexedCollection.
+     */
+    remove(ids: OneOrMany<ID>): void;
+    /**
+     * Вызывать после изменения полей элемента
+     * mayAffectFilter если изменились поля фильтра
+     * mayAffectSort если изменились поля сортировки
+     */
+    touch(id: ID, opts?: {
+        mayAffectFilter?: boolean;
+        mayAffectSort?: boolean;
+    }): void;
+    /**
+     * Выполняет действие forEach в рамках ответственности IndexedCollection.
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * Отсортированный и/или отфильтрованный список (в зависимости от включенных функций).
+     */
+    all(): Array<T>;
+    /**
+     * Отсортированный полный список (без фильтра), если есть sortFn.
+     */
+    unfiltered(): Array<T>;
+    /**
+     * Отсортированный и отфильтрованный список (если есть filterFn).
+     * Если filterFn нет — возвращается list.
+     */
+    filtered(): Array<T>;
+    /**
+     * Выполняет действие pos в рамках ответственности IndexedCollection.
+     */
+    pos(index: number): T | null;
+    /**
+     * Выполняет действие first в рамках ответственности IndexedCollection.
+     */
+    first(): T | null;
+    /**
+     * Выполняет действие last в рамках ответственности IndexedCollection.
+     */
+    last(): T | null;
+    /**
+     * Выполняет действие has в рамках ответственности IndexedCollection.
+     */
+    has(id: ID): boolean;
+    /**
+     * Возвращает значение состояния IndexedCollection.
+     */
+    get(id: ID): T | undefined;
+    /**
+     * Выполняет действие size в рамках ответственности IndexedCollection.
+     */
+    size(): number;
+    /**
+     * Очищает накопленное состояние IndexedCollection.
+     */
+    clear(): void;
+    /**
+     * Выполняет внутренний шаг rebuildFilteredFromScratch для IndexedCollection.
+     */
+    private rebuildFilteredFromScratch;
+    /**
+     * Выполняет внутренний шаг addToFilteredIfPasses для IndexedCollection.
+     */
+    private addToFilteredIfPasses;
+    /**
+     * Добавляет сущность в runtime-коллекцию IndexedCollection.
+     */
+    private appendToFiltered;
+    /**
+     * Выполняет внутренний шаг refilterOneO1 для IndexedCollection.
+     */
+    private refilterOneO1;
+    /**
+     * Удаляет сущность из runtime-коллекции IndexedCollection.
+     */
+    private removeFromFilteredO1;
+    /**
+     * Удаляет сущность из runtime-коллекции IndexedCollection.
+     */
+    private removeFromListO1;
+}

package/dist/database/PayloadHttpClient.d.ts

@@ -0,0 +1,13 @@
+export interface PayloadClientOptions {
+    baseUrl: string;
+}
+export declare class PayloadHttpClient {
+    private readonly baseUrl;
+    constructor(opts: PayloadClientOptions);
+    private buildUrl;
+    private buildHeaders;
+    get<T>(path: string, query?: Record<string, unknown>, extraHeaders?: HeadersInit): Promise<T>;
+    post<T>(path: string, body?: unknown, extraHeaders?: HeadersInit): Promise<T>;
+    patch<T>(path: string, body?: unknown, extraHeaders?: HeadersInit): Promise<T>;
+    delete<T>(path: string, extraHeaders?: HeadersInit): Promise<T>;
+}

package/dist/events/ChangeNotifier.d.ts

@@ -0,0 +1,8 @@
+/** Внутренний механизм уведомления generic utilities об изменениях. */
+export declare class ChangeNotifier {
+    private readonly _listeners;
+    /** Подписывает listener на изменения utility owner. */
+    subscribe(listener: () => void): () => void;
+    /** Уведомляет текущих listeners об изменении. */
+    notify(): void;
+}

package/dist/events/EventBus.d.ts

@@ -0,0 +1,117 @@
+import { OneOrMany } from '../tools/tools.types';
+/**
+ * Тип колбэка для события.
+ * @template T Тип данных, передаваемых в событие.
+ */
+export type EventCallback<T = any> = (payload: T) => void;
+export type EventList = Record<string, any>;
+/**
+ * EventBus реализует паттерн подписки на события.
+ *
+ * Поддерживает:
+ * - Типизированные события через дженерик StaticEvents;
+ * - Кастомные (непредопределённые) события;
+ * - Подписку `on`, одноразовую подписку `once`, отписку `off`;
+ * - Эмит `emit`, проверку `hasListeners` и список активных событий `eventNames`.
+ *
+ * Пример использования:
+ *
+ * ```ts
+ * type Events = {
+ *   userLogin: { id: string }
+ *   error: { message: string }
+ * }
+ *
+ * const bus = new EventBus<Events>(['userLogin', 'error'])
+ *
+ * bus.on('userLogin', ({ id }) => console.logFrame(`Login: ${id}`))
+ * bus.once('error', ({ message }) => console.warn('One-time error:', message))
+ *
+ * bus.emit('userLogin', { id: 'u42' })         // Login: u42
+ * bus.emit('error', { message: 'fail' })       // One-time error: fail
+ * bus.emit('error', { message: 'fail again' }) // уже не сработает
+ *
+ * console.logFrame(bus.hasListeners('userLogin')) // true
+ * console.logFrame(bus.eventNames())              // ['userLogin']
+ * ```
+ */
+export declare class EventBus<StaticEvents extends Record<string, any>, CustomEventMap extends Record<string, any> = Record<string, any>> {
+    private listeners;
+    /**
+     * Создает экземпляр EventBus и подготавливает базовое состояние.
+     */
+    constructor(predefinedEvents?: Array<keyof StaticEvents>);
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    on<K extends keyof StaticEvents>(events: OneOrMany<K>, callback: EventCallback<StaticEvents[K]>): void;
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    once<K extends keyof StaticEvents>(events: OneOrMany<K>, callback: EventCallback<StaticEvents[K]>): void;
+    /**
+     * Выполняет действие off в рамках ответственности EventBus.
+     */
+    off<K extends keyof StaticEvents>(events: OneOrMany<K>, callback: EventCallback<StaticEvents[K]>): void;
+    /**
+     * Выполняет действие offAll в рамках ответственности EventBus.
+     */
+    offAll(): void;
+    /**
+     * Публикует событие во внутренний event bus EventBus.
+     */
+    emit<K extends keyof StaticEvents>(event: K, payload: StaticEvents[K]): void;
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    onCustom<K extends keyof CustomEventMap>(events: OneOrMany<K>, callback: EventCallback<CustomEventMap[K]>): void;
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    onceCustom<K extends keyof CustomEventMap>(events: OneOrMany<K>, callback: EventCallback<CustomEventMap[K]>): void;
+    /**
+     * Выполняет действие offCustom в рамках ответственности EventBus.
+     */
+    offCustom<K extends keyof CustomEventMap>(events: OneOrMany<K>, callback: EventCallback<CustomEventMap[K]>): void;
+    /**
+     * Публикует событие во внутренний event bus EventBus.
+     */
+    emitCustom<K extends keyof CustomEventMap>(event: K, payload: CustomEventMap[K]): void;
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    private _on;
+    /**
+     * Обрабатывает входящее событие EventBus.
+     */
+    private _once;
+    /**
+     * Выполняет внутренний шаг _off для EventBus.
+     */
+    private _off;
+    /**
+     * Публикует событие во внутренний event bus EventBus.
+     */
+    private _emit;
+    /**
+     * Выполняет действие hasListeners в рамках ответственности EventBus.
+     */
+    hasListeners(event: string): boolean;
+    /**
+     * Выполняет действие eventNames в рамках ответственности EventBus.
+     */
+    eventNames(): Array<string>;
+    /**
+     * Очищает накопленное состояние EventBus.
+     */
+    clear(event?: string): void;
+}
+export interface GlobalEvents {
+    notify: {
+        severity: 'success' | 'error' | 'info' | 'warn';
+        summary: string;
+        detail?: string;
+        life?: number;
+    };
+}
+export declare const AppBus: EventBus<GlobalEvents, Record<string, any>>;

package/dist/execute/NamedExecutor.d.ts

@@ -0,0 +1,39 @@
+interface NamedExecutorConfig {
+    delayMs: number;
+    maxMs: number;
+}
+/**
+ * Описывает ответственность NamedExecutor в архитектуре проекта.
+ */
+export declare class NamedExecutor {
+    private readonly config;
+    private delayTimers;
+    private maxTimers;
+    private callbacks;
+    private firstCallTime;
+    /**
+     * Создает экземпляр NamedExecutor и подготавливает базовое состояние.
+     */
+    constructor(config: NamedExecutorConfig);
+    /**
+     * Выполняет действие run в рамках ответственности NamedExecutor.
+     */
+    run(id: string, callback: () => void): void;
+    /**
+     * Принудительно завершает накопленные изменения NamedExecutor.
+     */
+    flush(id: string): void;
+    /**
+     * Выполняет действие cancel в рамках ответственности NamedExecutor.
+     */
+    cancel(id: string): void;
+    /**
+     * Принудительно завершает накопленные изменения NamedExecutor.
+     */
+    flushAll(): void;
+    /**
+     * Очищает накопленное состояние NamedExecutor.
+     */
+    private clear;
+}
+export {};

package/dist/execute/delay-executor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Описывает ответственность DelayedExecutor в архитектуре проекта.
+ */
+export declare class DelayedExecutor<T extends Array<any> = []> {
+    private readonly fn;
+    private readonly firstExecuteImmediately;
+    private delayTimer;
+    private maxTimer;
+    private hasExecutedOnce;
+    private lastArgs;
+    /**
+     * Создает экземпляр DelayedExecutor и подготавливает базовое состояние.
+     */
+    constructor(fn: (...args: T) => void, firstExecuteImmediately?: boolean);
+    /**
+     * Выполняет действие run в рамках ответственности DelayedExecutor.
+     */
+    run(args: T, delayMs?: number, maxWaitMs?: number): void;
+    /**
+     * Принудительно завершает накопленные изменения DelayedExecutor.
+     */
+    flush(): void;
+    /**
+     * Выполняет действие cancel в рамках ответственности DelayedExecutor.
+     */
+    cancel(): void;
+    /**
+     * Очищает накопленное состояние DelayedExecutor.
+     */
+    private clear;
+}