@dxtmisha/functional-basic 0.10.1 → 0.11.0

package/dist/library.d.ts

@@ -183,7 +183,12 @@ export declare class Api {
 /**
  * Shape of API response data wrapper/ Структура обёртки данных ответа API
  */
-export declare type ApiData<T = any> = T & {
+export declare type ApiData<T = any> = T extends any[] ? T : ApiDataItem<T>;
+
+/**
+ * Type of API response data item/ Тип элемента данных ответа API
+ */
+export declare type ApiDataItem<T = any> = T & {
     /** Primary payload (optional)/ Основная полезная нагрузка (опционально) */
     data?: T;
     /** Success flag/ Флаг успешности */
@@ -677,6 +682,12 @@ export declare type ApiStatusType = 'success' | 'error' | 'warning' | 'info';
  */
 export declare const applyTemplate: (text: string, replacement?: Record<string, string | number> | string[]) => string;
 
+/**
+ * Converts an array type to an item type (extracts the item type from an array)/
+ * Преобразует тип массива в тип элемента (извлекает тип элемента из массива)
+ */
+export declare type ArrayToItem<T> = T extends any[] ? T[number] : T;
+
 /**
  * The method creates an array of "count" elements with values equal to `value`.
  *
@@ -1615,9 +1626,11 @@ export declare type EventActivityItem<E extends ElementOrWindow> = {
 };
 
 /**
- * Class for working with events.
+ * Advanced wrapper for managing event listeners on DOM elements or the `window` object.
+ * It simplifies the entire event lifecycle (start, stop, toggle, reset) and provides built-in optimizations for high-frequency events like `resize` and `scroll-sync`.
  *
- * Класс для работы с событиями.
+ * Продвинутая обертка для управления слушателями событий на DOM-элементах или объекте `window`.
+ * Упрощает весь жизненный цикл событий (запуск, остановка, переключение, сброс) и предоставляет встроенные оптимизации для высокочастотных событий, таких как `resize` и `scroll-sync`.
  */
 export declare class EventItem<E extends ElementOrWindow, O extends Event, D extends Record<string, any> = Record<string, any>> {
     protected listener?: EventListenerDetail<O, D> | undefined;
@@ -1659,15 +1672,14 @@ export declare class EventItem<E extends ElementOrWindow, O extends Event, D ext
     protected activity: boolean;
     protected activityItems: EventActivityItem<E>[];
     /**
-     * Classes Constructor
-     * @param elementSelector element/ элемент
-     * @param type type/ тип
-     * @param listener the object that receives a notification (an object that implements the
-     * Event interface) when an event of the specified type occurs/ объект, который принимает
-     * уведомление, когда событие указанного типа произошло
-     * @param options object that specifies characteristics/ объект options
-     * @param detail an event-dependent value associated with the event/ зависимое от события
-     * значение, связанное с событием
+     * 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);
     /**
@@ -1720,13 +1732,12 @@ export declare class EventItem<E extends ElementOrWindow, O extends Event, D ext
      */
     setDetail(detail?: D): this;
     /**
-     * The method of the EventTarget sends an Event to the object, (synchronously) invoking
-     * the affected EventListeners in the appropriate order.
+     * Triggers the events on the target element, optionally with a new detail value.
+     * This method manually initiates a `CustomEvent` dispatch for all specified types.
      *
-     * Отправляет событие в общую систему событий. Это событие подчиняется тем же правилам
-     * поведения "Захвата" и "Всплывания" как и непосредственно инициированные события.
-     * @param detail an event-dependent value associated with the event/ зависимое от события
-     * значение, связанное с событием
+     * Инициирует события на целевом элементе, опционально с новым значением detail.
+     * Этот метод вручную запускает диспетчеризацию `CustomEvent` для всех указанных типов.
+     * @param detail the value to be passed as the event detail / значение, которое будет передано как detail события
      */
     dispatch(detail?: D | undefined): this;
     /**
@@ -1825,11 +1836,11 @@ export declare function forEach<T, R, D extends T[] | Record<string, T> | Map<st
  * Class for formatting a list of data based on provided options.
  *
  * Класс для форматирования списка данных на основе предоставленных параметров.
- * @template Item - type of items in the list/ тип элементов в списке.
- * @template Options - type of formatting options/ тип параметров форматирования.
- * @template List - type of the list of items/ тип списка элементов.
+ * @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<Item extends FormattersListItem, Options extends FormattersOptionsList, List extends FormattersList<Item> = FormattersList<Item>> {
+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;
     /**
@@ -1841,13 +1852,36 @@ export declare class Formatters<Item extends FormattersListItem, Options extends
      * @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, false otherwise/ true, если список установлен, иначе false
+     */
+    is(): boolean;
+    /**
+     * Checks if the list is an array.
+     *
+     * Проверяет, является ли список массивом.
+     * @returns true if the list is an array, false otherwise/ true, если список является массивом, иначе false
+     */
+    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.
      *
      * Возвращает текущий список данных.
      * @returns the list of data or undefined if not set/ список данных или undefined, если не задан
      */
-    getList(): List | undefined;
+    getList(): FormattersList<Item>;
     /**
      * Returns the current formatting options.
      *
@@ -1862,17 +1896,17 @@ export declare class Formatters<Item extends FormattersListItem, Options extends
      * @param list list of data/ список данных
      * @returns the Formatters instance for chaining/ экземпляр Formatters для цепочки вызовов
      */
-    setList(list: List): this;
+    setList(list?: List): this;
     /**
-     * Formats the entire list based on the provided options.
+     * 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 the list of items with additional formatted columns/
-     * список элементов с дополнительными отформатированными столбцами
+     * @returns formatted data (list or single item) with additional formatted columns /
+     * отформатированные данные (список или один элемент) с дополнительными отформатированными столбцами
      */
-    to(): FormattersListColumns<Item, Options>;
+    to(): FormattersReturn<List, Options>;
     /**
      * Generates formatted data for a single item based on options.
      *
@@ -1960,73 +1994,247 @@ export declare class Formatters<Item extends FormattersListItem, Options extends
     protected formatUnit(value: any, options?: FormattersOptionsUnit): string;
 }
 
+/**
+ * Utility type to capitalize a camelCase or dot-notated string.
+ *
+ * Вспомогательный тип для капитализации строки.
+ *
+ * @template K - The string to capitalize / Строка для капитализации.
+ */
 export declare type FormattersCapitalize<K extends string> = K extends `${infer First}.${infer Rest}` ? `${First}${Capitalize<FormattersCapitalize<Rest>>}` : K;
 
+/**
+ * Utility type to extract column keys from formatting options.
+ *
+ * Вспомогательный тип для извлечения ключей столбцов.
+ *
+ * @template T - The formatting options list type / Тип списка параметров форматирования.
+ */
 export declare type FormattersColumns<T extends FormattersOptionsList> = (keyof T & string)[];
 
+/**
+ * Represents a data item with additional formatted properties.
+ *
+ * Представляет элемент данных с доп. отформатированными свойствами.
+ *
+ * @template T - The original item type / Исходный тип элемента.
+ * @template KT - Array of property keys / Массив ключей свойств.
+ */
 export declare type FormattersDataItem<T extends FormattersListItem, KT extends string[]> = {
     [K in keyof T | FormattersKey<KT[number]>]: K extends keyof T ? T[K] : string;
 };
 
+/**
+ * Extracts the single item type from a single item or a list of items.
+ *
+ * Извлекает тип одного элемента из одного элемента или из списка элементов.
+ *
+ * @template List - The type of the input data / Тип входных данных.
+ */
+export declare type FormattersItemProp<List extends FormattersListProp> = ArrayToItem<List>;
+
+/**
+ * Utility type to generate a formatted property key.
+ *
+ * Вспомогательный тип для генерации ключа отформатированного свойства.
+ *
+ * @template K - The original property key / Ключ исходного свойства.
+ * @template A - The suffix to add / Суффикс.
+ */
 export declare type FormattersKey<K, A extends string = 'Format'> = K extends string ? `${FormattersCapitalize<K>}${A}` : never;
 
+/**
+ * An array of data items to be formatted.
+ *
+ * Массив элементов данных для форматирования.
+ *
+ * @template Item - The type of data items / Тип элементов данных.
+ */
 export declare type FormattersList<Item extends FormattersListItem> = Item[];
 
+/**
+ * A single data item formatted based on the provided options list.
+ *
+ * Один элемент данных, отформатированный на основе параметров.
+ *
+ * @template T - The original item type / Исходный тип элемента.
+ * @template O - The formatting options / Параметры форматирования.
+ */
+export declare type FormattersListColumnItem<T extends FormattersListItem, O extends FormattersOptionsList> = FormattersDataItem<T, FormattersColumns<O>>;
+
+/**
+ * A list of data items formatted based on the provided options list.
+ *
+ * Список элементов данных, отформатированных на основе параметров.
+ *
+ * @template T - The original item type / Исходный тип элемента.
+ * @template O - The formatting options / Параметры форматирования.
+ */
 export declare type FormattersListColumns<T extends FormattersListItem, O extends FormattersOptionsList> = FormattersListFormat<T, FormattersColumns<O>>;
 
+/**
+ * An array of data items with additional formatted properties.
+ *
+ * Массив элементов данных с доп. отформатированными свойствами.
+ *
+ * @template T - The original item type / Исходный тип элемента.
+ * @template K - Array of property keys / Массив ключей свойств.
+ */
 export declare type FormattersListFormat<T extends FormattersListItem, K extends string[]> = FormattersDataItem<T, K>[];
 
+/**
+ * Represents a single data item as a key-value record.
+ *
+ * Представляет один элемент данных как запись "ключ-значение".
+ */
 export declare type FormattersListItem = Record<string, any>;
 
+/**
+ * Possible formats for input data: either a single item or a list of items.
+ *
+ * Возможные форматы входных данных: либо один элемент, либо список элементов.
+ */
+export declare type FormattersListProp = FormattersList<FormattersListItem> | FormattersListItem;
+
+/**
+ * Options for currency formatting.
+ *
+ * Параметры для форматирования валюты.
+ */
 export declare type FormattersOptionsCurrency = {
+    /** The name of the property in the data item that contains the currency code / Имя свойства в элементе данных, которое содержит код валюты. */
     currencyPropName?: string;
+    /** Currency code or international number format options / Код валюты или международные параметры форматирования чисел. */
     options?: string | Intl.NumberFormatOptions;
+    /** If true, only the numeric value will be returned / Если true, будет возвращено только числовое значение. */
     numberOnly?: boolean;
 };
 
+/**
+ * Options for date formatting.
+ *
+ * Параметры для форматирования даты.
+ */
 export declare type FormattersOptionsDate = {
+    /** The type of date representation / Тип представления даты. */
     type?: GeoDate;
+    /** International date-time format options / Междунар. параметры форматирования даты и времени. */
     options?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions;
+    /** Use 24-hour format if true / Использовать 24-часовой формат, если true. */
     hour24?: boolean;
 };
 
+/**
+ * Mapping of formatter types to their respective option types.
+ *
+ * Соответствие типов форматировщиков их типам параметров.
+ *
+ * @template Type - The formatter type / Тип форматировщика.
+ */
 export declare type FormattersOptionsInformation<Type extends FormattersType> = Type extends FormattersType.currency ? FormattersOptionsCurrency : Type extends FormattersType.date ? FormattersOptionsDate : Type extends FormattersType.name ? FormattersOptionsName : Type extends FormattersType.number ? FormattersOptionsNumber : Type extends FormattersType.plural ? FormattersOptionsPlural : Type extends FormattersType.unit ? FormattersOptionsUnit : Record<string, any>;
 
+/**
+ * Configuration for a single property formatter.
+ *
+ * Конфигурация для форматировщика одного свойства.
+ *
+ * @template Type - The type of formatter / Тип форматировщика.
+ * @template R - The return type / Возвращаемый тип.
+ */
 export declare type FormattersOptionsItem<Type extends FormattersType = FormattersType, R = string> = {
+    /** The type of formatter / Тип форматировщика. */
     type?: Type;
+    /** Custom transformation function / Пользовательская функция преобразования. */
     transformation?: (valueOriginal: any, item: any, options?: FormattersOptionsInformation<Type>) => R;
+    /** Options for the specified formatter type / Параметры для указанного типа форматировщика. */
     options?: FormattersOptionsInformation<Type>;
 };
 
+/**
+ * A dictionary mapping property paths to their formatting configurations.
+ *
+ * Словарь, сопоставляющий пути к свойствам с их конфигурациями форматирования.
+ */
 export declare type FormattersOptionsList = Record<string, FormattersOptionsItem>;
 
+/**
+ * Options for name formatting.
+ *
+ * Параметры для форматирования имени.
+ */
 export declare type FormattersOptionsName = {
+    /** Property name for the last name / Имя свойства для фамилии. */
     lastPropName?: string;
+    /** Property name for the first name / Имя свойства для имени. */
     firstPropName?: string;
+    /** Property name for the middle name / Имя свойства для отчества. */
     surname?: string;
+    /** If true, returns a short version of the name / Если true, возвращает сокращенную версию имени. */
     short?: boolean;
 };
 
+/**
+ * Options for number formatting.
+ *
+ * Параметры для форматирования чисел.
+ */
 export declare type FormattersOptionsNumber = {
+    /** International number format options / Междунар. параметры форматирования чисел. */
     options?: Intl.NumberFormatOptions;
 };
 
+/**
+ * Options for plural forms formatting.
+ *
+ * Параметры для форматирования форм множественного числа.
+ */
 export declare type FormattersOptionsPlural = {
+    /** A string containing plural forms / Строка, содержащая формы множественного числа. */
     words: string;
+    /** International plural rules options / Междунар. параметры правил множественного числа. */
     options?: Intl.PluralRulesOptions;
+    /** International number format options for the numeric part / Междунар. параметры форматирования чисел для числовой части. */
     optionsNumber?: Intl.NumberFormatOptions;
 };
 
+/**
+ * Options for unit formatting.
+ *
+ * Параметры для форматирования единиц измерения.
+ */
 export declare type FormattersOptionsUnit = {
+    /** The unit to format or international number format options / Ед. изм. для форматирования или междунар. параметры форматирования чисел. */
     unit: string | Intl.NumberFormatOptions;
 };
 
+/**
+ * The return type of the formatter, matching the structure of the input data.
+ *
+ * Возвращаемый тип форматировщика, соответствующий структуре входных данных.
+ *
+ * @template List - The input data type / Тип входных данных.
+ * @template Options - The formatting options / Параметры форматирования.
+ * @template Item - The type of a single item / Тип одного элемента.
+ */
+export declare type FormattersReturn<List extends FormattersListProp, Options extends FormattersOptionsList = FormattersOptionsList, Item extends FormattersItemProp<List> = FormattersItemProp<List>> = List extends any[] ? FormattersListColumns<Item, Options> : (FormattersListColumnItem<Item, Options> | undefined);
+
+/**
+ * Enumeration of available formatter types.
+ *
+ * Перечисление доступных типов форматировщиков.
+ */
 export declare enum FormattersType {
+    /** Currency formatting / Форматирование валюты. */
     currency = "currency",
+    /** Date formatting / Форматирование даты. */
     date = "date",
+    /** Name formatting / Форматирование имени. */
     name = "name",
+    /** Number formatting / Форматирование чисел. */
     number = "number",
+    /** Plural forms formatting / Форматирование форм множественного числа. */
     plural = "plural",
+    /** Unit formatting (e.g., meters, kilograms) / Форматирование единиц измерения (например, метры, килограммы). */
     unit = "unit"
 }
 
@@ -2599,6 +2807,18 @@ export declare class GeoIntl {
      * @param compareFn a function for sorting/ функция для сортировки
      */
     sort<T>(data: T[], compareFn?: (a: T, b: T) => [string, string]): T[];
+    /**
+     * Checks if the Intl object is available.
+     *
+     * Проверяет доступность объекта Intl.
+     */
+    private hasIntl;
+    /**
+     * Checks if the Intl.DateTimeFormat object is available.
+     *
+     * Проверяет доступность объекта Intl.DateTimeFormat.
+     */
+    private hasIntlDateTimeFormat;
     /**
      * The object enables language-sensitive number formatting.
      *
@@ -3281,6 +3501,14 @@ export declare function initScrollbarOffset(): Promise<void>;
  */
 export declare function intersectKey<T, KT extends keyof T, C, KC extends keyof C>(data?: T, comparison?: C): Record<KT & KC, T[KT]>;
 
+/**
+ * Checks if the API response is successful.
+ *
+ * Проверяет, является ли ответ API успешным.
+ * @param data API response data/ данные ответа API
+ */
+export declare const isApiSuccess: <T>(data: ApiData<T>) => boolean;
+
 /**
  * Checks if the values are arrays.
  *