@mediacubeco/base 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1243 @@
+/**
+ * @packageDocumentation
+ * @description
+ * Общие утилитарные типы для проектов на TypeScript.
+ * Содержит типы для примитивов (Nullable, NotNullable), структур данных
+ * (BaseRecord, Entry, List), функций (Callback, AsyncCallback) и вспомогательные
+ * утилиты (KeyOf, ValueOf, Decrement, Increment и др.).
+ * Модуль не содержит рантайм-кода — только типы.
+ *
+ * @example
+ * ```typescript
+ * type User = { id: number; name?: string | null }
+ *
+ * type UserId = ValueOf<Pick<User, 'id'>>
+ * type SafeName = NotNullable<User['name']>
+ * ```
+ */
+type NullablePrimitive = undefined | null;
+/**
+ * Ключи объекта `Data`. Удобный псевдоним для `keyof`.
+ *
+ * @example
+ * ```typescript
+ * type UserKeys = KeyOf<{ id: number; name: string }> // 'id' | 'name'
+ * ```
+ */
+type KeyOf<Data> = keyof Data;
+/**
+ * Объединение всех возможных значений объекта `Data`.
+ *
+ * @example
+ * ```typescript
+ * type UserValue = ValueOf<{ id: number; name: string }> // number | string
+ * ```
+ */
+type ValueOf<Data> = Data[KeyOf<Data>];
+/** Тип одного элемента массива или кортежа. */
+type IterableOf<Data extends unknown[]> = Data[number];
+/** Служебный псевдоним для `never` или другого "пустого" значения. */
+type Nothing<Data = never> = Data;
+/**
+ * Тип, допускающий null или undefined (например для опциональных полей).
+ *
+ * @example
+ * ```typescript
+ * type MaybeName = Nullable<string> // string | null | undefined
+ * ```
+ */
+type Nullable<Data = undefined> = Data | NullablePrimitive;
+/**
+ * Тип, исключающий null и undefined (гарантированно заданное значение).
+ *
+ * @example
+ * ```typescript
+ * type Name = NotNullable<string | null | undefined> // string
+ * ```
+ */
+type NotNullable<Data = undefined> = Exclude<Data, NullablePrimitive>;
+/** Число или значение, которое можно привести к числу, включая строковый литерал числа. */
+type Numerable<Data = number> = Data | number | `${number}`;
+/** Значение, которое может быть как синхронным, так и обёрнутым в Promise. */
+type MaybeAsync<Data = never> = Data | Promise<Data>;
+/**
+ * Допустимые ключи объекта (как в Record).
+ *
+ * @example
+ * ```typescript
+ * type Key = BaseKey // string | number | symbol
+ * ```
+ */
+type BaseKey = string | number | symbol;
+/**
+ * Массив элементов (базовый тип для списков).
+ *
+ * @example
+ * ```typescript
+ * type IdList = BaseList<number> // number[]
+ * ```
+ */
+type BaseList<Item = unknown> = Item[];
+/**
+ * Объект с ключами Key и значениями Value (обобщение Record).
+ *
+ * @example
+ * ```typescript
+ * type UserMap = BaseRecord<string, 'name' | 'role'>
+ * ```
+ */
+type BaseRecord<Value = unknown, Key extends BaseKey = BaseKey> = Record<Key, Value>;
+/** Объединение `{ key, value }` для каждой пары ключ-значение объекта. */
+type Entry<Data> = {
+    [Key in KeyOf<Data>]: {
+        key: Key;
+        value: Data[Key];
+    };
+}[KeyOf<Data>];
+/** Делает указанные ключи обязательными, а остальные оставляет опциональными. */
+type Include<Data, Key extends KeyOf<Data>> = Required<Pick<Data, Key>> & Partial<Omit<Data, Key>>;
+/** Разделяет объект на кортеж из выбранных и оставшихся свойств. */
+type Divide<Data, Key extends KeyOf<Data>> = [Pick<Data, Key>, Omit<Data, Key>];
+/** Заполняет набор ключей значениями из `Data` или `DefaultValue`, если ключ отсутствует. */
+type Filled<Data, Key extends BaseKey, DefaultValue = undefined> = {
+    [SomeKey in Key]: SomeKey extends KeyOf<Data> ? Data[SomeKey] : DefaultValue;
+};
+/** Общая часть нескольких объектов: только совпадающие ключи и совместимые типы значений. */
+type Shared<DataList extends BaseList[], FirstData extends IterableOf<DataList> = IterableOf<DataList>, SecondData extends IterableOf<DataList> = IterableOf<DataList>> = {
+    [Key in KeyOf<FirstData> & KeyOf<SecondData>]: FirstData[Key] extends SecondData[Key] ? FirstData[Key] : never;
+};
+/**
+ * Кортеж фиксированной длины `Length`, заполненный элементами типа `Item`.
+ *
+ * @example
+ * ```typescript
+ * type Pair = List<2, string> // [string, string]
+ * ```
+ */
+type List<Length extends number, Item = unknown, ResultList extends Item[] = []> = Length extends ResultList['length'] ? ResultList : List<Length, Item, [...ResultList, Item]>;
+/**
+ * Уменьшает числовой литерал на единицу.
+ *
+ * @example
+ * ```typescript
+ * type Two = Decrement<3> // 2
+ * ```
+ */
+type Decrement<Value extends number> = List<Value> extends [infer _, ...infer Rest] ? Rest['length'] : never;
+/**
+ * Увеличивает числовой литерал на единицу.
+ *
+ * @example
+ * ```typescript
+ * type Four = Increment<3> // 4
+ * ```
+ */
+type Increment<Value extends number> = [...List<Value>, IterableOf<List<Value>>]['length'];
+/**
+ * Функция без аргументов и возвращаемого значения.
+ *
+ * @example
+ * ```typescript
+ * const noop: Noop = () => {}
+ * ```
+ */
+type Noop = () => void;
+/**
+ * Синхронная функция с заданным списком параметров и результатом.
+ * @template ParamList - кортеж типов аргументов
+ * @template Result - тип возвращаемого значения
+ *
+ * @example
+ * ```typescript
+ * type Sum = Callback<[number, number], number>
+ * ```
+ */
+type Callback<ParamList extends BaseList = BaseList, Result = void> = (...paramList: ParamList) => Result;
+/**
+ * Асинхронная функция с заданным списком параметров и результатом.
+ *
+ * @example
+ * ```typescript
+ * type FetchUser = AsyncCallback<[string], { id: string }>
+ * ```
+ */
+type AsyncCallback<ParamList extends BaseList = BaseList, Result = void> = (...paramList: ParamList) => Promise<Result>;
+/** Любая синхронная функция без ограничений на аргументы и результат. */
+type AnyCallback = Callback<any[], any>;
+/** Любая асинхронная функция без ограничений на аргументы и результат. */
+type AnyAsyncCallback = AsyncCallback<any[], any>;
+/** Извлекает кортеж аргументов из типа функции. */
+type CallbackParamList<Callback> = Callback extends (...args: infer ParamList) => any ? ParamList : never;
+/** Извлекает тип возвращаемого значения из типа функции. */
+type CallbackResult<Callback> = Callback extends (...args: any) => infer Result ? Result : any;
+
+type ExtraSizeRange<Level extends number, Value extends string, Result extends string = `x${Value}`> = Level extends 1 ? Result : ExtraSizeRange<Decrement<Level>, Value, `${Level}x${Value}` | Result>;
+/**
+ * Набор строковых размеров относительно базовых `s`, `m`, `l`.
+ * Позволяет расширять диапазон вниз (`xs`, `2xs`, ...) и вверх (`xl`, `2xl`, ...).
+ *
+ * @example
+ * ```typescript
+ * type ButtonSize = SizeRange<2, 1> // '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl'
+ * ```
+ */
+type SizeRange<ExtraLevelDown extends number = 1, ExtraLevelUp extends number = 1> = ExtraSizeRange<ExtraLevelDown, 's'> | 's' | 'm' | 'l' | ExtraSizeRange<ExtraLevelUp, 'l'>;
+/**
+ * Объединение чисел от `1` до `Level`.
+ *
+ * @example
+ * ```typescript
+ * type Steps = LevelRange<3> // 1 | 2 | 3
+ * ```
+ */
+type LevelRange<Level extends number, Result extends number = Level> = Level extends 1 ? Result : LevelRange<Decrement<Level>, Result | Decrement<Level>>;
+
+declare class Event {
+    isDefaultPrevented: boolean;
+    constructor();
+    preventDefault(): void;
+    overrideDefault(): void;
+}
+
+type EventEmitterDefaultAction = Noop;
+type EventEmitterListener<Params> = Callback<[Event & Params]>;
+
+/**
+ * Имена событий, которые генерирует `ErrorHandler`.
+ */
+declare enum ErrorHandlerEventName {
+    /** Ошибка была залогирована и передана подписчикам без выбрасывания. */
+    Capture = "capture",
+    /** Зарезервированное имя события для проброса ошибки дальше по цепочке. */
+    Forward = "forward"
+}
+
+/**
+ * Сообщение об ошибке для пользователя или лога.
+ *
+ * @example
+ * ```typescript
+ * const message: ErrorHandlerMessage = 'Request failed'
+ * ```
+ */
+type ErrorHandlerMessage = string;
+/**
+ * Любое значение, которое может быть перехвачено как ошибка (Error или unknown).
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorHandlerError = new Error('Timeout')
+ * ```
+ */
+type ErrorHandlerError = unknown;
+/**
+ * Словарь ошибок валидации (например поле → сообщение или список сообщений).
+ *
+ * @example
+ * ```typescript
+ * const errors: ErrorHandlerErrors<'email'> = { email: 'Invalid email' }
+ * ```
+ */
+type ErrorHandlerErrors<Key extends BaseKey = BaseKey, Value = Nullable<string | string[]>> = BaseRecord<Value, Key>;
+/**
+ * Результат разбора ошибки через ErrorHandler.parse.
+ * Используется для единообразного представления ошибок API (message, status, errors, isExternal).
+ *
+ * @example
+ * ```typescript
+ * const result: ErrorHandlerParseResult<'email'> = {
+ *   message: 'Validation failed',
+ *   status: 422,
+ *   errors: { email: 'Invalid email' },
+ *   isExternal: true
+ * }
+ * ```
+ */
+type ErrorHandlerParseResult<Key extends BaseKey> = {
+    message: string;
+    status: number;
+    errors: ErrorHandlerErrors<Key>;
+    isExternal: boolean;
+};
+/**
+ * Конфиг одного «кейса» для ErrorHandler.parse: проверка типа ошибки и функция разбора.
+ * Регистрируется через ErrorHandler.case().
+ *
+ * @example
+ * ```typescript
+ * const config: ErrorHandlerCaseConfig<Response> = {
+ *   check: (error): error is Response => error instanceof Response,
+ *   parse: (error, defaultResult) => ({ ...defaultResult, status: error.status })
+ * }
+ * ```
+ */
+type ErrorHandlerCaseConfig<ErrorHandlerCaseError = any> = {
+    check: <Key extends BaseKey>(error: ErrorHandlerError, defaultResult: ErrorHandlerParseResult<Key>) => error is ErrorHandlerCaseError;
+    parse: <Key extends BaseKey>(error: ErrorHandlerCaseError, defaultResult: ErrorHandlerParseResult<Key>) => ErrorHandlerParseResult<Key>;
+};
+/**
+ * Конфигурация при логировании/пробросе ошибки (signal, опциональные message, payload, stack).
+ *
+ * @example
+ * ```typescript
+ * const config: ErrorHandlerConfig = {
+ *   signal: 'api',
+ *   message: 'Cannot load profile'
+ * }
+ * ```
+ */
+type ErrorHandlerConfig = {
+    signal: string;
+    message?: ErrorHandlerMessage;
+    payload?: BaseRecord<unknown>;
+    stack?: string[];
+};
+/**
+ * Параметры события capture/forward: ошибка и конфиг.
+ *
+ * @example
+ * ```typescript
+ * const params: ErrorHandlerEventParams = {
+ *   error: new Error('Timeout'),
+ *   config: { signal: 'api' }
+ * }
+ * ```
+ */
+type ErrorHandlerEventParams = {
+    error: ErrorHandlerError;
+    config: ErrorHandlerConfig;
+};
+
+/**
+ * Централизованная обработка ошибок: логирование, подписка на события, разбор ошибок по кейсам.
+ * Статический класс; подписка через on('capture', …), регистрация кейсов через case().
+ * capture — залогировать и вызвать событие, не бросать; forward — залогировать, вызвать событие и пробросить.
+ *
+ * @example
+ * ```typescript
+ * ErrorHandler.on(ErrorHandlerEventName.Capture, ({ error }) => {
+ *   console.error(error)
+ * })
+ *
+ * ErrorHandler.capture(new Error('Request failed'), { signal: 'api' })
+ * ```
+ */
+declare class ErrorHandler {
+    private static eventEmitter;
+    private static caseList;
+    private static log;
+    /**
+     * Доступ к подписке на события обработчика ошибок.
+     * Обычно используется как `ErrorHandler.on(ErrorHandlerEventName.Capture, listener)`.
+     *
+     * @returns Метод подписки `EventEmitter.on`
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.on(ErrorHandlerEventName.Capture, ({ config }) => {
+     *   console.log(config.signal)
+     * })
+     * ```
+     */
+    static get on(): (name: ErrorHandlerEventName, listener: EventEmitterListener<ErrorHandlerEventParams>) => () => void;
+    /**
+     * Доступ к удалению конкретного подписчика обработчика ошибок.
+     *
+     * @returns Метод отписки `EventEmitter.off`
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.off(ErrorHandlerEventName.Capture, listener)
+     * ```
+     */
+    static get off(): (name: ErrorHandlerEventName, listener: EventEmitterListener<ErrorHandlerEventParams>) => void;
+    /**
+     * Доступ к очистке подписок по имени события.
+     *
+     * @returns Метод очистки `EventEmitter.clear`
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.clear(ErrorHandlerEventName.Capture)
+     * ```
+     */
+    static get clear(): (name: ErrorHandlerEventName) => void;
+    /**
+     * Создаёт экземпляр Error с сообщением и опциональной причиной (cause).
+     *
+     * @param message - Текст ошибки
+     * @param error - Исходная ошибка или причина
+     * @returns Новый объект Error (не бросается)
+     *
+     * @example
+     * ```typescript
+     * const error = ErrorHandler.create('Request failed', new Error('Timeout'))
+     * ```
+     */
+    static create(message: ErrorHandlerMessage, error?: ErrorHandlerError): Error;
+    /**
+     * Создаёт ошибку и немедленно бросает её (never).
+     * Используется для заглушек (например «Not implemented»).
+     *
+     * @param message - Текст ошибки
+     * @param error - Исходная ошибка или причина
+     * @returns Управление не возвращается, так как метод выбрасывает исключение
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.throw('Not implemented')
+     * ```
+     */
+    static throw(message: ErrorHandlerMessage, error?: ErrorHandlerError): never;
+    /**
+     * Логирует ошибку и эмитит событие 'capture'. Ошибку не бросает.
+     * Подписчики могут отправить данные в мониторинг и т.д.
+     *
+     * @param error - Ошибка или любое перехваченное значение
+     * @param config - Конфигурация логирования и сопровождающих данных
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.capture(new Error('Request failed'), {
+     *   signal: 'api',
+     *   message: 'Cannot load profile'
+     * })
+     * ```
+     */
+    static capture(error: ErrorHandlerError, config: ErrorHandlerConfig): void;
+    /**
+     * Логирует ошибку, эмитит 'capture' и пробрасывает ошибку дальше (never).
+     *
+     * @param error - Ошибка или любое перехваченное значение
+     * @param config - Конфигурация логирования и сопровождающих данных
+     * @returns Управление не возвращается, так как метод выбрасывает ошибку дальше
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.forward(new Error('Forbidden'), {
+     *   signal: 'auth'
+     * })
+     * ```
+     */
+    static forward(error: ErrorHandlerError, config: ErrorHandlerConfig): never;
+    /**
+     * Регистрирует кейс для parse: при совпадении check() будет вызван parse().
+     * Порядок регистрации важен — используется первый подходящий кейс.
+     *
+     * @param config - Пара функций `check` и `parse` для пользовательского разбора ошибок
+     *
+     * @example
+     * ```typescript
+     * ErrorHandler.case({
+     *   check: (error): error is Response => error instanceof Response,
+     *   parse: (error, defaultResult) => ({
+     *     ...defaultResult,
+     *     status: error.status
+     *   })
+     * })
+     * ```
+     */
+    static case<ErrorHandlerCaseError>(config: ErrorHandlerCaseConfig<ErrorHandlerCaseError>): void;
+    /**
+     * Разбирает ошибку в единый формат (message, status, errors, isExternal).
+     * Сначала проверяются зарегистрированные кейсы; если ни один не подошёл — базовый разбор (Error.message или default).
+     *
+     * @param error - Ошибка или любое неизвестное значение
+     * @returns Унифицированный результат разбора ошибки
+     *
+     * @example
+     * ```typescript
+     * const parsed = ErrorHandler.parse(new Error('Request failed'))
+     * console.log(parsed.message)
+     * ```
+     */
+    static parse<Key extends BaseKey>(error: ErrorHandlerError): ErrorHandlerParseResult<Key>;
+}
+
+/**
+ * Лёгкий EventEmitter с поддержкой подписок, отписок и `defaultAction`.
+ * Слушатель получает объект события, объединённый с переданными параметрами emit.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new EventEmitter<'save', { id: number }>()
+ *
+ * emitter.on('save', (event) => {
+ *   console.log(event.id)
+ * })
+ *
+ * emitter.emit('save', { id: 1 })
+ * ```
+ */
+declare class EventEmitter<EventName extends string = string, EventParams extends Nullable<object> = undefined> {
+    private subscriptions;
+    constructor();
+    /**
+     * Вызывает событие и передаёт параметры всем подписчикам.
+     * Если ни один слушатель не отменил стандартное действие, дополнительно вызывается `defaultAction`.
+     *
+     * @param name - Имя события
+     * @param params - Дополнительные параметры события
+     * @param defaultAction - Функция, которая выполнится после слушателей, если действие не отменено
+     *
+     * @example
+     * ```typescript
+     * emitter.emit('save', { id: 1 }, () => {
+     *   console.log('saved')
+     * })
+     * ```
+     */
+    emit(name: EventName, params?: EventParams, defaultAction?: EventEmitterDefaultAction): void;
+    /**
+     * Подписывает слушатель на событие.
+     *
+     * @param name - Имя события
+     * @param listener - Обработчик события
+     * @returns Функция для отписки от события
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = emitter.on('save', (event) => {
+     *   console.log(event.id)
+     * })
+     *
+     * unsubscribe()
+     * ```
+     */
+    on(name: EventName, listener: EventEmitterListener<EventParams>): () => void;
+    /**
+     * Удаляет конкретный слушатель из подписки на событие.
+     *
+     * @param name - Имя события
+     * @param listener - Слушатель, которого нужно удалить
+     *
+     * @example
+     * ```typescript
+     * emitter.off('save', listener)
+     * ```
+     */
+    off(name: EventName, listener: EventEmitterListener<EventParams>): void;
+    /**
+     * Полностью очищает подписку на указанное событие.
+     *
+     * @param name - Имя события
+     *
+     * @example
+     * ```typescript
+     * emitter.clear('save')
+     * ```
+     */
+    clear(name: EventName): void;
+}
+
+type LogSignal = string;
+type LogParamList = any[];
+type LogStyles = string;
+
+/**
+ * Статический helper для форматированного вывода сообщений в консоль.
+ * Поддерживает обычные сообщения, стилизованные группы и набор `formatted`-методов с signal.
+ *
+ * @example
+ * ```typescript
+ * Log.info('App started')
+ * Log.formatted.success('auth', 'Signed in')
+ * ```
+ */
+declare class Log {
+    #private;
+    /**
+     * Набор методов для логирования с предварительным форматированием по signal.
+     *
+     * @example
+     * ```typescript
+     * Log.formatted.warning('api', 'Slow response')
+     * ```
+     */
+    static readonly formatted: {
+        info: (paramList_0: string, ...paramList: any[]) => void;
+        success: (paramList_0: string, ...paramList: any[]) => void;
+        warning: (paramList_0: string, ...paramList: any[]) => void;
+        danger: (paramList_0: string, ...paramList: any[]) => void;
+    };
+    /**
+     * Открывает группу логов в консоли и выводит её заголовок.
+     *
+     * @param signal - Короткий идентификатор группы
+     * @param styles - Дополнительные CSS-стили для заголовка
+     * @param paramList - Дополнительные данные, которые будут выведены вместе с signal
+     *
+     * @example
+     * ```typescript
+     * Log.startGroup('profile', 'color: purple;', { id: 1 })
+     * ```
+     */
+    static startGroup(signal: LogSignal, styles?: LogStyles, ...paramList: LogParamList): void;
+    /**
+     * Закрывает текущую группу логов в консоли.
+     *
+     * @example
+     * ```typescript
+     * Log.endGroup()
+     * ```
+     */
+    static endGroup(): void;
+    /**
+     * Выводит информационное сообщение.
+     *
+     * @param paramList - Параметры для вывода в консоль
+     *
+     * @example
+     * ```typescript
+     * Log.info('Profile loaded', user)
+     * ```
+     */
+    static info(...paramList: LogParamList): void;
+    /**
+     * Выводит сообщение об успешном результате.
+     *
+     * @param paramList - Параметры для вывода в консоль
+     *
+     * @example
+     * ```typescript
+     * Log.success('Profile saved')
+     * ```
+     */
+    static success(...paramList: LogParamList): void;
+    /**
+     * Выводит предупреждение.
+     *
+     * @param paramList - Параметры для вывода в консоль
+     *
+     * @example
+     * ```typescript
+     * Log.warning('Retry in progress')
+     * ```
+     */
+    static warning(...paramList: LogParamList): void;
+    /**
+     * Выводит сообщение об ошибке.
+     *
+     * @param paramList - Параметры для вывода в консоль
+     *
+     * @example
+     * ```typescript
+     * Log.danger('Request failed', error)
+     * ```
+     */
+    static danger(...paramList: LogParamList): void;
+}
+
+type StorageItemConfig<Value = string> = Partial<StorageConfig> & {
+    defaultValue?: Value;
+};
+
+declare class StorageItem<Value = unknown> {
+    private key;
+    private model;
+    private config?;
+    constructor(key: string, model: StorageModel, config?: StorageConfig);
+    get(): Promise<Nullable<Value>>;
+    get(config: StorageItemConfig<Value>): Promise<Value>;
+    set(value: Value, config?: StorageItemConfig<Value>): Promise<void>;
+    delete(config?: StorageItemConfig<Value>): Promise<void>;
+    has(config?: StorageItemConfig<Value>): Promise<boolean>;
+}
+
+/**
+ * Тип экземпляра Storage после вызова .create(key): объект с полем key типа StorageItem<Value>.
+ * Позволяет типизировать storage.user, storage.settings и т.д.
+ *
+ * @example
+ * ```typescript
+ * type UserStorage = StorageInstance<'user', { name: string }>
+ * ```
+ */
+type StorageInstance<Key extends string = string, Value = unknown> = {
+    [key in Key]: StorageItem<Value>;
+};
+/**
+ * Абстрактная модель хранилища ключ–значение.
+ * Реализация может быть localStorage, sessionStorage, серверный API и т.д.
+ * Значения передаются как строки; сериализация/десериализация (например JSON) — в StorageItem.
+ *
+ * @example
+ * ```typescript
+ * const model: StorageModel = {
+ *   get: (key) => localStorage.getItem(key),
+ *   set: (key, value) => localStorage.setItem(key, value),
+ *   delete: (key) => localStorage.removeItem(key)
+ * }
+ * ```
+ */
+type StorageModel = {
+    get: Callback<[string], MaybeAsync<Nullable<string>>>;
+    set: Callback<[string, string], MaybeAsync<void>>;
+    delete: Callback<[string], MaybeAsync<void>>;
+};
+/**
+ * Конфиг Storage/StorageItem: опция отладочного логирования через Log.
+ *
+ * @example
+ * ```typescript
+ * const config: StorageConfig = { withDebug: true }
+ * ```
+ */
+type StorageConfig = {
+    withDebug?: boolean;
+};
+
+/**
+ * Абстракция над ключ–значение хранилищем. Принимает модель (get/set/delete) и через .create(key)
+ * добавляет на экземпляр поле с StorageItem для данного ключа. Данные сериализуются в JSON в StorageItem.
+ *
+ * @example
+ * const model = { get: k => Promise.resolve(localStorage.getItem(k)), set: (k,v) => ..., delete: k => ... }
+ * const storage = new Storage(model).create('user')
+ * await storage.user.set({ name: 'John' })
+ * const user = await storage.user.get()
+ */
+declare class Storage {
+    private readonly model;
+    private readonly config?;
+    /**
+     * @param model - Реализация хранилища (например обёртка над localStorage или API)
+     * @param config - Опции (withDebug для отладочного логирования)
+     *
+     * @example
+     * ```typescript
+     * const storage = new Storage(model, { withDebug: true })
+     * ```
+     */
+    constructor(model: StorageModel, config?: StorageConfig);
+    /**
+     * Должен вернуть все элементы хранилища.
+     * В базовой реализации не поддержан и выбрасывает `Not implemented`.
+     *
+     * @returns Никогда не завершается успешно в базовом классе
+     *
+     * @example
+     * ```typescript
+     * await storage.all() // Error: Not implemented
+     * ```
+     */
+    all(): Promise<never>;
+    /**
+     * Должен очистить всё хранилище.
+     * В базовой реализации не поддержан и выбрасывает `Not implemented`.
+     *
+     * @returns Никогда не завершается успешно в базовом классе
+     *
+     * @example
+     * ```typescript
+     * await storage.clear() // Error: Not implemented
+     * ```
+     */
+    clear(): Promise<never>;
+    /**
+     * Создаёт и привязывает к экземпляру Storage элемент хранилища с заданным ключом.
+     * Возвращает this с новым полем key типа StorageItem<Value> (типизация через StorageInstance).
+     *
+     * @param key - Имя ключа (и имени поля на экземпляре, например 'user' → storage.user)
+     * @returns this с добавленным полем key
+     *
+     * @example
+     * ```typescript
+     * const storage = new Storage(model).create<'user', { name: string }>('user')
+     * await storage.user.set({ name: 'John' })
+     * ```
+     */
+    create<Key extends string = string, Value = unknown>(key: Key): this & StorageInstance<Key, Value>;
+}
+
+/**
+ * Асинхронная задержка на указанное количество миллисекунд.
+ * Удобна для пауз между ретраями, анимациями или батч-обработкой.
+ *
+ * @param delay - Длительность ожидания в миллисекундах
+ * @returns Promise, который выполнится через указанное время
+ *
+ * @example
+ * ```typescript
+ * await wait(300)
+ * ```
+ */
+declare const wait: (delay: number) => Promise<unknown>;
+/**
+ * Собирает объект из переданного значения и опционального исходного объекта.
+ * Поддерживает три сценария: вернуть объект как есть, слить два объекта или записать примитив по ключу.
+ *
+ * @param value - Объект целиком или значение для поля
+ * @param data - Исходный объект для объединения
+ * @param key - Ключ, в который нужно записать примитивное значение
+ * @returns Новый объект с объединёнными данными
+ *
+ * @example
+ * ```typescript
+ * compose({ name: 'John' }) // { name: 'John' }
+ * compose({ age: 18 }, { name: 'John' }) // { name: 'John', age: 18 }
+ * compose('John', { age: 18 }, 'name') // { age: 18, name: 'John' }
+ * ```
+ */
+declare function compose<Data extends object, Value extends Data>(value: Value): Value;
+declare function compose<Data extends object, Value extends Data>(value: Value, data: Data): Data & Value;
+declare function compose<Data extends object, Key extends KeyOf<Data>, Value extends Data[Key] | Data>(value: Value, data: Nullable<Partial<Data>>, key: Nullable<Key>): Data;
+/**
+ * Возвращает значение объекта по ключу.
+ * Если ключ отсутствует или равен null/undefined, может вернуть значение по умолчанию.
+ *
+ * @param key - Ключ поля
+ * @param data - Объект-источник
+ * @param defaultValue - Резервное значение, если ключ не задан или значение отсутствует
+ * @returns Значение по ключу или defaultValue
+ *
+ * @example
+ * ```typescript
+ * getValueByKey('name', { name: 'John' }) // 'John'
+ * getValueByKey('age', { name: 'John' }, 18) // 18
+ * ```
+ */
+declare function getValueByKey<Value, Key extends BaseKey>(key: Key, data: BaseRecord<Value, Key>): Value;
+declare function getValueByKey<Value, Key extends BaseKey, DefaultValue>(key: Nullable<Key>, data: Partial<BaseRecord<Value, Key>>, defaultValue: DefaultValue): Value | DefaultValue;
+/**
+ * Преобразует значения объекта, сохраняя его исходные ключи.
+ *
+ * @param data - Объект, который нужно обойти
+ * @param callback - Функция преобразования значения
+ * @returns Новый объект с теми же ключами и результатами callback
+ *
+ * @example
+ * ```typescript
+ * mapRecord({ a: 1, b: 2 }, (_, value) => value * 2) // { a: 2, b: 4 }
+ * ```
+ */
+declare const mapRecord: <ResultValue, Data extends object, Key extends KeyOf<Data>, Value extends ValueOf<Data>, Result = BaseRecord<ResultValue, Key>>(data: Data, callback: (key: Key, value: Value, index: number, list: [Key, Value][]) => ResultValue) => Result;
+/**
+ * Безопасно вызывает callback, если передано действительно вызываемое значение.
+ *
+ * @param callback - Функция для вызова
+ * @param paramList - Аргументы, которые будут переданы в callback
+ * @returns Результат callback или undefined, если callback не является функцией
+ *
+ * @example
+ * ```typescript
+ * runCallback((name: string) => `Hello, ${name}`, 'John') // 'Hello, John'
+ * runCallback(undefined, 'John') // undefined
+ * ```
+ */
+declare const runCallback: <Callback, Result = Callback extends AnyCallback ? ReturnType<Callback> : void>(callback: Callback, ...paramList: CallbackParamList<Callback>) => Result;
+
+/**
+ * Создаёт функцию с отложенным вызовом callback.
+ * Повторный вызов до истечения delay сбрасывает предыдущий таймер.
+ *
+ * @param callback - Функция, которую нужно вызывать с задержкой
+ * @param delay - Задержка в миллисекундах
+ * @returns Обёртка с debounce-поведением
+ *
+ * @example
+ * ```typescript
+ * const save = debounce(() => api.save(), 300)
+ * input.addEventListener('input', save)
+ * ```
+ */
+declare const debounce: <Callback>(callback: Callback, delay: number) => (...params: CallbackParamList<Callback>) => void;
+/**
+ * Создаёт функцию, которая допускает не более одного вызова за период delay.
+ *
+ * @param callback - Функция, которую нужно ограничить по частоте вызовов
+ * @param delay - Интервал блокировки в миллисекундах
+ * @returns Обёртка с throttle-поведением
+ *
+ * @example
+ * ```typescript
+ * const onScroll = throttle(() => console.log('scroll'), 100)
+ * window.addEventListener('scroll', onScroll)
+ * ```
+ */
+declare const throttle: <Callback>(callback: Callback, delay: number) => (...params: CallbackParamList<Callback>) => void;
+
+/**
+ * Фильтрует список объектов по булевому полю.
+ * Если у элемента нет указанного ключа, такой элемент сохраняется.
+ *
+ * @param list - Исходный список объектов
+ * @param key - Булево поле для фильтрации, по умолчанию `isVisible`
+ * @returns Новый список, содержащий только подходящие элементы
+ *
+ * @example
+ * ```typescript
+ * filterByKey([{ isVisible: true }, { isVisible: false }]) // [{ isVisible: true }]
+ * ```
+ */
+declare function filterByKey<Key extends KeyOf<Item>, Item extends object & BaseRecord<boolean, Key>>(list: Item[], key?: Key): Item[];
+/**
+ * Удаляет дубликаты из списка объектов по значению указанного ключа.
+ *
+ * @param data - Список объектов
+ * @param key - Ключ, по которому определяется уникальность
+ * @returns Новый список без повторяющихся значений key
+ *
+ * @example
+ * ```typescript
+ * filterDuplicateByKey([{ id: 1 }, { id: 1 }, { id: 2 }], 'id') // [{ id: 1 }, { id: 2 }]
+ * ```
+ */
+declare function filterDuplicateByKey<Key extends BaseKey, Item extends object & BaseRecord<any, Key>>(data: Item[], key: Key): Item[];
+/**
+ * Возвращает элементы первого списка, которые присутствуют во втором.
+ *
+ * @param inputList - Список для проверки
+ * @param list - Список значений, с которыми нужно сравнить
+ * @returns Пересечение двух списков
+ *
+ * @example
+ * ```typescript
+ * filterEqualValues([1, 2, 3], [2, 4]) // [2]
+ * ```
+ */
+declare function filterEqualValues<Item>(inputList: Item[], list: Item[]): Item[];
+/**
+ * Удаляет из списка `null` и `undefined`, одновременно сужая тип результата.
+ *
+ * @param list - Исходный список
+ * @returns Список только с непустыми значениями
+ *
+ * @example
+ * ```typescript
+ * filterNullableValues([1, null, 2, undefined]) // [1, 2]
+ * ```
+ */
+declare function filterNullableValues<Item>(list: Item[]): NotNullable<Item>[];
+
+/**
+ * Проверяет, что объект не содержит перечисляемых свойств.
+ *
+ * @param object - Объект для проверки
+ * @returns `true`, если объект пустой
+ *
+ * @example
+ * ```typescript
+ * isObjectEmpty({}) // true
+ * isObjectEmpty({ id: 1 }) // false
+ * ```
+ */
+declare function isObjectEmpty<Param extends object>(object: Param): boolean;
+/**
+ * Проверяет, что массив не содержит элементов.
+ *
+ * @param array - Массив для проверки
+ * @returns `true`, если массив пустой
+ *
+ * @example
+ * ```typescript
+ * isArrayEmpty([]) // true
+ * isArrayEmpty([1]) // false
+ * ```
+ */
+declare function isArrayEmpty<Param extends BaseList>(array: Param): boolean;
+/**
+ * Проверяет наличие ключа в объекте и сужает тип data при успешной проверке.
+ *
+ * @param key - Ключ, наличие которого нужно проверить
+ * @param data - Значение, которое предполагается объектом
+ * @returns `true`, если ключ существует в объекте
+ *
+ * @example
+ * ```typescript
+ * if (hasKey('name', payload)) {
+ *   console.log(payload.name)
+ * }
+ * ```
+ */
+declare function hasKey<Key extends BaseKey, Data, Value>(key: Key, data: Data): data is Data & BaseRecord<Value, Key>;
+/**
+ * Проверяет, есть ли у двух списков хотя бы одно общее значение.
+ *
+ * @param inputList - Первый список
+ * @param list - Второй список
+ * @returns `true`, если найдено хотя бы одно совпадение
+ *
+ * @example
+ * ```typescript
+ * hasEqualValues(['a', 'b'], ['c', 'b']) // true
+ * hasEqualValues(['a'], ['c']) // false
+ * ```
+ */
+declare function hasEqualValues<Item>(inputList: Item[], list: Item[]): boolean;
+
+/**
+ * Приводит значение к массиву: если передано одно значение — возвращает массив из одного элемента,
+ * если передан массив — возвращает его без изменений.
+ * Удобно для API, которые могут принимать как один элемент, так и массив.
+ *
+ * @param param - Один элемент или массив элементов
+ * @returns Массив элементов (всегда массив)
+ *
+ * @example
+ * ```typescript
+ * forceList(1)        // [1]
+ * forceList([1, 2])   // [1, 2]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const ids = forceList(query.id)  // query.id: string | string[]
+ * ids.forEach(processId)
+ * ```
+ */
+declare function forceList<Item>(param: Item | Item[]): Item[];
+/**
+ * Разбивает массив на подмассивы заданного размера (чанки).
+ * Последний чанк может быть меньше size, если длина массива не кратна size.
+ *
+ * @param list - Исходный массив
+ * @param size - Размер одного чанка (целое положительное число)
+ * @returns Массив чанков (массив массивов)
+ *
+ * @example
+ * ```typescript
+ * chunkList([1, 2, 3, 4, 5], 2)  // [[1, 2], [3, 4], [5]]
+ * chunkList([], 3)                // []
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const pages = chunkList(items, PAGE_SIZE)
+ * for (const page of pages) {
+ *   await saveBatch(page)
+ * }
+ * ```
+ */
+declare function chunkList<Item>(list: Item[], size: number): Item[][];
+
+/**
+ * Проверяет, что значение равно `undefined`.
+ *
+ * @example
+ * ```typescript
+ * isUndefined(undefined) // true
+ * isUndefined(null) // false
+ * ```
+ */
+declare const isUndefined: (param: unknown) => param is undefined;
+/**
+ * Проверяет, что значение равно `null`.
+ *
+ * @example
+ * ```typescript
+ * isNull(null) // true
+ * isNull(undefined) // false
+ * ```
+ */
+declare const isNull: (param: unknown) => param is null;
+/**
+ * Проверяет, что значение равно `null` или `undefined`.
+ *
+ * @example
+ * ```typescript
+ * isNullable(undefined) // true
+ * isNullable('value') // false
+ * ```
+ */
+declare const isNullable: (param: unknown) => param is Nullable;
+/**
+ * Проверяет, что значение имеет тип `string`.
+ *
+ * @example
+ * ```typescript
+ * isString('hello') // true
+ * isString(42) // false
+ * ```
+ */
+declare const isString: (param: unknown) => param is string;
+/**
+ * Проверяет, что значение имеет тип `number`.
+ *
+ * @example
+ * ```typescript
+ * isNumber(42) // true
+ * isNumber('42') // false
+ * ```
+ */
+declare const isNumber: (param: unknown) => param is number;
+/**
+ * Проверяет, что значение имеет тип `bigint`.
+ *
+ * @example
+ * ```typescript
+ * isBigint(10n) // true
+ * isBigint(10) // false
+ * ```
+ */
+declare const isBigint: (param: unknown) => param is bigint;
+/**
+ * Проверяет, что значение является `NaN`.
+ *
+ * @example
+ * ```typescript
+ * isNaN(Number('foo')) // true
+ * isNaN(10) // false
+ * ```
+ */
+declare const isNaN: (param: unknown) => param is number;
+/**
+ * Проверяет, что значение имеет тип `boolean`.
+ *
+ * @example
+ * ```typescript
+ * isBoolean(true) // true
+ * isBoolean(0) // false
+ * ```
+ */
+declare const isBoolean: (param: unknown) => param is boolean;
+/**
+ * Проверяет, что значение имеет тип `symbol`.
+ *
+ * @example
+ * ```typescript
+ * isSymbol(Symbol('id')) // true
+ * isSymbol('id') // false
+ * ```
+ */
+declare const isSymbol: (param: unknown) => param is symbol;
+/**
+ * Проверяет, что значение относится к объектным типам JavaScript.
+ *
+ * @example
+ * ```typescript
+ * isAnyObject({}) // true
+ * isAnyObject(null) // true
+ * ```
+ */
+declare const isAnyObject: (param: unknown) => param is object;
+/**
+ * Проверяет, что значение является "простым" объектом, а не массивом, датой, ошибкой или другой специальной структурой.
+ *
+ * @param param - Значение для проверки
+ * @returns `true`, если значение можно трактовать как обычный объект
+ *
+ * @example
+ * ```typescript
+ * isObject({ id: 1 }) // true
+ * isObject([1, 2, 3]) // false
+ * ```
+ */
+declare const isObject: <Param = object>(param: unknown) => param is Param;
+/**
+ * Проверяет, что значение является массивом.
+ *
+ * @example
+ * ```typescript
+ * isArray([1, 2]) // true
+ * isArray({ length: 2 }) // false
+ * ```
+ */
+declare const isArray: <Param = unknown>(param: unknown) => param is Param[];
+/**
+ * Проверяет, что значение является `ArrayBuffer`.
+ *
+ * @example
+ * ```typescript
+ * isArrayBuffer(new ArrayBuffer(8)) // true
+ * ```
+ */
+declare const isArrayBuffer: (param: unknown) => param is ArrayBuffer;
+/**
+ * Проверяет, что значение является `Map`.
+ *
+ * @example
+ * ```typescript
+ * isMap(new Map()) // true
+ * ```
+ */
+declare const isMap: (param: unknown) => param is Map<unknown, unknown>;
+/**
+ * Проверяет, что значение является `Set`.
+ *
+ * @example
+ * ```typescript
+ * isSet(new Set()) // true
+ * ```
+ */
+declare const isSet: (param: unknown) => param is Set<unknown>;
+/**
+ * Проверяет, что значение является `WeakMap`.
+ *
+ * @example
+ * ```typescript
+ * isWeakMap(new WeakMap()) // true
+ * ```
+ */
+declare const isWeakMap: (param: unknown) => param is WeakMap<object, unknown>;
+/**
+ * Проверяет, что значение является `WeakSet`.
+ *
+ * @example
+ * ```typescript
+ * isWeakSet(new WeakSet()) // true
+ * ```
+ */
+declare const isWeakSet: (param: unknown) => param is WeakSet<object>;
+/**
+ * Проверяет, что значение является объектом `Date`.
+ *
+ * @example
+ * ```typescript
+ * isDate(new Date()) // true
+ * ```
+ */
+declare const isDate: (param: unknown) => param is Error;
+/**
+ * Проверяет, что значение является экземпляром `Error`.
+ *
+ * @example
+ * ```typescript
+ * isError(new Error('boom')) // true
+ * ```
+ */
+declare const isError: (param: unknown) => param is Error;
+/**
+ * Проверяет, что значение является `Proxy`.
+ *
+ * @example
+ * ```typescript
+ * const value = new Proxy({}, {})
+ * isProxy(value) // true
+ * ```
+ */
+declare const isProxy: (param: unknown) => param is ProxyConstructor;
+/**
+ * Проверяет, что значение является `RegExp`.
+ *
+ * @example
+ * ```typescript
+ * isRegExp(/test/) // true
+ * ```
+ */
+declare const isRegExp: (param: unknown) => param is RegExp;
+/**
+ * Проверяет, что значение является `Promise`.
+ *
+ * @example
+ * ```typescript
+ * isPromise(Promise.resolve()) // true
+ * ```
+ */
+declare const isPromise: (param: unknown) => param is Promise<typeof param>;
+/**
+ * Проверяет, что значение является функцией.
+ *
+ * @param param - Значение для проверки
+ * @returns `true`, если значение можно вызвать как функцию
+ *
+ * @example
+ * ```typescript
+ * isFunction(() => true) // true
+ * isFunction('callback') // false
+ * ```
+ */
+declare const isFunction: <Callback = <ParamList extends BaseList, Result>(...paramList: ParamList) => Result>(param: unknown) => param is Callback;
+
+export { ErrorHandler, ErrorHandlerEventName, EventEmitter, Log, Storage, chunkList, compose, debounce, filterByKey, filterDuplicateByKey, filterEqualValues, filterNullableValues, forceList, getValueByKey, hasEqualValues, hasKey, isAnyObject, isArray, isArrayBuffer, isArrayEmpty, isBigint, isBoolean, isDate, isError, isFunction, isMap, isNaN, isNull, isNullable, isNumber, isObject, isObjectEmpty, isPromise, isProxy, isRegExp, isSet, isString, isSymbol, isUndefined, isWeakMap, isWeakSet, mapRecord, runCallback, throttle, wait };
+export type { AnyAsyncCallback, AnyCallback, AsyncCallback, BaseKey, BaseList, BaseRecord, Callback, CallbackParamList, CallbackResult, Decrement, Divide, Entry, ErrorHandlerCaseConfig, ErrorHandlerConfig, ErrorHandlerError, ErrorHandlerErrors, ErrorHandlerEventParams, ErrorHandlerMessage, ErrorHandlerParseResult, Filled, Include, Increment, IterableOf, KeyOf, LevelRange, List, MaybeAsync, Noop, NotNullable, Nothing, Nullable, Numerable, Shared, SizeRange, StorageConfig, StorageInstance, StorageModel, ValueOf };