@katlux/providers 0.1.1-alpha.95 → 0.1.1-alpha.97

package/dist/index.d.ts

@@ -1,5 +1,36 @@
-import { Ref } from 'vue';
+/**
+ * types.ts — Framework-agnostic hydration and platform abstraction contracts.
+ */
+interface ISSRHydrationAdapter {
+    /**
+     * Retrieve pre-hydrated SSR state for a key. Returns null if not present.
+     */
+    getSSRData<T>(key: string, context?: any): T | null;
+    /**
+     * Execute fetcher with SSR serialization/caching if in an SSR environment,
+     * or simply await fetcher() in standalone/client environments.
+     */
+    fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
+    /**
+     * Invalidate or clear SSR cache for a key (e.g. after mutations).
+     */
+    clearSSRData?(key: string, context?: any): void;
+    /**
+     * Extract SSR hydration payload dictionary (for cache initialization).
+     */
+    getSSRPayload?(context?: any): Record<string, any> | null;
+}
+interface IPlatformRouter {
+    getRoute(): {
+        query: Record<string, any>;
+        path?: string;
+    } | null;
+    getRouter(): any;
+    onReady?(cb: () => void): void;
+}
 
+type TDataProviderListener<T = any> = (provider: T) => void;
+type TUnsubscribe = () => void;
 declare enum EDataFilterOperator {
     Equal = "==",
     NotEqual = "!=",
@@ -37,8 +68,45 @@ interface IRequestOptions {
     cacheKey?: string;
     query?: Record<string, any>;
     deduplicate?: boolean;
+    context?: any;
+    /** @deprecated Use `context` instead */
     nuxtApp?: any;
     disableCache?: boolean;
+    queue?: boolean;
+    queueLabel?: string;
+    label?: string;
+    tags?: string[];
+    signal?: AbortSignal;
+}
+/** Queue persistence backend with automatic fallback: IndexedDB → LocalStorage → Memory */
+declare enum EQueueStorage {
+    Memory = "Memory",
+    LocalStorage = "LocalStorage",
+    IndexedDB = "IndexedDB"
+}
+/** Status of an item currently in the pending queue */
+type TQueueItemStatus = 'pending' | 'flushing';
+/** A single mutation operation waiting to be sent */
+interface IQueuedOperation {
+    id: string;
+    url: string;
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    options: IRequestOptions;
+    tags: string[];
+    label?: string;
+    createdAt: number;
+    flushAttempts: number;
+    status: TQueueItemStatus;
+}
+/** An operation that failed permanently and was moved to the dead-letter store */
+interface IDeadLetterItem extends IQueuedOperation {
+    failedAt: number;
+    lastError: string;
+    httpStatus?: number;
+}
+/** Options for flush operations */
+interface IFlushOptions {
+    tag?: string;
 }
 interface IKDatatableAction {
     action: Function;
@@ -68,18 +136,23 @@ type TPageDataHandler = (currentPage: number, pageSize: number, filter: IDataFil
     disableCache?: boolean;
 }) => IDataResult | Promise<IDataResult>;
 interface IDataProviderOptions {
+    idKey?: string;
     filter?: IDataFilter;
     sortList?: IDataSort[];
     pageSize?: number;
     currentPage?: number;
     SSR?: boolean;
+    initialLoad?: boolean;
     cacheStrategy?: ECacheStrategy;
     cacheLifetime?: number;
     deduplicate?: boolean;
+    context?: any;
+    /** @deprecated Use `context` instead for framework-agnostic SSR context */
     nuxtApp?: any;
     urlPageParam?: string;
     refreshOnMutation?: boolean;
 }
+
 interface ITreeNode {
     data: TDataRow;
     id: string | number;
@@ -102,6 +175,19 @@ interface ITreeDataProviderOptions extends IDataProviderOptions {
     expandedByDefault?: boolean;
     paginateBy?: TreePaginationMode;
 }
+/**
+ * Tree-specific page data handler that includes tree parameters
+ * Server handles tree building, visibility, and pagination
+ */
+type TTreePageDataHandler = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], treeParams: {
+    expandedNodes: (string | number)[] | Set<string | number>;
+    parentKey: string;
+    idKey: string;
+    paginateBy: TreePaginationMode;
+    expandedByDefault: boolean;
+}, options?: {
+    disableCache?: boolean;
+}) => IDataResult | Promise<IDataResult>;
 interface KProductItemData {
     id: string | number;
     title: string;
@@ -118,34 +204,94 @@ interface KProductRowAction {
     color?: 'primary' | 'danger' | 'success' | 'warning' | 'info' | 'light' | 'dark' | 'default';
 }
 
+/**
+ * Standalone CompatRef and CompatArray
+ * Zero-dependency wrappers providing backward-compatibility for .value access
+ * and reactive callback triggers without Vue.
+ */
+declare const VAL_KEY: unique symbol;
+declare const ON_CHANGE_KEY: unique symbol;
+declare class CompatRef<T> {
+    private [VAL_KEY];
+    private [ON_CHANGE_KEY]?;
+    constructor(initial: T, onChange?: (val: T) => void);
+    get value(): T;
+    set value(newVal: T);
+    setOnChange(cb: (val: T) => void): void;
+    valueOf(): T;
+    toString(): string;
+    [Symbol.toPrimitive](hint: string): string | number | T;
+}
+declare class CompatArray<T> extends Array<T> {
+    private [VAL_KEY];
+    private [ON_CHANGE_KEY]?;
+    static get [Symbol.species](): ArrayConstructor;
+    constructor(items?: T[], onChange?: (items: T[]) => void);
+    get value(): T[];
+    set value(newItems: T[]);
+    [Symbol.iterator](): ArrayIterator<T>;
+    setOnChange(cb: (items: T[]) => void): void;
+}
+declare function makeCompatArray<T>(arr: T[]): T[] & {
+    value: T[];
+};
+
 declare abstract class ADataProvider {
-    filter: Ref<IDataFilter | null>;
-    sortList: Ref<IDataSort[]>;
-    currentPage: Ref<number>;
-    pageSize: Ref<number>;
-    pageData: Ref<TDataRow[]>;
-    rowCount: Ref<number>;
-    loading: Ref<Boolean>;
-    SSR: Ref<Boolean>;
-    deduplicate: Ref<Boolean>;
-    nuxtApp: any;
-    urlPageParam: Ref<string>;
-    selectedRows: Ref<any[]>;
-    selectAll: Ref<boolean>;
+    idKey: string;
+    filter: CompatRef<IDataFilter | null>;
+    sortList: CompatRef<IDataSort[]>;
+    currentPage: CompatRef<number>;
+    pageSize: CompatRef<number>;
+    pageData: CompatArray<TDataRow>;
+    rowCount: CompatRef<number>;
+    loading: CompatRef<boolean>;
+    initialLoad: CompatRef<boolean>;
+    error: CompatRef<any>;
+    SSR: CompatRef<boolean>;
+    deduplicate: CompatRef<boolean>;
+    context: any;
+    get nuxtApp(): any;
+    set nuxtApp(val: any);
+    urlPageParam: CompatRef<string>;
+    selectedRows: CompatRef<any[]>;
+    selectAll: CompatRef<boolean>;
+    private _listeners;
     constructor(options?: IDataProviderOptions);
+    subscribe(listener: TDataProviderListener<this>): TUnsubscribe;
+    notify(): void;
+    getState(): {
+        pageData: TDataRow[];
+        rowCount: number;
+        currentPage: number;
+        pageSize: number;
+        loading: boolean;
+        initialLoad: boolean;
+        error: any;
+        filter: IDataFilter | null;
+        sortList: IDataSort[];
+        selectedRows: any[];
+        selectAll: boolean;
+    };
     setFilter(filter: IDataFilter | null): void;
     setSortList(sortList: IDataSort[]): void;
     setCurrentPage(currentPage: number): void;
     setPageSize(pageSize: number): void;
-    abstract loadPageData(): void;
+    abstract loadPageData(options?: {
+        disableCache?: boolean;
+        signal?: AbortSignal;
+    }): void | Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
 }
 
 declare class CFlatClientDataProvider extends ADataProvider {
-    allData: Ref<TDataRow[]>;
-    filteredData: Ref<TDataRow[]>;
+    allData: CompatArray<TDataRow>;
+    filteredData: CompatArray<TDataRow>;
     constructor(options?: IDataProviderOptions);
     setData(data: TDataRow[]): void;
+    refreshData(options?: {
+        disableCache?: boolean;
+    }): Promise<void>;
+    refresh(hardRefresh?: boolean): Promise<void>;
     loadPageData(): Promise<void>;
 }
 
@@ -162,9 +308,14 @@ declare abstract class ACacheProvider {
 
 declare class RequestProvider {
     cacheProvider: ACacheProvider | null;
+    cacheStrategy?: ECacheStrategy;
     cacheLifetime: number | null;
     deduplicate: boolean;
     cacheKey: string;
+    /** Registry tags — set via useRequestProvider() or manually */
+    tags: string[];
+    /** If true, non-GET requests are enqueued instead of sent immediately */
+    queue: boolean;
     private static requestQueue;
     private static executing;
     private static requestsInFlight;
@@ -185,11 +336,11 @@ declare class RequestProvider {
 }
 
 declare abstract class AAPIDataProvider {
-    apiUrl: Ref<string>;
-    cacheStrategy: Ref<ECacheStrategy | null>;
-    cacheLifetime: Ref<number>;
+    apiUrl: CompatRef<string>;
+    cacheStrategy: CompatRef<ECacheStrategy | null>;
+    cacheLifetime: CompatRef<number>;
     requestProvider: RequestProvider;
-    refreshOnMutation: Ref<boolean | undefined>;
+    refreshOnMutation: CompatRef<boolean | undefined>;
     constructor(options?: IDataProviderOptions);
     abstract setAPIUrl(url: string): void;
     abstract create(item: any): Promise<void>;
@@ -198,13 +349,12 @@ declare abstract class AAPIDataProvider {
 }
 
 declare class CAPIFlatClientDataProvider extends CFlatClientDataProvider implements AAPIDataProvider {
-    apiUrl: Ref<string>;
-    contextKey: Ref<string>;
-    initialLoad: Ref<boolean>;
+    apiUrl: CompatRef<string>;
+    contextKey: CompatRef<string>;
     requestProvider: RequestProvider;
-    cacheStrategy: Ref<ECacheStrategy | null>;
-    cacheLifetime: Ref<number>;
-    refreshOnMutation: Ref<boolean | undefined>;
+    cacheStrategy: CompatRef<ECacheStrategy | null>;
+    cacheLifetime: CompatRef<number>;
+    refreshOnMutation: CompatRef<boolean | undefined>;
     constructor(options?: IDataProviderOptions);
     setContextKey(key: string): void;
     refresh(hardRefresh?: boolean): Promise<void>;
@@ -219,24 +369,26 @@ declare class CAPIFlatClientDataProvider extends CFlatClientDataProvider impleme
 }
 
 declare class CFlatServerDataProvider extends ADataProvider {
-    pageDataHandler: Ref<TPageDataHandler>;
-    contextKey: Ref<string>;
-    initialLoad: Ref<boolean>;
+    pageDataHandler: CompatRef<TPageDataHandler>;
+    contextKey: CompatRef<string>;
+    private latestRequestId;
+    private abortController;
     constructor(options?: IDataProviderOptions);
     setContextKey(key: string): void;
     setPageDataHandler(handler: TPageDataHandler): Promise<void>;
     loadPageData(options?: {
         disableCache?: boolean;
+        signal?: AbortSignal;
     }): Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
 }
 
 declare class CAPIFlatServerDataProvider extends CFlatServerDataProvider implements AAPIDataProvider {
-    apiUrl: Ref<string>;
+    apiUrl: CompatRef<string>;
     requestProvider: RequestProvider;
-    cacheStrategy: Ref<ECacheStrategy | null>;
-    cacheLifetime: Ref<number>;
-    refreshOnMutation: Ref<boolean | undefined>;
+    cacheStrategy: CompatRef<ECacheStrategy | null>;
+    cacheLifetime: CompatRef<number>;
+    refreshOnMutation: CompatRef<boolean | undefined>;
     constructor(options?: IDataProviderOptions);
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
@@ -244,6 +396,8 @@ declare class CAPIFlatServerDataProvider extends CFlatServerDataProvider impleme
     }): Promise<void>;
     setAPIUrl(url: string): Promise<void>;
     delete(items: any[]): Promise<void>;
+    create(item: any): Promise<void>;
+    update(item: any): Promise<void>;
 }
 
 declare class CTreeClientDataProvider extends CFlatClientDataProvider {
@@ -251,11 +405,16 @@ declare class CTreeClientDataProvider extends CFlatClientDataProvider {
     idKey: string;
     expandedByDefault: boolean;
     paginateBy: TreePaginationMode;
-    expandedNodes: Ref<Set<string | number>>;
-    private _staticNodes;
-    private _nodeMap;
-    private _sortedNodeIds;
+    expandedNodes: CompatRef<Set<string | number>>;
+    private _staticNodesCache;
+    private _nodeMapCache;
+    private _sortedNodeIdsCache;
+    private get _staticNodes();
+    private get _nodeMap();
+    private get _sortedNodeIds();
+    private invalidateStaticCache;
     constructor(options?: ITreeDataProviderOptions);
+    setData(data: TDataRow[]): void;
     private buildStaticNodes;
     private computeSortedIds;
     private updatePageData;
@@ -275,13 +434,12 @@ declare class CTreeClientDataProvider extends CFlatClientDataProvider {
 }
 
 declare class CAPITreeClientDataProvider extends CTreeClientDataProvider implements AAPIDataProvider {
-    apiUrl: Ref<string>;
-    contextKey: Ref<string>;
-    initialLoad: Ref<boolean>;
+    apiUrl: CompatRef<string>;
+    contextKey: CompatRef<string>;
     requestProvider: RequestProvider;
-    cacheStrategy: Ref<ECacheStrategy | null>;
-    cacheLifetime: Ref<number>;
-    refreshOnMutation: Ref<boolean | undefined>;
+    cacheStrategy: CompatRef<ECacheStrategy | null>;
+    cacheLifetime: CompatRef<number>;
+    refreshOnMutation: CompatRef<boolean | undefined>;
     constructor(options?: ITreeDataProviderOptions);
     setContextKey(key: string): void;
     refresh(hardRefresh?: boolean): Promise<void>;
@@ -295,19 +453,6 @@ declare class CAPITreeClientDataProvider extends CTreeClientDataProvider impleme
     delete(items: any[]): Promise<void>;
 }
 
-/**
- * Tree-specific page data handler that includes tree parameters
- * Server handles tree building, visibility, and pagination
- */
-type TTreePageDataHandler = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], treeParams: {
-    expandedNodes: (string | number)[];
-    parentKey: string;
-    idKey: string;
-    paginateBy: TreePaginationMode;
-    expandedByDefault: boolean;
-}, options?: {
-    disableCache?: boolean;
-}) => IDataResult | Promise<IDataResult>;
 /**
  * Server-side Tree Data Provider
  *
@@ -322,19 +467,21 @@ declare class CTreeServerDataProvider extends ADataProvider {
     idKey: string;
     expandedByDefault: boolean;
     paginateBy: TreePaginationMode;
-    expandedNodes: Ref<Set<string | number>>;
-    pageDataHandler: Ref<TTreePageDataHandler | null>;
-    contextKey: Ref<string>;
-    initialLoad: Ref<boolean>;
+    expandedNodes: CompatRef<Set<string | number>>;
+    pageDataHandler: CompatRef<TTreePageDataHandler | null>;
+    contextKey: CompatRef<string>;
     constructor(options?: ITreeDataProviderOptions);
     setContextKey(key: string): void;
     setPageDataHandler(handler: TTreePageDataHandler): Promise<void>;
+    private latestRequestId;
+    private abortController;
     /**
      * Load page data from server
      * Server handles tree building, visibility, and pagination
      */
     loadPageData(options?: {
         disableCache?: boolean;
+        signal?: AbortSignal;
     }): Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
     toggleNode(nodeId: string | number): void;
@@ -353,11 +500,11 @@ declare class CTreeServerDataProvider extends ADataProvider {
  * - Automatic tree parameter serialization in query
  */
 declare class CAPITreeServerDataProvider extends CTreeServerDataProvider implements AAPIDataProvider {
-    apiUrl: Ref<string>;
+    apiUrl: CompatRef<string>;
     requestProvider: RequestProvider;
-    cacheStrategy: Ref<ECacheStrategy | null>;
-    cacheLifetime: Ref<number>;
-    refreshOnMutation: Ref<boolean | undefined>;
+    cacheStrategy: CompatRef<ECacheStrategy | null>;
+    cacheLifetime: CompatRef<number>;
+    refreshOnMutation: CompatRef<boolean | undefined>;
     constructor(options?: ITreeDataProviderOptions);
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
@@ -365,21 +512,90 @@ declare class CAPITreeServerDataProvider extends CTreeServerDataProvider impleme
     }): Promise<void>;
     setAPIUrl(url: string): Promise<void>;
     delete(items: any[]): Promise<void>;
+    create(item: any): Promise<void>;
+    update(item: any): Promise<void>;
+}
+
+/**
+ * KatluxIndexedDB
+ *
+ * Shared IndexedDB connection singleton for the entire @katlux/providers library.
+ * All IndexedDB consumers (CIndexedDBCache, RequestQueue) use this single connection,
+ * ensuring there is one database, one version number, and no versionchange conflicts.
+ *
+ * KatluxDB stores:
+ *   cache       — used by CIndexedDBCache
+ *   queue       — used by RequestQueue (pending operations)
+ *   dead_letter — used by RequestQueue (permanently failed operations)
+ */
+type TKatluxStore = 'cache' | 'queue' | 'dead_letter' | (string & {});
+declare class KatluxIndexedDB {
+    private static db;
+    private static openPromise;
+    private static currentVersion;
+    private static customStores;
+    static readonly DB_NAME = "KatluxDB";
+    static get DB_VERSION(): number;
+    /**
+     * Opens (or returns the existing) shared IDBDatabase connection.
+     * Safe to call multiple times — always resolves to the same instance.
+     */
+    static open(): Promise<IDBDatabase>;
+    /**
+     * Dynamically ensures that an object store exists in the database.
+     * If not present, performs a database version bump and creates the store.
+     */
+    static ensureStore(storeName: string): Promise<IDBDatabase>;
+    /**
+     * Returns a transaction-bound object store.
+     * Convenience wrapper used by CIndexedDBCache, QueueStorage adapters, etc.
+     */
+    static getStore(storeName: TKatluxStore, mode: IDBTransactionMode): Promise<IDBObjectStore>;
+    /**
+     * For testing only — resets the singleton so tests can start fresh.
+     */
+    static _reset(): void;
 }
 
+type CacheDriverLoader = () => Promise<{
+    getInstance: () => ACacheProvider;
+}>;
 declare class CacheProviderFactory {
-    static getProvider(strategy: ECacheStrategy): ACacheProvider | null;
+    private static instanceCache;
+    private static customDrivers;
+    private static readonly defaultLoaders;
+    /**
+     * Register a custom or pre-loaded cache provider driver
+     */
+    static registerDriver(strategy: string, loaderOrClass: CacheDriverLoader | {
+        getInstance: () => ACacheProvider;
+    }): void;
+    /**
+     * Asynchronously load and return the cache provider singleton for a strategy.
+     */
+    static getProvider(strategy: ECacheStrategy | string): Promise<ACacheProvider | null>;
+    /**
+     * Synchronously returns the cache provider if it was already loaded/instantiated,
+     * or undefined otherwise.
+     */
+    static getProviderSync(strategy: ECacheStrategy | string): ACacheProvider | undefined;
+    /**
+     * Clear cached singleton instances (useful for testing or cache resets)
+     */
+    static clearInstances(): void;
 }
 
 declare class CSessionCache extends ACacheProvider {
     private static instance;
     static getInstance(): CSessionCache;
-    private static get storage();
+    static get storage(): Map<string, Map<string, ICacheEntry<any>>>;
     static getSnapshot(): Map<string, Map<string, ICacheEntry<any>>>;
+    private static cleanupTimer;
+    private static initCleanupTimer;
     private sessionIdCache;
     private sessionId;
     private readonly SESSION_ID_KEY;
-    private constructor();
+    constructor();
     /**
      * Generate a UUID v4 sessionId
      */
@@ -401,11 +617,15 @@ declare class CCookieCache extends ACacheProvider {
     private static instance;
     static getInstance(): CCookieCache;
     type: string;
-    private constructor();
+    constructor();
+    private getCookieKey;
+    private parseKeyFromCookieName;
+    private isClient;
     getKeyList(nuxtApp?: any): Promise<Array<string>>;
     get<T>(key: string, nuxtApp?: any): Promise<T | null>;
     set<T>(key: string, data: T, lifetime: number, nuxtApp?: any): Promise<void>;
     remove(key: string, nuxtApp?: any): Promise<void>;
+    removeByPrefix(prefix: string, nuxtApp?: any): Promise<void>;
     getRemainingTime(key: string, nuxtApp?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
@@ -428,14 +648,8 @@ declare class CLocalStorageCache extends ACacheProvider {
 declare class CIndexedDBCache extends ACacheProvider {
     private static instance;
     static getInstance(): CIndexedDBCache;
-    private dbName;
-    private storeName;
-    private version;
-    private dbPromise;
-    setStore(storeName?: string): void;
     private constructor();
     private _hydrateFromPayload;
-    private openDB;
     private getStore;
     getKeyList(nuxtApp?: any): Promise<Array<string>>;
     get<T>(key: string, nuxtApp?: any): Promise<T | null>;
@@ -478,5 +692,295 @@ declare class CApplicationCache extends ACacheProvider {
     cleanupExpired(): Promise<void>;
 }
 
-export { AAPIDataProvider, ADataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CCookieCache, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CLocalStorageCache, CMemoryCache, CSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CacheProviderFactory, ECacheStrategy, EDataFilterOperator, RequestProvider };
-export type { ICacheEntry, IDataFilter, IDataProviderOptions, IDataResult, IDataSort, IKDatatableAction, IRequestOptions, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, KProductItemData, KProductRowAction, TDataRow, TPageDataHandler, TreePaginationMode };
+interface IRegistryEntry {
+    provider: RequestProvider;
+    tags: string[];
+}
+/**
+ * RequestProviderRegistry
+ *
+ * Static singleton registry that maps RequestProvider instances to string tags.
+ * When a mutation completes on any tagged provider, the registry automatically
+ * calls refresh(true) on all GET-capable providers sharing any of those tags.
+ *
+ * Framework-agnostic — no Vue imports. Works in any JS environment.
+ *
+ * Usage:
+ *   // Register (or use the useRequestProvider() Vue composable for auto-lifecycle)
+ *   RequestProviderRegistry.register(myProvider, ['invoices', 'sales'])
+ *
+ *   // Unregister manually (or automatically via useRequestProvider onUnmounted)
+ *   RequestProviderRegistry.unregister(myProvider)
+ *
+ *   // Manual targeted refresh
+ *   await RequestProviderRegistry.refreshByTag('invoices', true)
+ *
+ *   // Called internally by RequestProvider after a successful non-GET request
+ *   await RequestProviderRegistry.notifyMutation(['invoices'])
+ */
+declare class RequestProviderRegistry {
+    private static entries;
+    /**
+     * Register a provider with one or more tags.
+     * If the provider is already registered, its tags are updated.
+     */
+    static register(provider: RequestProvider, tags: string[]): void;
+    /**
+     * Unregister a provider from the registry.
+     * After this, the provider will no longer receive auto-refresh signals.
+     */
+    static unregister(provider: RequestProvider): void;
+    /**
+     * Manually refresh all providers matching a specific tag.
+     */
+    static refreshByTag(tag: string, hardRefresh?: boolean): Promise<void>;
+    /**
+     * Called internally by RequestProvider (after non-GET success) and by
+     * RequestQueue (after flush with at least one success).
+     *
+     * Finds all registered providers sharing any of the succeeded tags and
+     * calls refresh(true) once per unique provider (deduplication built in).
+     */
+    static notifyMutation(succeededTags: string[]): Promise<void>;
+    /**
+     * Returns a copy of all registry entries.
+     * Useful for debugging and testing.
+     */
+    static getEntries(): IRegistryEntry[];
+    /**
+     * Clears the entire registry.
+     * Use on app teardown (e.g., logout) or in tests.
+     */
+    static clear(): void;
+}
+
+/**
+ * RequestQueue
+ *
+ * Static class that manages the offline mutation queue and dead-letter store.
+ * All state is reactive (CompatRef / CompatArray) so UI components and standalone code can bind directly.
+ *
+ * Design rules:
+ *  - Stop-on-first-failure: flush halts when any item fails
+ *  - No internal retry: the queue is the retry mechanism (items persist until flushed)
+ *  - Partial refresh: registry refresh fires for succeeded tags only
+ *  - Dead-letter is final: Katlux never auto-retries — app decides via retryOne() or discard()
+ *
+ * Usage:
+ *   RequestQueue.setStorageBackend(EQueueStorage.IndexedDB)
+ *   await RequestQueue.init()  // call once at app startup
+ *
+ *   // Hooks (set in app setup, not in components)
+ *   RequestQueue.onDeadLetter((item, err) => toast.error(`Failed: ${item.label}`))
+ *   RequestQueue.onFlushComplete((tags) => console.log('Synced tags:', tags))
+ *   RequestQueue.onNetworkError((item) => toast.warn('Offline — will retry when back online'))
+ *
+ *   // Flush when back online
+ *   window.addEventListener('online', () => RequestQueue.flushAll())
+ */
+declare class RequestQueue {
+    static queue: CompatArray<IQueuedOperation>;
+    static deadLetterQueue: CompatArray<IDeadLetterItem>;
+    static isFlushing: CompatRef<boolean>;
+    private static adapter;
+    private static initialized;
+    private static _onDeadLetter;
+    private static _onFlushComplete;
+    private static _onNetworkError;
+    /**
+     * Load persisted queue from storage into reactive state.
+     * Call once at app startup, before any flush or enqueue operations.
+     */
+    static init(): Promise<void>;
+    /**
+     * Set the storage backend. Call before init().
+     * Defaults to IndexedDB with fallback to LocalStorage → Memory.
+     */
+    static setStorageBackend(backend: EQueueStorage): void;
+    static onDeadLetter(cb: (item: IDeadLetterItem, error: Error) => void): void;
+    static onFlushComplete(cb: (succeededTags: string[]) => void): void;
+    static onNetworkError(cb: (item: IQueuedOperation) => void): void;
+    /**
+     * Add an operation to the pending queue and persist it.
+     * Called internally by RequestProvider when queue: true.
+     * Returns the stable ID of the queued item.
+     */
+    static enqueue(operation: Omit<IQueuedOperation, 'id' | 'createdAt' | 'flushAttempts' | 'status'>): Promise<string>;
+    static getQueue(tag?: string): IQueuedOperation[];
+    static getDeadLetterQueue(tag?: string): IDeadLetterItem[];
+    /**
+     * Flush queued items in FIFO order.
+     * Stops on first failure. Refreshes registry for succeeded tags only.
+     */
+    static flushAll(options?: IFlushOptions): Promise<void>;
+    /**
+     * Flush a specific pending item by ID, independent of queue position.
+     * On success: triggers registry refresh for its own tags.
+     * On failure: moves to dead-letter independently.
+     */
+    static flushOne(id: string): Promise<void>;
+    /**
+     * Move a dead-letter item back to the FRONT of the pending queue for retry.
+     * App should call flushAll() afterwards.
+     */
+    static retryOne(id: string): Promise<void>;
+    /**
+     * Permanently remove an item from either the pending queue or dead-letter store.
+     */
+    static discard(id: string): Promise<void>;
+    /**
+     * Reorder the pending queue by providing an ordered array of IDs.
+     * Fully permissive — causal ordering is the app's responsibility.
+     */
+    static reorder(ids: string[]): void;
+    private static executeRequest;
+    private static moveToDeadLetter;
+    private static persistQueue;
+    private static persistDeadLetter;
+    /** For testing only */
+    static _reset(): void;
+}
+
+interface IQueueStorageAdapter {
+    loadQueue(): Promise<IQueuedOperation[]>;
+    saveQueue(items: IQueuedOperation[]): Promise<void>;
+    loadDeadLetter(): Promise<IDeadLetterItem[]>;
+    saveDeadLetter(items: IDeadLetterItem[]): Promise<void>;
+}
+declare class QueueStorageFactory {
+    private static indexedDBAdapter;
+    private static localStorageAdapter;
+    private static memoryAdapter;
+    /**
+     * Returns an adapter for the requested backend.
+     * Falls back automatically if the requested backend is unavailable:
+     *   IndexedDB → LocalStorage → Memory
+     */
+    static getAdapter(backend: EQueueStorage): IQueueStorageAdapter;
+    static _reset(): void;
+}
+
+declare const compareIn: (rowValue: any, filterValue: any) => boolean;
+declare const compareEqual: (rowValue: any, filterValue: any) => boolean;
+declare const compareValues: (rowValue: any, filterValue: any) => number;
+declare const compareAnd: (row: TDataRow, nested: any) => boolean;
+declare const compareOr: (row: TDataRow, nested: any) => boolean;
+declare const applyOperator: (operator: string, rowValue: any, filterValue: any) => boolean;
+declare const evaluateFilter: (filter: IDataFilter, row: TDataRow) => boolean;
+declare const filterTreeData: (nodes: any[], filter: IDataFilter, options: {
+    idKey: string;
+    parentKey: string;
+}) => {
+    visibleNodes: any[];
+    expandedNodes: Set<string | number>;
+};
+declare const filterData: (data: any[], filter: IDataFilter, options?: {
+    treeOptions?: {
+        idKey: string;
+        parentKey: string;
+    };
+}) => {
+    results: any[];
+    expandedNodes?: Set<string | number>;
+};
+declare const useFilterLogic: () => {
+    evaluateFilter: (filter: IDataFilter, row: TDataRow) => boolean;
+    filterTreeData: (nodes: any[], filter: IDataFilter, options: {
+        idKey: string;
+        parentKey: string;
+    }) => {
+        visibleNodes: any[];
+        expandedNodes: Set<string | number>;
+    };
+    filterData: (data: any[], filter: IDataFilter, options?: {
+        treeOptions?: {
+            idKey: string;
+            parentKey: string;
+        };
+    }) => {
+        results: any[];
+        expandedNodes?: Set<string | number>;
+    };
+};
+
+declare const sortData: (sortList: IDataSort[], rows: TDataRow[]) => TDataRow[];
+declare const useSortLogic: () => {
+    sortData: (sortList: IDataSort[], rows: TDataRow[]) => TDataRow[];
+};
+
+/**
+ * Universal debounce utility
+ */
+declare const useDebounce: <T extends (...args: any[]) => any>(callback: T, delay: number) => ((...args: Parameters<T>) => void);
+declare const debounce: <T extends (...args: any[]) => any>(callback: T, delay: number) => ((...args: Parameters<T>) => void);
+
+/**
+ * defaultAdapter.ts — Framework-agnostic default implementation of ISSRHydrationAdapter.
+ * Pure Vanilla JS / React / Node.js with zero framework dependencies.
+ */
+
+declare class DefaultHydrationAdapter implements ISSRHydrationAdapter {
+    getSSRData<T>(key: string, context?: any): T | null;
+    fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
+    clearSSRData(key: string, context?: any): void;
+    getSSRPayload(context?: any): Record<string, any> | null;
+}
+
+/**
+ * nuxtAdapter.ts — Nuxt 3 implementation of ISSRHydrationAdapter.
+ * Bridges to Nuxt 3's useNuxtData, useAsyncData, and useNuxtApp when running in Nuxt.
+ */
+
+declare class NuxtHydrationAdapter implements ISSRHydrationAdapter {
+    private fallback;
+    getSSRData<T>(key: string, context?: any): T | null;
+    fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
+    clearSSRData(key: string, context?: any): void;
+    getSSRPayload(context?: any): Record<string, any> | null;
+}
+
+/**
+ * index.ts — Framework-agnostic hydration and platform bridge.
+ * Provides unified, safe methods for SSR hydration, routing, and lifecycle hooks.
+ */
+
+declare function getHydrationAdapter(): ISSRHydrationAdapter;
+declare function setHydrationAdapter(adapter: ISSRHydrationAdapter): void;
+/**
+ * Retrieve SSR state for a key. Returns null if not found.
+ */
+declare function getSSRData<T>(key: string, context?: any): T | null;
+/**
+ * Execute fetcher with SSR caching/serialization or fallback directly.
+ */
+declare function fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
+/**
+ * Clear SSR data for a key.
+ */
+declare function clearSSRData(key: string, context?: any): void;
+/**
+ * Extract SSR payload dictionary for hydration of memory/storage caches.
+ */
+declare function getSSRPayload(context?: any): Record<string, any> | null;
+/**
+ * Safe platform app accessor.
+ */
+declare function getPlatformApp(): any;
+/**
+ * Safe route accessor with browser URLSearchParams fallback for React/Vanilla.
+ */
+declare function getAppRoute(): {
+    query: Record<string, any>;
+    path?: string;
+} | null;
+/**
+ * Safe router accessor with window.history fallback for React/Vanilla.
+ */
+declare function getAppRouter(): any;
+/**
+ * Register a callback when platform hydration is ready or DOMContentLoaded.
+ */
+declare function onPlatformReady(cb: () => void): void;
+
+export { AAPIDataProvider, ADataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CCookieCache, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CLocalStorageCache, CMemoryCache, CSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CacheProviderFactory, CompatArray, CompatRef, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, NuxtHydrationAdapter, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, applyOperator, clearSSRData, compareAnd, compareEqual, compareIn, compareOr, compareValues, debounce, evaluateFilter, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getHydrationAdapter, getPlatformApp, getSSRData, getSSRPayload, makeCompatArray, onPlatformReady, setHydrationAdapter, sortData, useDebounce, useFilterLogic, useSortLogic };
+export type { CacheDriverLoader, ICacheEntry, IDataFilter, IDataProviderOptions, IDataResult, IDataSort, IDeadLetterItem, IFlushOptions, IKDatatableAction, IPlatformRouter, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, KProductItemData, KProductRowAction, TDataProviderListener, TDataRow, TKatluxStore, TPageDataHandler, TQueueItemStatus, TTreePageDataHandler, TUnsubscribe, TreePaginationMode };