@dxtmisha/functional-basic 1.1.0 → 1.1.6

package/dist/classes/ErrorCenterHandler.d.ts

@@ -0,0 +1,64 @@
+import { ErrorCenterCauseItem, ErrorCenterGroup, ErrorCenterHandlerCallback, ErrorCenterHandlerItem, ErrorCenterHandlerList } from '../types/errorCenter';
+/**
+ * Class for managing and triggering error handlers.
+ *
+ * Класс для управления и вызова обработчиков ошибок.
+ */
+export declare class ErrorCenterHandler {
+    /** Registered handlers list / Список зарегистрированных обработчиков */
+    protected handlers: ErrorCenterHandlerList;
+    /**
+     * Constructor
+     * @param handlers initial handlers list / начальный список обработчиков
+     */
+    constructor(handlers?: ErrorCenterHandlerList);
+    /**
+     * Checks if handlers exist for a group.
+     *
+     * Проверяет наличие обработчиков для группы.
+     * @param group error group / группа ошибки
+     * @returns true if handlers exist / true, если обработчики существуют
+     */
+    has(group: ErrorCenterGroup): boolean;
+    /**
+     * Gets handlers for a group.
+     *
+     * Получает обработчики для группы.
+     * @param group error group / группа ошибки
+     * @returns handler item or undefined / элемент обработчика или undefined
+     */
+    get(group: ErrorCenterGroup): ErrorCenterHandlerItem | undefined;
+    /**
+     * Adds a handler for a specific group.
+     *
+     * Добавляет обработчик для определенной группы.
+     * @param group error group / группа ошибки
+     * @param handler callback function / функция обратного вызова
+     * @returns this instance / текущий экземпляр
+     */
+    add(group: ErrorCenterGroup, handler: ErrorCenterHandlerCallback): this;
+    /**
+     * Adds a list of group-based handlers.
+     *
+     * Добавляет список обработчиков по группам.
+     * @param handlers handlers list / список обработчиков
+     * @returns this instance / текущий экземпляр
+     */
+    addList(handlers: ErrorCenterHandlerList): this;
+    /**
+     * Triggers handlers for a group and logs to console.
+     *
+     * Вызывает обработчики для группы и выводит ошибку в консоль.
+     * @param cause error cause details / детали причины ошибки
+     * @returns this instance / текущий экземпляр
+     */
+    on(cause: ErrorCenterCauseItem): this;
+    /**
+     * Logs error cause to the console.
+     *
+     * Выводит причину ошибки в консоль.
+     * @param cause error details / детали ошибки
+     * @returns this instance / текущий экземпляр
+     */
+    protected toConsole(cause: ErrorCenterCauseItem): this;
+}

package/dist/classes/ErrorCenterInstance.d.ts

@@ -0,0 +1,85 @@
+import { ErrorCenterHandler } from './ErrorCenterHandler';
+import { ErrorCenterCauseItem, ErrorCenterCauseList, ErrorCenterGroup, ErrorCenterHandlerCallback, ErrorCenterHandlerList } from '../types/errorCenter';
+/**
+ * Class for managing error storage and handling within an instance.
+ *
+ * Класс для управления хранилищем ошибок и их обработкой внутри экземпляра.
+ */
+export declare class ErrorCenterInstance {
+    protected handler: ErrorCenterHandler;
+    /** List of stored error causes / Список сохраненных причин ошибок */
+    protected causes: ErrorCenterCauseList;
+    /**
+     * Constructor
+     * @param causes initial list of error causes / начальный список причин ошибок
+     * @param handler handler instance / экземпляр обработчика
+     */
+    constructor(causes?: ErrorCenterCauseList, handler?: ErrorCenterHandler);
+    /**
+     * Checks if a cause with specific code exists.
+     *
+     * Проверяет наличие причины с конкретным кодом.
+     * @param code error code / код ошибки
+     * @param group error group / группа ошибки
+     * @returns true if cause exists / true, если причина существует
+     */
+    has(code: string, group?: string): boolean;
+    /**
+     * Gets a specific error cause by code and group.
+     *
+     * Получает конкретную причину ошибки по коду и группе.
+     * @param code error code / код ошибки
+     * @param group error group / группа ошибки
+     * @returns error cause item or undefined / элемент причины ошибки или undefined
+     */
+    get(code: string, group?: string): ErrorCenterCauseItem | undefined;
+    /**
+     * Adds an error cause to the storage.
+     *
+     * Добавляет причину ошибки в хранилище.
+     * @param cause error cause item / элемент причины ошибки
+     * @returns this instance / текущий экземпляр
+     */
+    add(cause: ErrorCenterCauseItem): this;
+    /**
+     * Adds a list of error causes to the storage.
+     *
+     * Добавляет список причин ошибок в хранилище.
+     * @param causes error causes list / список причин ошибок
+     * @returns this instance / текущий экземпляр
+     */
+    addList(causes: ErrorCenterCauseList): this;
+    /**
+     * Registers a new handler.
+     *
+     * Регистрирует новый обработчик.
+     * @param group target group / целевая группа
+     * @param handler handler callback / обратный вызов обработчика
+     * @returns this instance / текущий экземпляр
+     */
+    addHandler(group: ErrorCenterGroup, handler: ErrorCenterHandlerCallback): this;
+    /**
+     * Registers a list of handlers.
+     *
+     * Регистрирует список обработчиков.
+     * @param handlers handlers list / список обработчиков
+     * @returns this instance / текущий экземпляр
+     */
+    addHandlerList(handlers: ErrorCenterHandlerList): this;
+    /**
+     * Triggers error handling for a group.
+     *
+     * Вызывает обработку ошибки для группы.
+     * @param cause error cause details / детали причины ошибки
+     * @returns this instance / текущий экземпляр
+     */
+    on(cause: ErrorCenterCauseItem): this;
+    /**
+     * Merges provided cause with stored cause data.
+     *
+     * Объединяет предоставленную причину с сохраненными данными причины.
+     * @param cause input cause / входная причина
+     * @returns merged error cause / объединенная причина ошибки
+     */
+    protected assign(cause: ErrorCenterCauseItem): ErrorCenterCauseItem;
+}

package/dist/classes/EventItem.d.ts

@@ -0,0 +1,251 @@
+import { ElementOrString, ElementOrWindow, EventActivityItem, EventListenerDetail, EventOptions } from '../types/basicTypes';
+/**
+ * Advanced wrapper for managing event listeners on DOM elements or the `window` object.
+ *
+ * `EventItem` simplifies the entire event lifecycle (start, stop, toggle, reset), provides
+ * built-in optimizations for high-frequency events, and ensures DOM safety by automatically
+ * checking if elements are still in the document.
+ *
+ * ### Key Features:
+ * - **Lifecycle Control**: Easily `start`, `stop`, `toggle`, or `reset` event listeners.
+ * - **DOM Safety**: Automatically halts the event if the target element is removed from the DOM.
+ * - **Specialized Optimizations**:
+ *   - `resize`: Uses `ResizeObserver` for any HTML element (not limited to `window`).
+ *   - `scroll-sync`: High-performance scroll tracking using `requestAnimationFrame`.
+ * - **Dynamic Configuration**: Chained setters for target element, event type, listener, and options.
+ * - **Custom Event Dispatching**: Built-in support for triggering events with custom data via `dispatch`.
+ * - **Strict Typing**: Generic support for elements, event objects, and custom detail data.
+ *
+ * ---
+ *
+ * Продвинутая обертка для управления слушателями событий на DOM-элементах или объекте `window`.
+ *
+ * `EventItem` упрощает весь жизненный цикл событий (запуск, остановка, переключение, сброс),
+ * предоставляет встроенную оптимизацию для тяжелых событий и гарантирует безопасность работы с DOM,
+ * автоматически проверяя наличие элементов в документе.
+ *
+ * ### Ключевые особенности:
+ * - **Управление циклом**: Простой контроль через методы `start`, `stop`, `toggle` и `reset`.
+ * - **Безопасность DOM**: Автоматическая остановка события, если целевой элемент удален из DOM.
+ * - **Специальные оптимизации**:
+ *   - `resize`: Использует `ResizeObserver` для любых HTML-элементов (не только для `window`).
+ *   - `scroll-sync`: Высокопроизводительный трекинг скролла через `requestAnimationFrame`.
+ * - **Динамическая настройка**: Чейнинг сеттеров для смены цели, типа события, метода или опций.
+ * - **Диспетчеризация**: Встроенная поддержка вызова событий с передачей пользовательских данных через `dispatch`.
+ * - **Строгая типизация**: Поддержка дженериков для типа элемента, объекта события и структуры данных.
+ *
+ * ---
+ *
+ * ### Usage Examples / Примеры использования:
+ *
+ * #### 1. Basic Listener / Базовый слушатель
+ * ```typescript
+ * const clickEvent = new EventItem('.btn', 'click', (e) => console.log('Clicked!'));
+ * clickEvent.start();
+ * ```
+ *
+ * #### 2. Specialized 'resize' and 'scroll-sync' / Оптимизированные 'resize' и 'scroll-sync'
+ * ```typescript
+ * // Tracks any element's size / Отслеживает размер любого элемента
+ * const resizeEvent = new EventItem('.box', 'resize', (entry) => console.log('New size:', entry));
+ *
+ * // Performance-optimized scroll / Оптимизированный скролл
+ * const scrollEvent = new EventItem(window, 'scroll-sync', () => console.log('Scrolling...'));
+ *
+ * resizeEvent.start();
+ * scrollEvent.start();
+ * ```
+ *
+ * #### 3. Custom Data and Dispatching / Пользовательские данные и диспетчеризация
+ * ```typescript
+ * interface UserData { id: number }
+ * const emitter = new EventItem<Window, CustomEvent, UserData>(window, 'user-update');
+ *
+ * emitter.setListener((e, detail) => {
+ *   console.log('Update received for ID:', detail?.id);
+ * });
+ *
+ * emitter.start();
+ *
+ * // Trigger manually with data / Вызов вручную с данными
+ * emitter.dispatch({ id: 456 });
+ * ```
+ *
+ * #### 4. Chaining and Dynamic Updates / Чейнинг и динамическое обновление
+ * ```typescript
+ * const tracker = new EventItem('.item-1', 'mousemove', (e) => console.log(e.clientX));
+ *
+ * // Switch element on the fly / Переключение элемента "на лету"
+ * tracker.start().setElement('.item-2');
+ * ```
+ */
+export declare class EventItem<E extends ElementOrWindow, O extends Event, D extends Record<string, any> = Record<string, any>> {
+    protected listener?: EventListenerDetail<O, D> | undefined;
+    protected options?: EventOptions;
+    protected detail?: D | undefined;
+    /**
+     * Element.
+     *
+     * Элемент.
+     */
+    protected element?: E;
+    /**
+     * Element for checking. If the element is missing in the DOM, the event is turned off.
+     *
+     * Элемент для проверки. Если элемент отсутствует в DOM, событие выключается.
+     */
+    protected elementControl?: ElementOrWindow;
+    protected elementControlEdit?: boolean;
+    /**
+     * A case-sensitive string representing the event type to listen for.
+     *
+     * Чувствительная к регистру строка, представляющая тип обрабатываемого события.
+     */
+    protected type: string[];
+    /**
+     * The object that receives a notification (an object that implements the Event interface)
+     * when an event of the specified type occurs. This must be null, an object with a
+     * handleEvent() method, or a JavaScript function.
+     *
+     * Объект, который принимает уведомление, когда событие указанного типа произошло.
+     * Это должен быть объект, реализующий интерфейс EventListener или просто функция JavaScript.
+     */
+    protected listenerRecent: (event?: O | ResizeObserverEntry) => void;
+    /**
+     * Event states.
+     *
+     * Состояния события.
+     */
+    protected activity: boolean;
+    protected activityItems: EventActivityItem<E>[];
+    /**
+     * Constructor for EventItem.
+     *
+     * Конструктор для EventItem.
+     * @param elementSelector target element or selector where the listener should be attached / целевой элемент или селектор, к которому должен быть прикреплен слушатель
+     * @param type event type (e.g., 'click'), array of types, or special optimization types ('resize', 'scroll-sync') / тип события (например, 'click'), массив типов или специальные типы оптимизации ('resize', 'scroll-sync')
+     * @param listener the handler function to be executed when the event occurs / функция-обработчик, которая будет выполнена при возникновении события
+     * @param options standard EventListenerOptions or boolean for useCapture / стандартные EventListenerOptions или логическое значение для useCapture
+     * @param detail additional data provided to the listener via the custom Event interaction / дополнительные данные, предоставляемые слушателю через кастомное взаимодействие с событием
+     */
+    constructor(elementSelector?: ElementOrString<E>, type?: string | string[], listener?: EventListenerDetail<O, D> | undefined, options?: EventOptions, detail?: D | undefined);
+    /**
+     * Checks whether event listening is currently enabled.
+     *
+     * Проверяет, включено ли сейчас прослушивание события.
+     * @returns true if active / true, если активно
+     */
+    isActive(): boolean;
+    /**
+     * Returns the target element.
+     *
+     * Возвращает целевой элемент.
+     * @returns target element / целевой элемент
+     */
+    getElement(): E | undefined;
+    /**
+     * Change of an element for tracking.
+     *
+     * Изменение элемента для прослеживания.
+     * @param elementSelector target element or selector / целевой элемент или селектор
+     * @returns this instance / текущий экземпляр
+     */
+    setElement(elementSelector?: ElementOrString<E>): this;
+    /**
+     * Modifies the control element for DOM safety checks.
+     *
+     * Модифицирует контрольный элемент для проверки безопасности DOM.
+     * @param elementSelector control element or selector / контрольный элемент или селектор
+     * @returns this instance / текущий экземпляр
+     */
+    setElementControl<EC extends HTMLElement>(elementSelector?: ElementOrString<EC>): this;
+    /**
+     * Changes the type of the handled event.
+     *
+     * Изменяет тип обрабатываемого события.
+     * @param type event type or array of types / тип события или массив типов
+     * @returns this instance / текущий экземпляр
+     */
+    setType(type: string | string[]): this;
+    /**
+     * Modifies the listener function.
+     *
+     * Модифицирует функцию-слушатель.
+     * @param listener new listener function / новая функция-слушатель
+     * @returns this instance / текущий экземпляр
+     */
+    setListener(listener: EventListenerDetail<O, D>): this;
+    /**
+     * Modifying the options object that defines the characteristics of the event listener.
+     *
+     * Изменение объекта options, который определяет характеристики слушателя событий.
+     * @param options event listener options / опции слушателя событий
+     * @returns this instance / текущий экземпляр
+     */
+    setOptions(options?: EventOptions): this;
+    /**
+     * Modifying the additional data provided to the listener.
+     *
+     * Изменение дополнительных данных, передаваемых слушателю.
+     * @param detail custom data / пользовательские данные
+     * @returns this instance / текущий экземпляр
+     */
+    setDetail(detail?: D): this;
+    /**
+     * Triggers the events on the target element, optionally with a new detail value.
+     * This method manually initiates a `CustomEvent` dispatch for all specified types.
+     *
+     * Инициирует события на целевом элементе, опционально с новым значением detail.
+     * Этот метод вручную запускает диспетчеризацию `CustomEvent` для всех указанных типов.
+     * @param detail the value to be passed as the event detail / значение, которое будет передано как detail события
+     * @returns this instance / текущий экземпляр
+     */
+    dispatch(detail?: D | undefined): this;
+    /**
+     * Starts event listening.
+     *
+     * Запуск прослушивания события.
+     * @returns this instance / текущий экземпляр
+     */
+    start(): this;
+    /**
+     * Stops event listening.
+     *
+     * Остановка прослушивания события.
+     * @returns this instance / текущий экземпляр
+     */
+    stop(): this;
+    /**
+     * Toggling event handler state.
+     *
+     * Переключение состояния работы события.
+     * @param activity event activation/ активация события
+     * @returns this instance / текущий экземпляр
+     */
+    toggle(activity: boolean): this;
+    /**
+     * Overloads the listening events (stops and starts again if active).
+     *
+     * Перегружает события прослушивания (останавливает и запускает заново, если активно).
+     * @returns this instance / текущий экземпляр
+     */
+    reset(): this;
+    /**
+     * Checks if the ResizeObserver object exists.
+     *
+     * Проверяет, существует ли объект ResizeObserver.
+     */
+    protected isObserver(): boolean;
+    /**
+     * The implementation of the resize event for an element.
+     *
+     * Реализация события изменения размера для элемента.
+     */
+    protected makeResize(): boolean;
+    /**
+     * Implementation of the scroll event for an element.
+     *
+     * Реализация события изменения положения скролла для элемента.
+     */
+    protected makeScroll(): boolean;
+}

package/dist/classes/Formatters.d.ts

@@ -0,0 +1,161 @@
+import { FormattersType, FormattersList, FormattersOptionsList, FormattersOptionsInformation, FormattersOptionsCurrency, FormattersOptionsDate, FormattersOptionsName, FormattersOptionsNumber, FormattersOptionsPlural, FormattersOptionsUnit, FormattersReturn, FormattersListProp, FormattersItemProp } from '../types/formattersTypes';
+/**
+ * Class for formatting a list of data based on provided options.
+ *
+ * Класс для форматирования списка данных на основе предоставленных параметров.
+ * @template Options type of formatting options / тип параметров форматирования.
+ * @template List type of the list of items (can be an array or a single item) / тип списка элементов (может быть массивом или одним элементом).
+ * @template Item type of a single item in the list / тип одного элемента в списке.
+ */
+export declare class Formatters<Options extends FormattersOptionsList = FormattersOptionsList, List extends FormattersListProp = FormattersListProp, Item extends FormattersItemProp<List> = FormattersItemProp<List>> {
+    protected options: Options;
+    protected list?: List | undefined;
+    /**
+     * Constructor
+     *
+     * Конструктор
+     * @param options formatting options for each column/property / параметры форматирования для каждого столбца/свойства
+     * @param list initial list of data to format / начальный список данных для форматирования
+     */
+    constructor(options: Options, list?: List | undefined);
+    /**
+     * Checks if the list is set.
+     *
+     * Проверяет, установлен ли список.
+     * @returns true if the list is set / true, если список установлен
+     */
+    is(): boolean;
+    /**
+     * Checks if the list is an array.
+     *
+     * Проверяет, является ли список массивом.
+     * @returns true if the list is an array / true, если список является массивом
+     */
+    isArray(): this is this & {
+        list: FormattersList<Item>;
+    };
+    /**
+     * Returns the count of records in the list.
+     *
+     * Возвращает количество записей в списке.
+     * @returns count of records / количество записей
+     */
+    length(): number;
+    /**
+     * Returns the current list of data as an array.
+     *
+     * Возвращает текущий список данных в виде массива.
+     * @returns the list of data / список данных
+     */
+    getList(): FormattersList<Item>;
+    /**
+     * Returns the current formatting options.
+     *
+     * Возвращает текущие параметры форматирования.
+     * @returns formatting options / параметры форматирования
+     */
+    getOptions(): Options;
+    /**
+     * Sets the list of data to be formatted.
+     *
+     * Устанавливает список данных для форматирования.
+     * @param list list of data / список данных
+     * @returns this instance / текущий экземпляр
+     */
+    setList(list?: List): this;
+    /**
+     * Formats the entire list or a single item based on the provided options.
+     * Adds formatted values with the suffix 'Format' to each item.
+     *
+     * Форматирует весь список или один элемент на основе предоставленных параметров.
+     * Добавляет отформатированные значения с суффиксом 'Format' к каждому элементу.
+     * @returns FormattersReturn<List, Options> formatted data (list or single item) / отформатированные данные (список или один элемент)
+     */
+    to(): FormattersReturn<List, Options>;
+    /**
+     * Generates formatted data for a single item based on options.
+     *
+     * Генерирует отформатированные данные для одного элемента на основе параметров.
+     * @param item item to format / элемент для форматирования
+     * @returns object with formatted fields / объект с отформатированными полями
+     * @protected
+     */
+    protected getFormatData(item: Item): Record<string, string>;
+    /**
+     * Router-like method to delegate formatting to specific type formatters.
+     *
+     * Метод-маршрутизатор для делегирования форматирования конкретным типам форматировщиков.
+     * @param valueOriginal original value to format/ исходное значение для форматирования
+     * @param item entire item context/ весь контекст элемента
+     * @param type type of formatter to use/ тип используемого форматировщика
+     * @param options additional options for the specific formatter/
+     * дополнительные параметры для конкретного форматировщика
+     * @protected
+     * @returns Formatted string/ отформатированная строка
+     */
+    protected transformation<Type extends FormattersType>(valueOriginal: any, item: any, type?: Type, options?: FormattersOptionsInformation<Type>): string;
+    /**
+     * Formats a value as currency.
+     *
+     * Форматирует значение как валюту.
+     * @param value value to format/ значение для форматирования
+     * @param item item context/ контекст элемента
+     * @param options currency formatting options/ параметры форматирования валюты
+     * @protected
+     * @returns Formatted currency string/ отформатированная строка валюты
+     */
+    protected formatCurrency(value: any, item: Item, options?: FormattersOptionsCurrency): string;
+    /**
+     * Formats a value as a date.
+     *
+     * Форматирует значение как дату.
+     * @param value value to format/ значение для форматирования
+     * @param options date formatting options/ параметры форматирования даты
+     * @protected
+     * @returns Formatted date string/ отформатированная строка даты
+     */
+    protected formatDate(value: any, options?: FormattersOptionsDate): string;
+    /**
+     * Formats full name from multiple property names.
+     *
+     * Форматирует полное имя из нескольких имен свойств.
+     * @param item item context containing name components/ контекст элемента, содержащий компоненты имени
+     * @param options name formatting options (prop names for first, last, surname)/
+     * параметры форматирования имени (имена свойств для имени, фамилии, отчества)
+     * @protected
+     * @returns Formatted name string or empty string if components are missing/
+     * отформатированная строка имени или пустая строка, если компоненты отсутствуют
+     */
+    protected formatName(item: Item, options?: FormattersOptionsName): string;
+    /**
+     * Formats a value as a number.
+     *
+     * Форматирует значение как число.
+     * @param value value to format/ значение для форматирования
+     * @param options number formatting options/ параметры форматирования числа
+     * @protected
+     * @returns Formatted number string/ отформатированная строка числа
+     */
+    protected formatNumber(value: any, options?: FormattersOptionsNumber): string;
+    /**
+     * Formats a value based on plural rules.
+     *
+     * Форматирует значение на основе правил множественного числа.
+     * @param value numeric value for pluralization/ числовое значение для плюрализации
+     * @param options plural formatting options (words and rules)/
+     * параметры форматирования множественного числа (слова и правила)
+     * @protected
+     * @returns Formatted plural string/ отформатированная строка множественного числа
+     */
+    protected formatPlural(value: any, options?: FormattersOptionsPlural): string;
+    /**
+     * Formats a value with a specific unit.
+     *
+     * Форматирует значение с определенной единицей измерения.
+     * @param value value to format/ значение для форматирования
+     * @param options unit formatting options/ параметры форматирования единиц измерения
+     * @protected
+     * @returns Formatted unit string/ отформатированная строка единицы измерения
+     */
+    protected formatUnit(value: any, options?: FormattersOptionsUnit): string;
+}