@katlux/providers 0.1.1-alpha.100 → 0.1.1-alpha.102

package/dist/index.d.cts

@@ -47,7 +47,8 @@ declare enum EDataFilterOperator {
 }
 declare enum ECacheStrategy {
     Application = "Application",
-    Session = "Session",
+    ServerSession = "ServerSession",
+    BrowserSession = "BrowserSession",
     Memory = "Memory",
     LocalStorage = "LocalStorage",
     IndexedDB = "IndexedDB",
@@ -69,14 +70,13 @@ interface IRequestOptions {
     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;
+    _generation?: number;
 }
 /** Queue persistence backend with automatic fallback: IndexedDB → LocalStorage → Memory */
 declare enum EQueueStorage {
@@ -122,19 +122,20 @@ type TDataRow = {
 interface IDataFilter {
     operator: EDataFilterOperator;
     field: TDataRow | IDataFilter[];
-    active: Boolean;
+    active: boolean;
 }
 interface IDataSort {
     field: string;
     direction: 'asc' | 'desc';
 }
-interface IDataResult {
+interface IDataResult<TRow = TDataRow> {
     rowCount: number;
-    rows: TDataRow[];
+    rows: TRow[];
 }
-type TPageDataHandler = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], options?: {
+type TPageDataHandler<TRow = TDataRow> = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], options?: {
     disableCache?: boolean;
-}) => IDataResult | Promise<IDataResult>;
+    signal?: AbortSignal;
+}) => IDataResult<TRow> | Promise<IDataResult<TRow>>;
 interface IDataProviderOptions {
     idKey?: string;
     filter?: IDataFilter;
@@ -147,29 +148,56 @@ interface IDataProviderOptions {
     cacheLifetime?: number;
     deduplicate?: boolean;
     context?: any;
-    /** @deprecated Use `context` instead for framework-agnostic SSR context */
-    nuxtApp?: any;
+    contextKey?: string;
     urlPageParam?: string;
     refreshOnMutation?: boolean;
+    filterDebounce?: number;
+    sortDebounce?: number;
 }
 
-interface ITreeNode {
-    data: TDataRow;
+interface ITreeNode<TRow = TDataRow> {
+    data: TRow;
     id: string | number;
     parentId: string | number | null;
     depth: number;
     hasChildren: boolean;
     isExpanded: boolean;
 }
-interface ITreeNodeStatic {
-    data: TDataRow;
+interface ITreeNodeStatic<TRow = TDataRow> {
+    data: TRow;
     id: string | number;
     parentId: string | number | null;
     depth: number;
     hasChildren: boolean;
     childIds?: (string | number)[];
 }
+/**
+ * A row enriched with tree metadata by a tree data provider
+ */
+type TTreeRow<TRow = TDataRow> = TRow & {
+    id?: string | number;
+    __treeNode?: ITreeNode<TRow>;
+    depth?: number;
+    hasChildren?: boolean;
+    isExpanded?: boolean;
+    parentId?: string | number | null;
+};
 type TreePaginationMode = 'all' | 'root';
+/**
+ * Interface describing a DataProvider with hierarchical tree capabilities
+ */
+interface ITreeDataProvider<TRow = TDataRow> {
+    toggleNode(id: string | number): void;
+    expandedNodes: Set<string | number> | {
+        value: Set<string | number>;
+    };
+    parentKey?: string;
+    expandedByDefault?: boolean;
+    paginateBy?: TreePaginationMode;
+    collapseAll?(): void;
+    expandAll?(): void;
+    isExpanded?(id: string | number): boolean;
+}
 interface ITreeDataProviderOptions extends IDataProviderOptions {
     parentKey?: string;
     idKey?: string;
@@ -180,7 +208,7 @@ interface ITreeDataProviderOptions extends IDataProviderOptions {
  * 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: {
+type TTreePageDataHandler<TRow = TDataRow> = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], treeParams: {
     expandedNodes: (string | number)[] | Set<string | number>;
     parentKey: string;
     idKey: string;
@@ -188,7 +216,7 @@ type TTreePageDataHandler = (currentPage: number, pageSize: number, filter: IDat
     expandedByDefault: boolean;
 }, options?: {
     disableCache?: boolean;
-}) => IDataResult | Promise<IDataResult>;
+}) => IDataResult<TRow> | Promise<IDataResult<TRow>>;
 interface KProductItemData {
     id: string | number;
     title: string;
@@ -205,21 +233,31 @@ interface KProductRowAction {
     color?: 'primary' | 'danger' | 'success' | 'warning' | 'info' | 'light' | 'dark' | 'default';
 }
 
-declare abstract class ADataProvider {
+declare abstract class ADataProvider<TRow = TDataRow> {
     idKey: string;
-    pageData: TDataRow[];
-    rowCount: number;
-    loading: boolean;
-    initialLoad: boolean;
-    error: any;
+    pageData: TRow[];
+    protected _rowCount: number;
+    get rowCount(): number;
+    set rowCount(val: number);
+    protected _loading: boolean;
+    get loading(): boolean;
+    set loading(val: boolean);
+    protected _initialLoad: boolean;
+    get initialLoad(): boolean;
+    set initialLoad(val: boolean);
+    protected _error: any;
+    get error(): any;
+    set error(val: any);
     SSR: boolean;
     deduplicate: boolean;
     context: any;
-    get nuxtApp(): any;
-    set nuxtApp(val: any);
     urlPageParam: string;
-    selectedRows: any[];
-    selectAll: boolean;
+    protected _selectedRows: TRow[];
+    get selectedRows(): TRow[];
+    set selectedRows(val: TRow[]);
+    protected _selectAll: boolean;
+    get selectAll(): boolean;
+    set selectAll(val: boolean);
     protected _currentPage: number;
     protected _pageSize: number;
     protected _filter: IDataFilter | null;
@@ -234,11 +272,19 @@ declare abstract class ADataProvider {
     set sortList(s: IDataSort[]);
     private _listeners;
     private _debouncedFilterLoad;
+    private _debouncedSortLoad;
     constructor(options?: IDataProviderOptions);
+    private _batchDepth;
+    private _pendingNotify;
+    private _isNotifying;
+    /**
+     * Batches multiple state updates so notify() fires exactly once upon completion.
+     */
+    batchUpdates<R>(fn: () => R): R;
     subscribe(listener: TDataProviderListener<this>): TUnsubscribe;
     notify(): void;
     getState(): {
-        pageData: TDataRow[];
+        pageData: TRow[];
         rowCount: number;
         currentPage: number;
         pageSize: number;
@@ -247,27 +293,40 @@ declare abstract class ADataProvider {
         error: any;
         filter: IDataFilter | null;
         sortList: IDataSort[];
-        selectedRows: any[];
+        selectedRows: TRow[];
         selectAll: boolean;
     };
-    setFilter(filter: IDataFilter | null): void;
-    setSortList(sortList: IDataSort[]): void;
+    setFilter(filter: IDataFilter | null, immediate?: boolean): void;
+    setSortList(sortList: IDataSort[], immediate?: boolean): void;
     setCurrentPage(currentPage: number): void;
     setPageSize(pageSize: number): void;
-    setSelectedRows(rows: any[]): void;
+    setSelectedRows(rows: TRow[]): void;
     setSelectAll(val: boolean): void;
     abstract loadPageData(options?: {
         disableCache?: boolean;
         signal?: AbortSignal;
     }): void | Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
+    cancelPending(): void;
 }
 
-declare class CFlatClientDataProvider extends ADataProvider {
-    allData: TDataRow[];
-    filteredData: TDataRow[];
+declare class CFlatClientDataProvider<TRow = TDataRow> extends ADataProvider<TRow> {
+    private _allData;
+    filteredData: TRow[];
+    private _rowMap;
+    private _filterDirty;
+    private _sortDirty;
     constructor(options?: IDataProviderOptions);
-    setData(data: TDataRow[]): void;
+    get allData(): TRow[];
+    set allData(data: TRow[]);
+    get rowMap(): readonly TRow[];
+    setData(data: TRow[]): void;
+    setFilter(filter: IDataFilter | null, immediate?: boolean): void;
+    setSortList(sortList: IDataSort[], immediate?: boolean): void;
+    /**
+     * Explicitly rebuilds the reference map array if row properties inside allData were mutated in-place.
+     */
+    updateMap(): void;
     refreshData(options?: {
         disableCache?: boolean;
     }): Promise<void>;
@@ -277,12 +336,12 @@ declare class CFlatClientDataProvider extends ADataProvider {
 
 declare abstract class ACacheProvider {
     constructor();
-    abstract getKeyList(nuxtApp?: any): Array<string> | Promise<Array<string>>;
-    abstract get<T>(key: string, nuxtApp?: any): Promise<T | null>;
-    abstract set<T>(key: string, data: T, lifetime: number, nuxtApp?: any): Promise<void>;
-    abstract remove(key: string, nuxtApp?: any): Promise<void>;
-    abstract removeByPrefix(prefix: string, nuxtApp?: any): Promise<void>;
-    abstract getRemainingTime(key: string, nuxtApp?: any): Promise<number | null>;
+    abstract getKeyList(context?: any): Array<string> | Promise<Array<string>>;
+    abstract get<T>(key: string, context?: any): Promise<T | null>;
+    abstract set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    abstract remove(key: string, context?: any): Promise<void>;
+    abstract removeByPrefix(prefix: string, context?: any): Promise<void>;
+    abstract getRemainingTime(key: string, context?: any): Promise<number | null>;
     abstract cleanupExpired(): Promise<void>;
 }
 
@@ -306,12 +365,16 @@ declare class RequestProvider {
     setCacheProvider(provider?: ACacheProvider | ECacheStrategy): void;
     setCacheLifetime(lifetime: number): void;
     setDeduplicate(deduplicate: boolean): void;
-    onDataReceived(callback: (data: any) => void): void;
+    onDataReceived(callback: (data: any, generation?: number) => void): void;
+    private invokeDataReceivedCallback;
     hasLastUrl(): boolean;
     refresh(hardRefresh?: boolean): Promise<any>;
+    private resolveContext;
+    private getInFlightMap;
     private getUniqueKey;
     registerRequest<T>(url: string, options?: IRequestOptions): Promise<T>;
     static executeAll(): void;
+    private isSameOriginUrl;
     request<T>(url: string, options?: IRequestOptions): Promise<T>;
 }
 
@@ -328,7 +391,7 @@ declare abstract class AAPIDataProvider {
     abstract delete(items: any[]): Promise<void>;
 }
 
-declare class CAPIFlatClientDataProvider extends CFlatClientDataProvider implements AAPIDataProvider {
+declare class CAPIFlatClientDataProvider<TRow = TDataRow> extends CFlatClientDataProvider<TRow> implements AAPIDataProvider {
     apiUrl: string;
     contextKey: string;
     requestProvider: RequestProvider;
@@ -337,25 +400,25 @@ declare class CAPIFlatClientDataProvider extends CFlatClientDataProvider impleme
     refreshOnMutation: boolean | undefined;
     constructor(options?: IDataProviderOptions);
     setContextKey(key: string): void;
-    refresh(hardRefresh?: boolean): Promise<void>;
+    setCacheStrategy(strategy: ECacheStrategy): void;
+    setCacheLifetime(lifetime: number): void;
     refreshData(options?: {
         disableCache?: boolean;
     }): Promise<void>;
-    private _initialFetch;
     setAPIUrl(url: string): Promise<void>;
     create(item: any): Promise<void>;
     update(item: any): Promise<void>;
     delete(items: any[]): Promise<void>;
 }
 
-declare class CFlatServerDataProvider extends ADataProvider {
-    pageDataHandler: TPageDataHandler;
+declare class CFlatServerDataProvider<TRow = TDataRow> extends ADataProvider<TRow> {
+    pageDataHandler: TPageDataHandler<TRow>;
     contextKey: string;
     private latestRequestId;
     private abortController;
     constructor(options?: IDataProviderOptions);
     setContextKey(key: string): void;
-    setPageDataHandler(handler: TPageDataHandler): Promise<void>;
+    setPageDataHandler(handler: TPageDataHandler<TRow>): Promise<void>;
     loadPageData(options?: {
         disableCache?: boolean;
         signal?: AbortSignal;
@@ -363,12 +426,14 @@ declare class CFlatServerDataProvider extends ADataProvider {
     refresh(hardRefresh?: boolean): Promise<void>;
 }
 
-declare class CAPIFlatServerDataProvider extends CFlatServerDataProvider implements AAPIDataProvider {
+declare class CAPIFlatServerDataProvider<TRow = TDataRow> extends CFlatServerDataProvider<TRow> implements AAPIDataProvider {
     apiUrl: string;
     requestProvider: RequestProvider;
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    /** Incremented on every new request; stale onDataReceived callbacks are discarded. */
+    private _requestGeneration;
     constructor(options?: IDataProviderOptions);
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
@@ -380,7 +445,7 @@ declare class CAPIFlatServerDataProvider extends CFlatServerDataProvider impleme
     update(item: any): Promise<void>;
 }
 
-declare class CTreeClientDataProvider extends CFlatClientDataProvider {
+declare class CTreeClientDataProvider<TRow extends TDataRow = TDataRow> extends CFlatClientDataProvider<TRow> implements ITreeDataProvider<TRow> {
     parentKey: string;
     idKey: string;
     expandedByDefault: boolean;
@@ -389,22 +454,24 @@ declare class CTreeClientDataProvider extends CFlatClientDataProvider {
     private _staticNodesCache;
     private _nodeMapCache;
     private _sortedNodeIdsCache;
+    private _filteredNodesCache;
     invalidateStaticCache(): void;
+    setFilter(filter: IDataFilter | null, immediate?: boolean): void;
     private get _staticNodes();
     private get _nodeMap();
     private get _sortedNodeIds();
     constructor(options?: ITreeDataProviderOptions);
-    setData(data: TDataRow[]): void;
+    setData(data: TRow[]): void;
     private buildStaticNodes;
     private computeSortedIds;
     private isNodeVisible;
     private paginateNodes;
     private updatePageData;
     loadPageData(): Promise<void>;
-    get treeNodes(): ITreeNode[];
-    get visibleRows(): ITreeNode[];
-    getAllNodes(): ITreeNode[];
-    getFlatNodes(): ITreeNode[];
+    get treeNodes(): ITreeNode<TRow>[];
+    get visibleRows(): ITreeNode<TRow>[];
+    getAllNodes(): ITreeNode<TRow>[];
+    getFlatNodes(): ITreeNode<TRow>[];
     toggleNode(nodeId: string | number): void;
     expand(nodeId: string | number): void;
     collapse(nodeId: string | number): void;
@@ -412,12 +479,12 @@ declare class CTreeClientDataProvider extends CFlatClientDataProvider {
     collapseNode(nodeId: string | number): void;
     expandAll(): void;
     collapseAll(): void;
-    getNode(nodeId: string | number): ITreeNode | undefined;
-    getChildren(nodeId: string | number): ITreeNode[];
-    getParent(nodeId: string | number): ITreeNode | undefined;
+    getNode(nodeId: string | number): ITreeNode<TRow> | undefined;
+    getChildren(nodeId: string | number): ITreeNode<TRow>[];
+    getParent(nodeId: string | number): ITreeNode<TRow> | undefined;
 }
 
-declare class CAPITreeClientDataProvider extends CTreeClientDataProvider implements AAPIDataProvider {
+declare class CAPITreeClientDataProvider<TRow extends TDataRow = TDataRow> extends CTreeClientDataProvider<TRow> implements AAPIDataProvider {
     apiUrl: string;
     contextKey: string;
     requestProvider: RequestProvider;
@@ -446,17 +513,17 @@ declare class CAPITreeClientDataProvider extends CTreeClientDataProvider impleme
  * - Server returns already-paginated visible rows with __treeNode metadata
  * - No allData - server handles everything
  */
-declare class CTreeServerDataProvider extends ADataProvider {
+declare class CTreeServerDataProvider<TRow = TDataRow> extends ADataProvider<TRow> implements ITreeDataProvider<TRow> {
     parentKey: string;
     idKey: string;
     expandedByDefault: boolean;
     paginateBy: TreePaginationMode;
     expandedNodes: Set<string | number>;
-    pageDataHandler: TTreePageDataHandler | null;
+    pageDataHandler: TTreePageDataHandler<TRow> | null;
     contextKey: string;
     constructor(options?: ITreeDataProviderOptions);
     setContextKey(key: string): void;
-    setPageDataHandler(handler: TTreePageDataHandler): Promise<void>;
+    setPageDataHandler(handler: TTreePageDataHandler<TRow>): Promise<void>;
     private latestRequestId;
     private abortController;
     /**
@@ -483,12 +550,14 @@ declare class CTreeServerDataProvider extends ADataProvider {
  * - Request management (caching, deduplication)
  * - Automatic tree parameter serialization in query
  */
-declare class CAPITreeServerDataProvider extends CTreeServerDataProvider implements AAPIDataProvider {
+declare class CAPITreeServerDataProvider<TRow = TDataRow> extends CTreeServerDataProvider<TRow> implements AAPIDataProvider {
     apiUrl: string;
     requestProvider: RequestProvider;
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    /** Incremented on every new request; stale onDataReceived callbacks are discarded. */
+    private _requestGeneration;
     constructor(options?: ITreeDataProviderOptions);
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
@@ -525,6 +594,7 @@ declare class KatluxIndexedDB {
      * Safe to call multiple times — always resolves to the same instance.
      */
     static open(): Promise<IDBDatabase>;
+    private static upgradeToVersion;
     /**
      * Dynamically ensures that an object store exists in the database.
      * If not present, performs a database version bump and creates the store.
@@ -569,15 +639,18 @@ declare class CacheProviderFactory {
     static clearInstances(): void;
 }
 
-declare class CSessionCache extends ACacheProvider {
+declare class CServerSessionCache extends ACacheProvider {
     private static instance;
-    static getInstance(): CSessionCache;
+    static getInstance(): CServerSessionCache;
     static get storage(): Map<string, Map<string, ICacheEntry<any>>>;
     static getSnapshot(): Map<string, Map<string, ICacheEntry<any>>>;
-    private static cleanupTimer;
-    private static initCleanupTimer;
+    static MAX_SERVER_SESSIONS: number;
+    /**
+     * Purges expired entries across all server sessions synchronously when the storage
+     * exceeds MAX_SERVER_SESSIONS. Avoids persistent background setInterval timers on Node.js/SSR.
+     */
+    static purgeExpiredServerSessions(): void;
     private sessionIdCache;
-    private sessionId;
     private readonly SESSION_ID_KEY;
     constructor();
     /**
@@ -585,18 +658,43 @@ declare class CSessionCache extends ACacheProvider {
      */
     private generateSessionId;
     /**
-     * Get or create sessionId
+     * Get or create sessionId — server-only path.
+     * Returns '__no_session__' sentinel when no isolatable H3 event context is available.
      */
     private getSessionId;
-    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>;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
 
+/**
+ * CBrowserSessionCache — client-side tab-lifetime cache backed by window.sessionStorage.
+ *
+ * - Server-side: all write operations store only into the SSR context payload for hydration
+ *   transfer to the client. No server memory is allocated.
+ * - Client-side: reads and writes use window.sessionStorage exclusively.
+ * - Hydration: on the first client-side get() miss, checks the SSR payload and promotes
+ *   the entry into sessionStorage for subsequent reads.
+ *
+ * Storage key prefix: 'bscache:' (distinct from the server session 'cache:' prefix)
+ */
+declare class CBrowserSessionCache extends ACacheProvider {
+    private static instance;
+    static getInstance(): CBrowserSessionCache;
+    private readonly PREFIX;
+    getKeyList(_context?: any): Promise<string[]>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, _context?: any): Promise<void>;
+    removeByPrefix(prefix: string, _context?: any): Promise<void>;
+    getRemainingTime(key: string, _context?: any): Promise<number | null>;
+    cleanupExpired(_context?: any): Promise<void>;
+}
+
 declare class CCookieCache extends ACacheProvider {
     private static instance;
     static getInstance(): CCookieCache;
@@ -605,12 +703,12 @@ declare class CCookieCache extends ACacheProvider {
     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>;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
 
@@ -620,27 +718,29 @@ declare class CLocalStorageCache extends ACacheProvider {
     type: string;
     private constructor();
     private _hydrateFromPayload;
-    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>;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
 
 declare class CIndexedDBCache extends ACacheProvider {
     private static instance;
-    static getInstance(): CIndexedDBCache;
-    private constructor();
+    private static instances;
+    readonly storeName: string;
+    static getInstance(storeName?: string): CIndexedDBCache;
+    constructor(storeName?: string);
     private _hydrateFromPayload;
     private getStore;
-    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>;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
 
@@ -651,12 +751,13 @@ declare class CMemoryCache extends ACacheProvider {
     static getInstance(): CMemoryCache;
     private constructor();
     private _hydrateFromPayload;
-    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>;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    private isServer;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
     cleanupExpired(): Promise<void>;
 }
 
@@ -665,15 +766,26 @@ declare class CApplicationCache extends ACacheProvider {
     private static _storage;
     private static get storage();
     static getInstance(): CApplicationCache;
+    static readonly MAX_ENTRIES = 10000;
     static getSnapshot(): Map<string, ICacheEntry<any>>;
+    /**
+     * Purges expired entries when storage size reaches MAX_ENTRIES watermark.
+     * Avoids persistent background setInterval timers on Node.js/SSR.
+     */
+    static purgeExpiredEntries(): void;
+    /**
+     * Clears all cached entries (used for test isolation).
+     */
+    static clear(): void;
     private constructor();
-    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>;
+    private isServer;
+    getKeyList(context?: any): Promise<Array<string>>;
+    get<T>(key: string, context?: any): Promise<T | null>;
+    set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
+    remove(key: string, context?: any): Promise<void>;
+    removeByPrefix(prefix: string, context?: any): Promise<void>;
+    getRemainingTime(key: string, context?: any): Promise<number | null>;
+    cleanupExpired(context?: any): Promise<void>;
 }
 
 interface IRegistryEntry {
@@ -707,6 +819,8 @@ declare class RequestProviderRegistry {
     /**
      * Register a provider with one or more tags.
      * If the provider is already registered, its tags are updated.
+     * In SSR (Node.js), registration is skipped to prevent process-global memory leaks
+     * and cross-user multi-tenant invalidation.
      */
     static register(provider: RequestProvider, tags: string[]): void;
     /**
@@ -738,6 +852,7 @@ declare class RequestProviderRegistry {
     static clear(): void;
 }
 
+declare const SENSITIVE_HEADER_KEYS: string[];
 /**
  * RequestQueue
  *
@@ -766,11 +881,25 @@ declare class RequestQueue {
     static queue: IQueuedOperation[];
     static deadLetterQueue: IDeadLetterItem[];
     static isFlushing: boolean;
+    private static MAX_PAYLOAD_SIZE_BYTES;
+    private static MAX_QUEUE_SIZE;
+    private static MAX_DEAD_LETTER_SIZE;
+    static setMaxPayloadSize(bytes: number): void;
+    static setMaxQueueSize(limit: number): void;
+    static setMaxDeadLetterSize(limit: number): void;
+    /**
+     * Strips sensitive headers (e.g., authorization, cookie, x-csrf-token) before persisting
+     * request options to persistent storage (IndexedDB / LocalStorage).
+     * Sensitive credentials must never be stored in plaintext in browser storage, and are
+     * instead regenerated dynamically at execution time.
+     */
+    private static sanitizeOptions;
     private static _subscribers;
     static subscribe(listener: () => void): () => void;
     static notify(): void;
     private static adapter;
     private static initialized;
+    private static initPromise;
     private static _onDeadLetter;
     private static _onFlushComplete;
     private static _onNetworkError;
@@ -820,6 +949,7 @@ declare class RequestQueue {
      * Fully permissive — causal ordering is the app's responsibility.
      */
     static reorder(ids: string[]): void;
+    private static regenerateHeaders;
     private static executeRequest;
     private static moveToDeadLetter;
     private static persistQueue;
@@ -895,11 +1025,12 @@ 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);
+interface IDebouncedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+}
+declare const useDebounce: <T extends (...args: any[]) => any>(callback: T, delay: number) => IDebouncedFunction<T>;
+declare const debounce: <T extends (...args: any[]) => any>(callback: T, delay: number) => IDebouncedFunction<T>;
 
 /**
  * defaultAdapter.ts — Framework-agnostic default implementation of ISSRHydrationAdapter.
@@ -913,19 +1044,6 @@ declare class DefaultHydrationAdapter implements ISSRHydrationAdapter {
     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.
@@ -969,5 +1087,5 @@ declare function getAppRouter(): any;
  */
 declare function onPlatformReady(cb: () => void): void;
 
-export { AAPIDataProvider, ADataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CCookieCache, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CLocalStorageCache, CMemoryCache, CSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CacheProviderFactory, 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, 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 };
+export { AAPIDataProvider, ADataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CBrowserSessionCache, CCookieCache, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CLocalStorageCache, CMemoryCache, CServerSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CacheProviderFactory, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, SENSITIVE_HEADER_KEYS, applyOperator, clearSSRData, compareAnd, compareEqual, compareIn, compareOr, compareValues, debounce, evaluateFilter, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getHydrationAdapter, getPlatformApp, getSSRData, getSSRPayload, onPlatformReady, setHydrationAdapter, sortData, useDebounce, useFilterLogic, useSortLogic };
+export type { CacheDriverLoader, ICacheEntry, IDataFilter, IDataProviderOptions, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IFlushOptions, IKDatatableAction, IPlatformRouter, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, KProductItemData, KProductRowAction, TDataProviderListener, TDataRow, TKatluxStore, TPageDataHandler, TQueueItemStatus, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };