synapse-storage 3.0.19 → 4.0.0

package/dist/storage.interface-BA_ktyDz.d.ts

@@ -1,591 +0,0 @@
-declare class StorageKey {
-    private readonly value;
-    private readonly isRawKey;
-    constructor(value: string, isRawKey?: boolean);
-    toString(): string;
-    toJSON(): string;
-    valueOf(): string;
-    isUnparseable(): boolean;
-}
-type StorageKeyType = string | StorageKey;
-
-/**
- * Контекст выполнения для плагинов
- * Содержит информацию о текущей операции и хранилище
- */
-interface PluginContext {
-    /** Имя хранилища, к которому применяется плагин */
-    storageName: string;
-    /** Временная метка выполнения операции (timestamp) */
-    timestamp: number;
-    /** Дополнительные метаданные операции (могут быть предоставлены хранилищем или другими плагинами) */
-    metadata?: Record<string, any>;
-}
-/**
- * Базовый интерфейс для всех плагинов
- * Определяет основные свойства и методы жизненного цикла
- */
-interface IPlugin {
-    /** Уникальное имя плагина */
-    name: string;
-    /**
-     * Метод инициализации плагина
-     * Вызывается при добавлении плагина в хранилище или при инициализации хранилища
-     */
-    initialize?(): Promise<void>;
-    /**
-     * Метод уничтожения плагина
-     * Вызывается при удалении плагина из хранилища или при уничтожении хранилища
-     * Используется для освобождения ресурсов и очистки состояния
-     */
-    destroy?(): Promise<void>;
-}
-/**
- * Интерфейс плагина для хранилища данных
- * Определяет хуки для различных операций хранилища
- */
-interface IStoragePlugin extends IPlugin {
-    /**
-     * Вызывается перед установкой значения в хранилище
-     * Позволяет изменить значение до его сохранения
-     *
-     * @param value Значение, которое будет сохранено
-     * @param context Контекст выполнения операции
-     * @returns Модифицированное значение для сохранения
-     */
-    onBeforeSet?<T>(value: T, context: PluginContext): Promise<T>;
-    /**
-     * Вызывается после установки значения в хранилище
-     * Позволяет выполнить дополнительные действия или модифицировать результат
-     *
-     * @param key Ключ, по которому было сохранено значение
-     * @param value Сохраненное значение
-     * @param context Контекст выполнения операции
-     * @returns Финальное значение (может быть модифицировано)
-     */
-    onAfterSet?<T>(key: StorageKeyType, value: T, context: PluginContext): Promise<T>;
-    /**
-     * Вызывается перед получением значения из хранилища
-     * Позволяет модифицировать запрашиваемый ключ
-     *
-     * @param key Ключ, по которому запрашивается значение
-     * @param context Контекст выполнения операции
-     * @returns Возможно модифицированный ключ для запроса
-     */
-    onBeforeGet?(key: StorageKeyType, context: PluginContext): Promise<StorageKeyType>;
-    /**
-     * Вызывается после получения значения из хранилища
-     * Позволяет модифицировать полученное значение
-     *
-     * @param key Ключ, по которому было запрошено значение
-     * @param value Полученное значение (undefined, если значение не найдено)
-     * @param context Контекст выполнения операции
-     * @returns Финальное значение (может быть модифицировано)
-     */
-    onAfterGet?<T>(key: StorageKeyType, value: T | undefined, context: PluginContext): Promise<T | undefined>;
-    /**
-     * Вызывается перед удалением значения из хранилища
-     * Позволяет разрешить или запретить удаление
-     *
-     * @param key Ключ, по которому будет удалено значение
-     * @param context Контекст выполнения операции
-     * @returns Булево значение, разрешающее (true) или запрещающее (false) удаление
-     */
-    onBeforeDelete?(key: StorageKeyType, context: PluginContext): Promise<boolean>;
-    /**
-     * Вызывается после удаления значения из хранилища
-     * Позволяет выполнить дополнительные действия после удаления
-     *
-     * @param key Ключ, по которому было удалено значение
-     * @param context Контекст выполнения операции
-     */
-    onAfterDelete?(key: StorageKeyType, context: PluginContext): Promise<void>;
-    /**
-     * Вызывается перед очисткой хранилища
-     * Позволяет выполнить дополнительные действия перед удалением всех данных
-     *
-     * @param context Контекст выполнения операции
-     */
-    onClear?(context: PluginContext): Promise<void>;
-}
-/**
- * Исполнитель плагинов
- * Отвечает за выполнение хуков плагинов в определенной последовательности
- */
-interface IPluginExecutor {
-    /**
-     * Выполняет хуки onBeforeSet всех зарегистрированных плагинов
-     *
-     * @param value Исходное значение
-     * @param metadata Дополнительные метаданные
-     * @returns Модифицированное значение после прохождения всех плагинов
-     */
-    executeBeforeSet<T>(value: T, metadata?: Record<string, any>): Promise<T>;
-    /**
-     * Выполняет хуки onAfterSet всех зарегистрированных плагинов
-     *
-     * @param key Ключ, по которому было сохранено значение
-     * @param value Сохраненное значение
-     * @param metadata Дополнительные метаданные
-     * @returns Финальное значение после прохождения всех плагинов
-     */
-    executeAfterSet<T>(key: StorageKeyType, value: T, metadata?: Record<string, any>): Promise<T>;
-    /**
-     * Выполняет хуки onBeforeGet всех зарегистрированных плагинов
-     *
-     * @param key Исходный ключ
-     * @param metadata Дополнительные метаданные
-     * @returns Модифицированный ключ после прохождения всех плагинов
-     */
-    executeBeforeGet(key: StorageKeyType, metadata?: Record<string, any>): Promise<StorageKeyType>;
-    /**
-     * Выполняет хуки onAfterGet всех зарегистрированных плагинов
-     *
-     * @param key Ключ, по которому было запрошено значение
-     * @param value Полученное значение
-     * @param metadata Дополнительные метаданные
-     * @returns Финальное значение после прохождения всех плагинов
-     */
-    executeAfterGet<T>(key: StorageKeyType, value: T | undefined, metadata?: Record<string, any>): Promise<T | undefined>;
-    /**
-     * Выполняет хуки onBeforeDelete всех зарегистрированных плагинов
-     *
-     * @param key Ключ, по которому будет удалено значение
-     * @param metadata Дополнительные метаданные
-     * @returns Результат проверки всех плагинов (false если хотя бы один плагин запретил удаление)
-     */
-    executeBeforeDelete(key: StorageKeyType, metadata?: Record<string, any>): Promise<boolean>;
-    /**
-     * Выполняет хуки onAfterDelete всех зарегистрированных плагинов
-     *
-     * @param key Ключ, по которому было удалено значение
-     * @param metadata Дополнительные метаданные
-     */
-    executeAfterDelete(key: StorageKeyType, metadata?: Record<string, any>): Promise<void>;
-    /**
-     * Выполняет хуки onClear всех зарегистрированных плагинов
-     *
-     * @param metadata Дополнительные метаданные
-     */
-    executeOnClear(metadata?: Record<string, any>): Promise<void>;
-}
-/**
- * Менеджер плагинов
- * Отвечает за регистрацию, получение и удаление плагинов
- */
-interface IPluginManager<T extends IPlugin> {
-    /**
-     * Добавляет плагин в менеджер
-     *
-     * @param plugin Экземпляр плагина
-     */
-    add(plugin: T): Promise<void>;
-    /**
-     * Удаляет плагин из менеджера по имени
-     *
-     * @param name Имя плагина
-     */
-    remove(name: string): Promise<void>;
-    /**
-     * Получает плагин по имени
-     *
-     * @param name Имя плагина
-     * @returns Экземпляр плагина или undefined, если плагин не найден
-     */
-    get(name: string): T | undefined;
-    /**
-     * Получает все зарегистрированные плагины
-     *
-     * @returns Массив всех плагинов
-     */
-    getAll(): T[];
-    /**
-     * Инициализирует все зарегистрированные плагины
-     */
-    initialize(): Promise<void>;
-    /**
-     * Уничтожает все зарегистрированные плагины
-     */
-    destroy(): Promise<void>;
-}
-
-type PathSelector<T, R> = (state: T) => R;
-declare abstract class BaseStorage<T extends Record<string, any>> implements IStorage<T> {
-    protected readonly config: StorageSingletonConfig<T>;
-    protected readonly pluginExecutor?: IPluginExecutor | undefined;
-    protected readonly eventEmitter?: IEventEmitter | undefined;
-    protected readonly logger?: ILogger | undefined;
-    protected static readonly GLOBAL_SUBSCRIPTION_KEY = "*";
-    protected static readonly STORAGE_TYPE: StorageType;
-    name: string;
-    private _initStatus;
-    private statusSubscribers;
-    private selectorPathCache;
-    private middlewareModule;
-    private initializedMiddlewares;
-    protected subscribers: Map<StorageKeyType, Set<(value: any) => void>>;
-    constructor(config: StorageSingletonConfig<T>, pluginExecutor?: IPluginExecutor | undefined, eventEmitter?: IEventEmitter | undefined, logger?: ILogger | undefined);
-    get initStatus(): StorageInitStatus;
-    waitForReady(): Promise<this>;
-    onStatusChange(callback: (status: StorageInitStatus) => void): VoidFunction;
-    private updateInitStatus;
-    initialize(): Promise<this>;
-    protected abstract doInitialize(): Promise<this>;
-    private ensureReady;
-    protected initializeMiddlewares(): void;
-    protected getDefaultMiddleware(): DefaultMiddlewares;
-    protected initializeWithMiddlewares(): Promise<void>;
-    protected abstract doGet(key: StorageKeyType): Promise<any>;
-    protected abstract doSet(key: StorageKeyType, value: any): Promise<void>;
-    protected abstract doUpdate(updates: Array<{
-        key: StorageKeyType;
-        value: any;
-    }>): Promise<void>;
-    protected abstract doDelete(key: StorageKeyType): Promise<boolean>;
-    protected abstract doClear(): Promise<void>;
-    protected abstract doKeys(): Promise<string[]>;
-    protected abstract doHas(key: StorageKeyType): Promise<boolean>;
-    protected abstract doDestroy(): Promise<void>;
-    get<R>(key: StorageKeyType): Promise<R | undefined>;
-    set<R>(key: StorageKeyType, value: R): Promise<void>;
-    update(updater: (state: T) => void): Promise<void>;
-    delete(key: StorageKeyType): Promise<void>;
-    clear(): Promise<void>;
-    keys(): Promise<string[]>;
-    has(key: StorageKeyType): Promise<boolean>;
-    getState(): Promise<T>;
-    subscribeToAll(callback: (event: {
-        type: string;
-        key?: StorageKeyType[] | StorageKeyType;
-        value?: any;
-        changedPaths?: string[];
-    }) => void): VoidFunction;
-    subscribe(key: string, callback: (value: any) => void): VoidFunction;
-    subscribe<R>(pathSelector: PathSelector<T, R>, callback: (value: R) => void): VoidFunction;
-    destroy(): Promise<void>;
-    private subscribeByKey;
-    private createDummyState;
-    private isEqual;
-    /**
-     * Возвращает полный путь, а не только корневой ключ
-     */
-    private extractPath;
-    protected notifySubscribers(key: StorageKeyType, value: any): void;
-    /**
-     * Метод для определения изменившихся путей между двумя объектами
-     */
-    private findChangedPaths;
-    private subscribeBySelector;
-    protected emitEvent(event: StorageEvent): Promise<void>;
-}
-
-interface IndexedDBConfig {
-    dbName?: string;
-    dbVersion: number;
-}
-declare class IndexedDBStorage<T extends Record<string, any>> extends BaseStorage<T> {
-    protected static readonly STORAGE_TYPE: StorageType;
-    private readonly DB_NAME;
-    private readonly STORE_NAME;
-    private readonly DB_VERSION;
-    private dbManager;
-    constructor(config: IndexedDBStorageConfig<T>, pluginExecutor?: IPluginExecutor, eventEmitter?: IEventEmitter, logger?: ILogger);
-    protected getStorageType(): StorageType;
-    static create<T extends Record<string, any>>(config: IndexedDBStorageConfig, pluginExecutor?: IPluginExecutor, eventEmitter?: IEventEmitter, logger?: ILogger): IndexedDBStorage<T>;
-    protected doInitialize(): Promise<this>;
-    static getCurrentDBVersion(dbName: string): Promise<number>;
-    static createStorages<S extends Record<string, any>>(dbName: string, configs: {
-        [K in keyof S]: {
-            name: string;
-            initialState?: S[K];
-            middlewares?: ConfigureMiddlewares;
-            pluginExecutor?: IPluginExecutor;
-            eventEmitter?: IEventEmitter;
-        };
-    }, logger?: ILogger): Promise<{
-        [K in keyof S]: IndexedDBStorage<S[K]>;
-    }>;
-    private getTransaction;
-    private getObjectStore;
-    protected doGet(key: StorageKeyType): Promise<any>;
-    protected doSet(key: StorageKeyType, value: any): Promise<void>;
-    private putValueInStore;
-    protected doUpdate(updates: Array<{
-        key: string | StorageKey;
-        value: any;
-    }>): Promise<void>;
-    protected doDelete(key: StorageKeyType): Promise<boolean>;
-    protected doClear(): Promise<void>;
-    protected doKeys(): Promise<string[]>;
-    protected doHas(key: StorageKeyType): Promise<boolean>;
-    protected doDestroy(): Promise<void>;
-}
-
-type StorageActionType = 'get' | 'set' | 'delete' | 'clear' | 'init' | 'keys' | 'update';
-type StorageAction = {
-    type: StorageActionType;
-    key?: StorageKeyType;
-    value?: any;
-    metadata?: Record<string, any>;
-    source?: string;
-    timestamp?: number;
-};
-type MiddlewareAPI = {
-    dispatch: (action: StorageAction) => Promise<any>;
-    getState: () => Promise<Record<string, any>>;
-    storage: {
-        doGet: (key: StorageKeyType) => Promise<any>;
-        doSet: (key: StorageKeyType, value: any) => Promise<void>;
-        doUpdate: (updates: Array<{
-            key: StorageKeyType;
-            value: any;
-        }>) => Promise<void>;
-        doDelete: (key: StorageKeyType) => Promise<boolean>;
-        doClear: () => Promise<void>;
-        doKeys: () => Promise<string[]>;
-        notifySubscribers: (key: StorageKeyType, value: any) => void;
-    };
-};
-type NextFunction = (action: StorageAction) => Promise<any>;
-type SetupEventsFunction = (api: MiddlewareAPI) => void;
-type Middleware = {
-    name: string;
-    setup?: SetupEventsFunction;
-    cleanup?: () => Promise<void> | void;
-    reducer: (api: MiddlewareAPI) => (next: NextFunction) => (action: StorageAction) => Promise<any>;
-};
-
-interface BatchingMiddlewareOptions {
-    batchSize?: number;
-    batchDelay?: number;
-}
-
-interface ShallowCompareMiddlewareOptions {
-    segments?: string[];
-    comparator?: <T>(prev: T, next: T) => boolean;
-}
-
-/**
- * @example
- * ```typescript
- * // Строгая проверка - выбросит ошибку при любых различиях
- * const storage1 = new MemoryStorage({
- *   name: 'user',
- *   singleton: {
- *     enabled: true,
- *     mergeStrategy: ConfigMergeStrategy.STRICT
- *   },
- *   initialState: { name: 'John' }
- * })
- *
- * // Глубокое слияние - объединит объекты
- * const storage2 = new MemoryStorage({
- *   name: 'settings',
- *   singleton: {
- *     enabled: true,
- *     mergeStrategy: ConfigMergeStrategy.DEEP_MERGE
- *   },
- *   initialState: { theme: 'dark', notifications: { email: true } }
- * })
- * ```
- */
-declare enum ConfigMergeStrategy {
-    /**
-     * Строгая проверка - выбрасывает ошибку при любых отличиях в конфигурации
-     *
-     * Используйте когда требуется абсолютная идентичность конфигураций
-     * для обеспечения предсказуемого поведения
-     */
-    STRICT = "strict",
-    /**
-     * Первая конфигурация побеждает - игнорирует последующие конфигурации
-     *
-     * **По умолчанию**. Безопасная стратегия, которая использует настройки
-     * первого созданного экземпляра и игнорирует все последующие
-     */
-    FIRST_WINS = "first_wins",
-    /**
-     * Глубокое слияние объектов - рекурсивно объединяет initialState
-     *
-     * Полезно когда разные компоненты должны дополнять начальное состояние.
-     * Примитивные значения из первой конфигурации сохраняются
-     */
-    DEEP_MERGE = "deep_merge",
-    /**
-     * Последняя конфигурация перезаписывает предыдущие (кроме name)
-     *
-     * **Осторожно!** Может привести к непредсказуемому поведению,
-     * так как результат зависит от порядка создания компонентов
-     */
-    OVERRIDE = "override",
-    /**
-     * Предупреждение в консоли + использование первой конфигурации
-     *
-     * Как FIRST_WINS, но с подробными предупреждениями в консоли
-     * о конфликтующих настройках. Полезно для отладки
-     */
-    WARN_AND_USE_FIRST = "warn_and_use_first"
-}
-/**
- * Позволяет переиспользовать экземпляры хранилищ между компонентами
- * по имени, что особенно полезно в React при частых ре-рендерах
- *
- * @example
- * ```typescript
- * // Базовое использование
- * const storage = new MemoryStorage({
- *   name: 'user-preferences',
- *   singleton: { enabled: true },
- *   initialState: { theme: 'light' }
- * })
- *
- * // Продвинутые настройки
- * const storage = new MemoryStorage({
- *   name: 'shared-state',
- *   singleton: {
- *     enabled: true,
- *     mergeStrategy: ConfigMergeStrategy.DEEP_MERGE,
- *     warnOnConflict: true,
- *     key: 'custom-singleton-key'
- *   },
- *   initialState: { user: null, settings: {} }
- * })
- * ```
- *
- * @see {@link ConfigMergeStrategy} для стратегий разрешения конфликтов
- */
-interface SingletonOptions {
-    /**
-     * Включить Singleton Pattern для данного хранилища
-     *
-     * При `true` хранилища с одинаковым именем (или ключом) будут
-     * возвращать один и тот же экземпляр вместо создания нового
-     *
-     * @default false
-     */
-    enabled: boolean;
-    /**
-     * Стратегия разрешения конфликтов при различающихся конфигурациях
-     *
-     * Определяет как поступать, когда singleton с тем же именем
-     * создается с отличающимися параметрами (initialState, middlewares и т.д.)
-     *
-     * @default ConfigMergeStrategy.FIRST_WINS
-     * @see {@link ConfigMergeStrategy}
-     */
-    mergeStrategy?: ConfigMergeStrategy;
-    /**
-     * Выводить предупреждения при обнаружении конфликтов конфигурации
-     *
-     * При `true` будет логировать в консоль информацию о различиях
-     * в конфигурациях между экземплярами singleton (кроме стратегии STRICT)
-     *
-     * @default true
-     */
-    warnOnConflict?: boolean;
-    /**
-     * Кастомный ключ для идентификации singleton экземпляра
-     *
-     * По умолчанию используется комбинация `{StorageType}_{name}`,
-     * но можно задать собственный ключ для более тонкого контроля
-     *
-     * @example
-     * ```typescript
-     * // Разные хранилища с одним именем, но разными ключами
-     * const userCache = new MemoryStorage({
-     *   name: 'user',
-     *   singleton: { enabled: true, key: 'user-cache' }
-     * })
-     *
-     * const userSettings = new LocalStorage({
-     *   name: 'user', // То же имя!
-     *   singleton: { enabled: true, key: 'user-settings' } // Но разный ключ
-     * })
-     * ```
-     *
-     * @default `${StorageType}_${name}`
-     */
-    key?: string;
-}
-
-declare enum StorageStatus {
-    IDLE = "idle",// Не инициализировано
-    LOADING = "loading",// В процессе инициализации
-    READY = "ready",// Успешно инициализировано
-    ERROR = "error"
-}
-interface StorageInitStatus {
-    status: StorageStatus;
-    error?: Error;
-}
-interface IStorage<T extends Record<string, any> = any> {
-    name: string;
-    get<R>(key: StorageKeyType): Promise<R | undefined>;
-    getState(): Promise<T>;
-    set<R>(key: StorageKeyType, value: R): Promise<void>;
-    update(updater: (state: T) => void): Promise<void>;
-    has(key: StorageKeyType): Promise<boolean>;
-    delete(key: StorageKeyType): Promise<void>;
-    clear(): Promise<void>;
-    keys(): Promise<string[]>;
-    destroy(): Promise<void>;
-    subscribeToAll(callback: (event: {
-        type: string;
-        changedPaths?: string[];
-        key?: StorageKeyType[] | StorageKeyType;
-        value?: any;
-    }) => void): VoidFunction;
-    initialize(): Promise<this>;
-    subscribe(key: StorageKeyType, callback: (value: any) => void): VoidFunction;
-    subscribe<R>(pathSelector: (state: T) => R, callback: (value: R) => void): VoidFunction;
-    onStatusChange(callback: (status: StorageInitStatus) => void): VoidFunction;
-    waitForReady(): Promise<this>;
-}
-declare enum StorageEvents {
-    STORAGE_UPDATE = "storage:update",
-    STORAGE_DELETE = "storage:delete",
-    STORAGE_PATCH = "storage:patch",
-    STORAGE_SELECT = "storage:select",
-    STORAGE_CLEAR = "storage:clear",
-    STORAGE_DESTROY = "storage:destroy"
-}
-interface StorageEvent<T = any> {
-    type: string;
-    payload?: T;
-    metadata?: Record<string, any>;
-}
-interface IEventEmitter {
-    emit(event: StorageEvent): Promise<void>;
-}
-interface ILogger {
-    debug(message: string, meta?: Record<string, any>): void;
-    info(message: string, meta?: Record<string, any>): void;
-    warn(message: string, meta?: Record<string, any>): void;
-    error(message: string, meta?: Record<string, any>): void;
-}
-interface DefaultMiddlewares {
-    batching: (options?: BatchingMiddlewareOptions) => Middleware;
-    shallowCompare: (options?: ShallowCompareMiddlewareOptions) => Middleware;
-}
-type GetDefaultMiddleware = () => DefaultMiddlewares;
-type ConfigureMiddlewares = (getDefaultMiddleware: GetDefaultMiddleware) => Middleware[];
-interface StorageConfig<T extends Record<string, any> = Record<string, any>> {
-    name: string;
-    initialState?: Partial<T>;
-    middlewares?: ConfigureMiddlewares;
-}
-interface StorageSingletonConfig<T extends Record<string, any> = Record<string, any>> extends StorageConfig<T> {
-    singleton?: SingletonOptions;
-}
-type StorageType = 'memory' | 'localStorage' | 'indexedDB';
-type MemoryStorageConfig<T extends Record<string, any> = Record<string, any>> = StorageSingletonConfig<T>;
-type LocalStorageConfig<T extends Record<string, any> = Record<string, any>> = StorageSingletonConfig<T>;
-interface IndexedDBStorageConfig<T extends Record<string, any> = Record<string, any>> extends StorageSingletonConfig<T> {
-    options: IndexedDBConfig;
-}
-interface UniversalStorageConfig<T extends Record<string, any> = Record<string, any>> extends StorageSingletonConfig<T> {
-    type: StorageType;
-    options?: IndexedDBConfig;
-}
-
-export { type BatchingMiddlewareOptions as B, ConfigMergeStrategy as C, type DefaultMiddlewares as D, type GetDefaultMiddleware as G, IndexedDBStorage as I, type LocalStorageConfig as L, type Middleware as M, type NextFunction as N, type PluginContext as P, type ShallowCompareMiddlewareOptions as S, type UniversalStorageConfig as U, type MiddlewareAPI as a, type StorageAction as b, type StorageKeyType as c, type IPlugin as d, type IStoragePlugin as e, type IPluginExecutor as f, type IPluginManager as g, StorageStatus as h, type StorageInitStatus as i, type IStorage as j, StorageEvents as k, type StorageEvent as l, type IEventEmitter as m, type ILogger as n, type ConfigureMiddlewares as o, type StorageConfig as p, type StorageSingletonConfig as q, type StorageType as r, type MemoryStorageConfig as s, type IndexedDBStorageConfig as t, BaseStorage as u };