api-core-lib 12.0.12 → 12.0.14

package/dist/{apiModule.types-CpwGDEpG.d.cts → apiModule.types-Cvp9QdAc.d.cts}

@@ -228,6 +228,7 @@ interface ExecuteOptions<TInput, TOutput, TContext = unknown> {
     onMutate?: (variables: TInput) => TContext | Promise<TContext>;
     onSuccess?: (data: TOutput, context?: TContext) => void;
     onError?: (error: ApiError, context?: TContext) => void;
+    onSettled?: (data?: TOutput, error?: ApiError, context?: TContext) => void;
 }
 /** @description A fully-typed object representing the callable actions for a module. */
 type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>> = {
@@ -254,4 +255,4 @@ interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<
     dehydrate: () => string;
 }
 
-export type { ActionConfigModule as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ApiModuleConfig as a, UseApiModuleOptions as b, UseApiModuleReturn as c, ApiClientConfig as d, ActionOptions as e, ActionStateModule as f, UseApiQuery as g, ApiError as h, TokenManager as i, Middleware as j, RefreshTokenConfig as k, ActionConfig as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };
+export type { ActionConfigModule as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ApiModuleConfig as a, UseApiModuleOptions as b, UseApiModuleReturn as c, ApiClientConfig as d, ActionOptions as e, UseApiQuery as f, ApiError as g, TokenManager as h, Middleware as i, RefreshTokenConfig as j, ActionConfig as k, ActionStateModule as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };

package/dist/{apiModule.types-CpwGDEpG.d.ts → apiModule.types-Cvp9QdAc.d.ts}

@@ -228,6 +228,7 @@ interface ExecuteOptions<TInput, TOutput, TContext = unknown> {
     onMutate?: (variables: TInput) => TContext | Promise<TContext>;
     onSuccess?: (data: TOutput, context?: TContext) => void;
     onError?: (error: ApiError, context?: TContext) => void;
+    onSettled?: (data?: TOutput, error?: ApiError, context?: TContext) => void;
 }
 /** @description A fully-typed object representing the callable actions for a module. */
 type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>> = {
@@ -254,4 +255,4 @@ interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<
     dehydrate: () => string;
 }
 
-export type { ActionConfigModule as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ApiModuleConfig as a, UseApiModuleOptions as b, UseApiModuleReturn as c, ApiClientConfig as d, ActionOptions as e, ActionStateModule as f, UseApiQuery as g, ApiError as h, TokenManager as i, Middleware as j, RefreshTokenConfig as k, ActionConfig as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };
+export type { ActionConfigModule as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ApiModuleConfig as a, UseApiModuleOptions as b, UseApiModuleReturn as c, ApiClientConfig as d, ActionOptions as e, UseApiQuery as f, ApiError as g, TokenManager as h, Middleware as i, RefreshTokenConfig as j, ActionConfig as k, ActionStateModule as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };

package/dist/{useApiRecord.types-B45E0qux.d.cts → cacheKey-BJQaehcQ.d.ts}

@@ -1,5 +1,5 @@
 import { Dispatch, SetStateAction } from 'react';
-import { R as RequestConfig, h as ApiError, S as StandardResponse, e as ActionOptions } from './apiModule.types-CpwGDEpG.cjs';
+import { R as RequestConfig, g as ApiError, S as StandardResponse, e as ActionOptions, l as ActionStateModule } from './apiModule.types-Cvp9QdAc.js';
 
 /**
  * Represents the internal state of the `useApiRecord` hook.
@@ -87,4 +87,54 @@ interface UseApiRecordReturn<T> {
     setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
 }
 
-export type { UseApiRecordConfig as U, UseApiRecordReturn as a, UseApiRecordState as b, UseApiRecordActions as c };
+declare class GlobalStateManager {
+    private store;
+    getSnapshot<T>(key: string): ActionStateModule<T>;
+    /**
+     * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
+     * @returns دالة لإلغاء الاشتراك.
+     */
+    subscribe(key: string, callback: () => void): () => void;
+    /**
+     * يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
+     */
+    setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
+    /**
+     * يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
+     */
+    invalidate(key: string): void;
+    /**
+   * [نسخة محدثة وأكثر قوة]
+   * يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
+   * @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
+   */
+    invalidateByPrefix(prefix: string): void;
+    /**
+   * Serializes the current state of the query store into a JSON string.
+   * This is used on the server to pass the initial state to the client.
+   * @returns A JSON string representing the dehydrated state.
+   */
+    dehydrate(): string;
+    /**
+     * Merges a dehydrated state object into the current store.
+     * This is used on the client to hydrate the state received from the server.
+     * @param hydratedState - A JSON string from the `dehydrate` method.
+     */
+    rehydrate(hydratedState: string): void;
+}
+declare const globalStateManager: GlobalStateManager;
+
+/**
+ * يقوم بإنشاء مفتاح تخزين مؤقت فريد وثابت لإجراء معين ومدخلاته.
+ * هذا يضمن أن نفس الطلب ينتج دائمًا نفس المفتاح.
+ * @param moduleName - عادةً ما يكون `baseEndpoint` للموديول.
+ * @param actionName - اسم الإجراء (مثل 'list', 'create').
+ * @param input - بيانات الطلب (body/query params).
+ * @param callOptions - خيارات إضافية مثل `pathParams`.
+ * @returns سلسلة نصية فريدة تمثل مفتاح التخزين المؤقت.
+ */
+declare const generateCacheKey: (moduleName: string, actionName: string, input?: unknown, callOptions?: {
+    pathParams?: Record<string, any>;
+}) => string;
+
+export { type UseApiRecordConfig as U, type UseApiRecordReturn as a, generateCacheKey as b, type UseApiRecordState as c, type UseApiRecordActions as d, globalStateManager as g };

package/dist/{useApiRecord.types-DlrlXL1t.d.ts → cacheKey-BNQ1ii6y.d.cts}

@@ -1,5 +1,5 @@
 import { Dispatch, SetStateAction } from 'react';
-import { R as RequestConfig, h as ApiError, S as StandardResponse, e as ActionOptions } from './apiModule.types-CpwGDEpG.js';
+import { R as RequestConfig, g as ApiError, S as StandardResponse, e as ActionOptions, l as ActionStateModule } from './apiModule.types-Cvp9QdAc.cjs';
 
 /**
  * Represents the internal state of the `useApiRecord` hook.
@@ -87,4 +87,54 @@ interface UseApiRecordReturn<T> {
     setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
 }
 
-export type { UseApiRecordConfig as U, UseApiRecordReturn as a, UseApiRecordState as b, UseApiRecordActions as c };
+declare class GlobalStateManager {
+    private store;
+    getSnapshot<T>(key: string): ActionStateModule<T>;
+    /**
+     * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
+     * @returns دالة لإلغاء الاشتراك.
+     */
+    subscribe(key: string, callback: () => void): () => void;
+    /**
+     * يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
+     */
+    setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
+    /**
+     * يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
+     */
+    invalidate(key: string): void;
+    /**
+   * [نسخة محدثة وأكثر قوة]
+   * يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
+   * @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
+   */
+    invalidateByPrefix(prefix: string): void;
+    /**
+   * Serializes the current state of the query store into a JSON string.
+   * This is used on the server to pass the initial state to the client.
+   * @returns A JSON string representing the dehydrated state.
+   */
+    dehydrate(): string;
+    /**
+     * Merges a dehydrated state object into the current store.
+     * This is used on the client to hydrate the state received from the server.
+     * @param hydratedState - A JSON string from the `dehydrate` method.
+     */
+    rehydrate(hydratedState: string): void;
+}
+declare const globalStateManager: GlobalStateManager;
+
+/**
+ * يقوم بإنشاء مفتاح تخزين مؤقت فريد وثابت لإجراء معين ومدخلاته.
+ * هذا يضمن أن نفس الطلب ينتج دائمًا نفس المفتاح.
+ * @param moduleName - عادةً ما يكون `baseEndpoint` للموديول.
+ * @param actionName - اسم الإجراء (مثل 'list', 'create').
+ * @param input - بيانات الطلب (body/query params).
+ * @param callOptions - خيارات إضافية مثل `pathParams`.
+ * @returns سلسلة نصية فريدة تمثل مفتاح التخزين المؤقت.
+ */
+declare const generateCacheKey: (moduleName: string, actionName: string, input?: unknown, callOptions?: {
+    pathParams?: Record<string, any>;
+}) => string;
+
+export { type UseApiRecordConfig as U, type UseApiRecordReturn as a, generateCacheKey as b, type UseApiRecordState as c, type UseApiRecordActions as d, globalStateManager as g };

package/dist/client.cjs

@@ -34,6 +34,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var client_exports = {};
 __export(client_exports, {
   ApiModuleProvider: () => ApiModuleProvider,
+  generateCacheKey: () => generateCacheKey,
+  globalStateManager: () => globalStateManager,
   useApi: () => useApi,
   useApiModule: () => useApiModule,
   useApiRecord: () => useApiRecord,
@@ -586,11 +588,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -679,9 +683,14 @@ var globalStateManager = new GlobalStateManager();
 var ApiModuleContext = (0, import_react4.createContext)(null);
 var ApiModuleProvider = ApiModuleContext.Provider;
 function useApiActionState(actionConfig, cacheKey, actionExecutor, enabled) {
+  const getClientSnapshot = () => globalStateManager.getSnapshot(cacheKey);
+  const getServerSnapshot = () => globalStateManager.getSnapshot(cacheKey);
   const state = (0, import_react4.useSyncExternalStore)(
     (callback) => globalStateManager.subscribe(cacheKey, callback),
-    () => globalStateManager.getSnapshot(cacheKey)
+    getClientSnapshot,
+    // لقطة العميل
+    getServerSnapshot
+    // لقطة الخادم
   );
   const input = actionConfig.hasQuery ? state.options : void 0;
   (0, import_react4.useEffect)(() => {
@@ -690,7 +699,7 @@ function useApiActionState(actionConfig, cacheKey, actionExecutor, enabled) {
     } else if (enabled && state.isStale && !state.loading) {
       actionExecutor(input);
     }
-  }, [enabled, state.isStale, state.loading, state.called, actionConfig.autoFetch, actionExecutor, input]);
+  }, [enabled, state.isStale, state.loading, state.called, actionConfig.autoFetch, actionExecutor, JSON.stringify(input)]);
   return state;
 }
 function useModuleContext() {
@@ -700,14 +709,6 @@ function useModuleContext() {
   }
   return context;
 }
-var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
-  const params = { path: callOptions.pathParams, body: input };
-  try {
-    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
-  } catch (error) {
-    return `${moduleName}/${actionName}::${Date.now()}`;
-  }
-};
 function useApiModule(axiosInstance, moduleConfig, options = {}) {
   const { refetchOnWindowFocus = true, onSuccess, onError, pathParams: modulePathParams, enabled = true, hydratedState } = options;
   const pathParamsString = (0, import_react4.useMemo)(() => JSON.stringify(modulePathParams || {}), [modulePathParams]);
@@ -758,6 +759,10 @@ function useApiModule(axiosInstance, moduleConfig, options = {}) {
           savedCallbacks.current.onError?.(actionName, apiError.message, apiError);
           options2.onError?.(apiError, mutationContext);
           return errorResult;
+        } finally {
+          if (options2.onSettled) {
+            options2.onSettled();
+          }
         }
       };
       const reset = (input, options2 = {}) => {
@@ -858,9 +863,83 @@ function useApiModule(axiosInstance, moduleConfig, options = {}) {
   }, []);
   return { actions, states, queries, dehydrate };
 }
+
+// src/core/client.ts
+var import_axios3 = __toESM(require("axios"), 1);
+var import_uuid = require("uuid");
+
+// src/core/cache.ts
+var CacheManager = class {
+  constructor() {
+    __publicField(this, "cache", /* @__PURE__ */ new Map());
+    __publicField(this, "defaultDuration", 15 * 60 * 1e3);
+  }
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  /**
+   * [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
+   * الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
+   */
+  getWithMeta(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  invalidateByPrefix(prefix) {
+    const keysToDelete = [];
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+    keysToDelete.forEach((key) => this.cache.delete(key));
+    console.log(`Invalidated ${keysToDelete.length} cache entries with prefix: ${prefix}`);
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
+var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
+  const params = { path: callOptions.pathParams, body: input };
+  try {
+    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
+  } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
+    return `${moduleName}/${actionName}::${Date.now()}`;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiModuleProvider,
+  generateCacheKey,
+  globalStateManager,
   useApi,
   useApiModule,
   useApiRecord,

package/dist/client.d.cts

@@ -1,6 +1,7 @@
 import { AxiosInstance } from 'axios';
-import { U as UseApiConfig, A as ActionConfigModule, a as ApiModuleConfig, b as UseApiModuleOptions, c as UseApiModuleReturn } from './apiModule.types-CpwGDEpG.cjs';
-import { U as UseApiRecordConfig, a as UseApiRecordReturn } from './useApiRecord.types-B45E0qux.cjs';
+import { U as UseApiConfig, A as ActionConfigModule, a as ApiModuleConfig, b as UseApiModuleOptions, c as UseApiModuleReturn } from './apiModule.types-Cvp9QdAc.cjs';
+import { U as UseApiRecordConfig, a as UseApiRecordReturn } from './cacheKey-BNQ1ii6y.cjs';
+export { b as generateCacheKey, g as globalStateManager } from './cacheKey-BNQ1ii6y.cjs';
 import * as React from 'react';
 
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): any;

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { AxiosInstance } from 'axios';
-import { U as UseApiConfig, A as ActionConfigModule, a as ApiModuleConfig, b as UseApiModuleOptions, c as UseApiModuleReturn } from './apiModule.types-CpwGDEpG.js';
-import { U as UseApiRecordConfig, a as UseApiRecordReturn } from './useApiRecord.types-DlrlXL1t.js';
+import { U as UseApiConfig, A as ActionConfigModule, a as ApiModuleConfig, b as UseApiModuleOptions, c as UseApiModuleReturn } from './apiModule.types-Cvp9QdAc.js';
+import { U as UseApiRecordConfig, a as UseApiRecordReturn } from './cacheKey-BJQaehcQ.js';
+export { b as generateCacheKey, g as globalStateManager } from './cacheKey-BJQaehcQ.js';
 import * as React from 'react';
 
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): any;

package/dist/client.js

@@ -547,11 +547,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -640,9 +642,14 @@ var globalStateManager = new GlobalStateManager();
 var ApiModuleContext = createContext(null);
 var ApiModuleProvider = ApiModuleContext.Provider;
 function useApiActionState(actionConfig, cacheKey, actionExecutor, enabled) {
+  const getClientSnapshot = () => globalStateManager.getSnapshot(cacheKey);
+  const getServerSnapshot = () => globalStateManager.getSnapshot(cacheKey);
   const state = useSyncExternalStore(
     (callback) => globalStateManager.subscribe(cacheKey, callback),
-    () => globalStateManager.getSnapshot(cacheKey)
+    getClientSnapshot,
+    // لقطة العميل
+    getServerSnapshot
+    // لقطة الخادم
   );
   const input = actionConfig.hasQuery ? state.options : void 0;
   useEffect4(() => {
@@ -651,7 +658,7 @@ function useApiActionState(actionConfig, cacheKey, actionExecutor, enabled) {
     } else if (enabled && state.isStale && !state.loading) {
       actionExecutor(input);
     }
-  }, [enabled, state.isStale, state.loading, state.called, actionConfig.autoFetch, actionExecutor, input]);
+  }, [enabled, state.isStale, state.loading, state.called, actionConfig.autoFetch, actionExecutor, JSON.stringify(input)]);
   return state;
 }
 function useModuleContext() {
@@ -661,14 +668,6 @@ function useModuleContext() {
   }
   return context;
 }
-var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
-  const params = { path: callOptions.pathParams, body: input };
-  try {
-    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
-  } catch (error) {
-    return `${moduleName}/${actionName}::${Date.now()}`;
-  }
-};
 function useApiModule(axiosInstance, moduleConfig, options = {}) {
   const { refetchOnWindowFocus = true, onSuccess, onError, pathParams: modulePathParams, enabled = true, hydratedState } = options;
   const pathParamsString = useMemo3(() => JSON.stringify(modulePathParams || {}), [modulePathParams]);
@@ -719,6 +718,10 @@ function useApiModule(axiosInstance, moduleConfig, options = {}) {
           savedCallbacks.current.onError?.(actionName, apiError.message, apiError);
           options2.onError?.(apiError, mutationContext);
           return errorResult;
+        } finally {
+          if (options2.onSettled) {
+            options2.onSettled();
+          }
         }
       };
       const reset = (input, options2 = {}) => {
@@ -819,8 +822,82 @@ function useApiModule(axiosInstance, moduleConfig, options = {}) {
   }, []);
   return { actions, states, queries, dehydrate };
 }
+
+// src/core/client.ts
+import axios3 from "axios";
+import { v4 as uuidv4 } from "uuid";
+
+// src/core/cache.ts
+var CacheManager = class {
+  constructor() {
+    __publicField(this, "cache", /* @__PURE__ */ new Map());
+    __publicField(this, "defaultDuration", 15 * 60 * 1e3);
+  }
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  /**
+   * [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
+   * الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
+   */
+  getWithMeta(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  invalidateByPrefix(prefix) {
+    const keysToDelete = [];
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+    keysToDelete.forEach((key) => this.cache.delete(key));
+    console.log(`Invalidated ${keysToDelete.length} cache entries with prefix: ${prefix}`);
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
+var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
+  const params = { path: callOptions.pathParams, body: input };
+  try {
+    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
+  } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
+    return `${moduleName}/${actionName}::${Date.now()}`;
+  }
+};
 export {
   ApiModuleProvider,
+  generateCacheKey,
+  globalStateManager,
   useApi,
   useApiModule,
   useApiRecord,

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   createApiActions: () => createApiActions,
   createApiClient: () => createApiClient,
   createApiServices: () => createApiServices,
+  generateCacheKey: () => generateCacheKey,
   globalStateManager: () => globalStateManager,
   processResponse: () => processResponse
 });
@@ -543,11 +544,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -688,6 +691,17 @@ var CacheManager = class {
   }
 };
 var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
+var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
+  const params = { path: callOptions.pathParams, body: input };
+  try {
+    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
+  } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
+    return `${moduleName}/${actionName}::${Date.now()}`;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   buildPaginateQuery,
@@ -696,6 +710,7 @@ var cacheManager = new CacheManager();
   createApiActions,
   createApiClient,
   createApiServices,
+  generateCacheKey,
   globalStateManager,
   processResponse
 });

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { AxiosInstance, AxiosRequestConfig, Method, AxiosResponse, AxiosError } from 'axios';
-import { d as ApiClientConfig, A as ActionConfigModule, S as StandardResponse, e as ActionOptions, R as RequestConfig, f as ActionStateModule, Q as QueryOptions, g as UseApiQuery, h as ApiError, L as LogLevel } from './apiModule.types-CpwGDEpG.cjs';
-export { l as ActionConfig, n as ActionState, a as ApiModuleConfig, E as ExecutableAction, o as ExecuteOptions, I as InputOf, j as Middleware, M as MiddlewareContext, p as ModuleActions, q as ModuleStates, O as OutputOf, P as PaginationMeta, k as RefreshTokenConfig, i as TokenManager, T as Tokens, U as UseApiConfig, b as UseApiModuleOptions, c as UseApiModuleReturn, m as UseApiState, V as ValidationError } from './apiModule.types-CpwGDEpG.cjs';
-export { c as UseApiRecordActions, U as UseApiRecordConfig, a as UseApiRecordReturn, b as UseApiRecordState } from './useApiRecord.types-B45E0qux.cjs';
+import { d as ApiClientConfig, A as ActionConfigModule, S as StandardResponse, e as ActionOptions, R as RequestConfig, Q as QueryOptions, f as UseApiQuery, g as ApiError, L as LogLevel } from './apiModule.types-Cvp9QdAc.cjs';
+export { k as ActionConfig, n as ActionState, l as ActionStateModule, a as ApiModuleConfig, E as ExecutableAction, o as ExecuteOptions, I as InputOf, i as Middleware, M as MiddlewareContext, p as ModuleActions, q as ModuleStates, O as OutputOf, P as PaginationMeta, j as RefreshTokenConfig, h as TokenManager, T as Tokens, U as UseApiConfig, b as UseApiModuleOptions, c as UseApiModuleReturn, m as UseApiState, V as ValidationError } from './apiModule.types-Cvp9QdAc.cjs';
+export { d as UseApiRecordActions, U as UseApiRecordConfig, a as UseApiRecordReturn, c as UseApiRecordState, b as generateCacheKey, g as globalStateManager } from './cacheKey-BNQ1ii6y.cjs';
 import 'react';
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
@@ -72,46 +72,6 @@ declare function createApiActions<TActions extends Record<string, {
     [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
 };
 
-declare class GlobalStateManager {
-    private store;
-    /**
-     * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-     */
-    getSnapshot<T>(key: string): ActionStateModule<T>;
-    /**
-     * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
-     * @returns دالة لإلغاء الاشتراك.
-     */
-    subscribe(key: string, callback: () => void): () => void;
-    /**
-     * يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
-     */
-    setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
-    /**
-     * يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
-     */
-    invalidate(key: string): void;
-    /**
-   * [نسخة محدثة وأكثر قوة]
-   * يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
-   * @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
-   */
-    invalidateByPrefix(prefix: string): void;
-    /**
-   * Serializes the current state of the query store into a JSON string.
-   * This is used on the server to pass the initial state to the client.
-   * @returns A JSON string representing the dehydrated state.
-   */
-    dehydrate(): string;
-    /**
-     * Merges a dehydrated state object into the current store.
-     * This is used on the client to hydrate the state received from the server.
-     * @param hydratedState - A JSON string from the `dehydrate` method.
-     */
-    rehydrate(hydratedState: string): void;
-}
-declare const globalStateManager: GlobalStateManager;
-
 /**
  * [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
  * يدعم الآن الفلاتر المتداخلة (filter[key]=value) والترتيب المتعدد.
@@ -228,4 +188,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { ActionConfigModule, ActionOptions, ActionStateModule, ApiClientConfig, ApiError, type ApiResourceStatus, LogLevel, QueryOptions, RequestConfig, StandardResponse, type UseApiActions, UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse };
+export { ActionConfigModule, ActionOptions, ApiClientConfig, ApiError, type ApiResourceStatus, LogLevel, QueryOptions, RequestConfig, StandardResponse, type UseApiActions, UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, processResponse };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { AxiosInstance, AxiosRequestConfig, Method, AxiosResponse, AxiosError } from 'axios';
-import { d as ApiClientConfig, A as ActionConfigModule, S as StandardResponse, e as ActionOptions, R as RequestConfig, f as ActionStateModule, Q as QueryOptions, g as UseApiQuery, h as ApiError, L as LogLevel } from './apiModule.types-CpwGDEpG.js';
-export { l as ActionConfig, n as ActionState, a as ApiModuleConfig, E as ExecutableAction, o as ExecuteOptions, I as InputOf, j as Middleware, M as MiddlewareContext, p as ModuleActions, q as ModuleStates, O as OutputOf, P as PaginationMeta, k as RefreshTokenConfig, i as TokenManager, T as Tokens, U as UseApiConfig, b as UseApiModuleOptions, c as UseApiModuleReturn, m as UseApiState, V as ValidationError } from './apiModule.types-CpwGDEpG.js';
-export { c as UseApiRecordActions, U as UseApiRecordConfig, a as UseApiRecordReturn, b as UseApiRecordState } from './useApiRecord.types-DlrlXL1t.js';
+import { d as ApiClientConfig, A as ActionConfigModule, S as StandardResponse, e as ActionOptions, R as RequestConfig, Q as QueryOptions, f as UseApiQuery, g as ApiError, L as LogLevel } from './apiModule.types-Cvp9QdAc.js';
+export { k as ActionConfig, n as ActionState, l as ActionStateModule, a as ApiModuleConfig, E as ExecutableAction, o as ExecuteOptions, I as InputOf, i as Middleware, M as MiddlewareContext, p as ModuleActions, q as ModuleStates, O as OutputOf, P as PaginationMeta, j as RefreshTokenConfig, h as TokenManager, T as Tokens, U as UseApiConfig, b as UseApiModuleOptions, c as UseApiModuleReturn, m as UseApiState, V as ValidationError } from './apiModule.types-Cvp9QdAc.js';
+export { d as UseApiRecordActions, U as UseApiRecordConfig, a as UseApiRecordReturn, c as UseApiRecordState, b as generateCacheKey, g as globalStateManager } from './cacheKey-BJQaehcQ.js';
 import 'react';
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
@@ -72,46 +72,6 @@ declare function createApiActions<TActions extends Record<string, {
     [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
 };
 
-declare class GlobalStateManager {
-    private store;
-    /**
-     * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-     */
-    getSnapshot<T>(key: string): ActionStateModule<T>;
-    /**
-     * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
-     * @returns دالة لإلغاء الاشتراك.
-     */
-    subscribe(key: string, callback: () => void): () => void;
-    /**
-     * يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
-     */
-    setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
-    /**
-     * يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
-     */
-    invalidate(key: string): void;
-    /**
-   * [نسخة محدثة وأكثر قوة]
-   * يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
-   * @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
-   */
-    invalidateByPrefix(prefix: string): void;
-    /**
-   * Serializes the current state of the query store into a JSON string.
-   * This is used on the server to pass the initial state to the client.
-   * @returns A JSON string representing the dehydrated state.
-   */
-    dehydrate(): string;
-    /**
-     * Merges a dehydrated state object into the current store.
-     * This is used on the client to hydrate the state received from the server.
-     * @param hydratedState - A JSON string from the `dehydrate` method.
-     */
-    rehydrate(hydratedState: string): void;
-}
-declare const globalStateManager: GlobalStateManager;
-
 /**
  * [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
  * يدعم الآن الفلاتر المتداخلة (filter[key]=value) والترتيب المتعدد.
@@ -228,4 +188,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { ActionConfigModule, ActionOptions, ActionStateModule, ApiClientConfig, ApiError, type ApiResourceStatus, LogLevel, QueryOptions, RequestConfig, StandardResponse, type UseApiActions, UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse };
+export { ActionConfigModule, ActionOptions, ApiClientConfig, ApiError, type ApiResourceStatus, LogLevel, QueryOptions, RequestConfig, StandardResponse, type UseApiActions, UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, processResponse };

package/dist/index.js

@@ -502,11 +502,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -647,6 +649,17 @@ var CacheManager = class {
   }
 };
 var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
+var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
+  const params = { path: callOptions.pathParams, body: input };
+  try {
+    return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
+  } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
+    return `${moduleName}/${actionName}::${Date.now()}`;
+  }
+};
 export {
   buildPaginateQuery,
   cacheManager,
@@ -654,6 +667,7 @@ export {
   createApiActions,
   createApiClient,
   createApiServices,
+  generateCacheKey,
   globalStateManager,
   processResponse
 };

package/dist/server.cjs

@@ -195,11 +195,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -284,15 +286,94 @@ var GlobalStateManager = class {
 };
 var globalStateManager = new GlobalStateManager();
 
-// src/server.ts
+// src/hooks/useApi.ts
+var import_react = require("react");
+
+// src/hooks/useApiRecord/index.ts
+var import_react2 = require("react");
+
+// src/hooks/useDeepCompareEffect/index.ts
+var import_react3 = require("react");
+var import_fast_deep_equal = __toESM(require("fast-deep-equal"), 1);
+
+// src/hooks/useApiModule/useApiModule.ts
+var import_react4 = require("react");
+var ApiModuleContext = (0, import_react4.createContext)(null);
+var ApiModuleProvider = ApiModuleContext.Provider;
+
+// src/core/client.ts
+var import_axios3 = __toESM(require("axios"), 1);
+var import_uuid = require("uuid");
+
+// src/core/cache.ts
+var CacheManager = class {
+  constructor() {
+    __publicField(this, "cache", /* @__PURE__ */ new Map());
+    __publicField(this, "defaultDuration", 15 * 60 * 1e3);
+  }
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  /**
+   * [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
+   * الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
+   */
+  getWithMeta(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  invalidateByPrefix(prefix) {
+    const keysToDelete = [];
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+    keysToDelete.forEach((key) => this.cache.delete(key));
+    console.log(`Invalidated ${keysToDelete.length} cache entries with prefix: ${prefix}`);
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
 var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
   const params = { path: callOptions.pathParams, body: input };
   try {
     return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
   } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
     return `${moduleName}/${actionName}::${Date.now()}`;
   }
 };
+
+// src/server.ts
 function createServerApi(apiClient, moduleConfig) {
   return {
     /**

package/dist/server.d.cts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from 'axios';
-import { A as ActionConfigModule, a as ApiModuleConfig, I as InputOf } from './apiModule.types-CpwGDEpG.cjs';
+import { A as ActionConfigModule, a as ApiModuleConfig, I as InputOf } from './apiModule.types-Cvp9QdAc.cjs';
 import 'react';
 
 /**

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from 'axios';
-import { A as ActionConfigModule, a as ApiModuleConfig, I as InputOf } from './apiModule.types-CpwGDEpG.js';
+import { A as ActionConfigModule, a as ApiModuleConfig, I as InputOf } from './apiModule.types-Cvp9QdAc.js';
 import 'react';
 
 /**

package/dist/server.js

@@ -161,11 +161,13 @@ var GlobalStateManager = class {
   constructor() {
     __publicField(this, "store", /* @__PURE__ */ new Map());
   }
-  /**
-   * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
-   */
   getSnapshot(key) {
-    return this.store.get(key)?.state ?? createInitialState();
+    if (!this.store.has(key)) {
+      const initialState = createInitialState();
+      this.store.set(key, { state: initialState, listeners: /* @__PURE__ */ new Set() });
+      return initialState;
+    }
+    return this.store.get(key).state;
   }
   /**
    * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
@@ -250,15 +252,94 @@ var GlobalStateManager = class {
 };
 var globalStateManager = new GlobalStateManager();
 
-// src/server.ts
+// src/hooks/useApi.ts
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
+
+// src/hooks/useApiRecord/index.ts
+import { useState as useState2, useEffect as useEffect2, useCallback as useCallback2, useRef as useRef2, useMemo as useMemo2 } from "react";
+
+// src/hooks/useDeepCompareEffect/index.ts
+import { useEffect as useEffect3, useRef as useRef3 } from "react";
+import isEqual from "fast-deep-equal";
+
+// src/hooks/useApiModule/useApiModule.ts
+import { createContext, useContext, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef4, useState as useState3, useSyncExternalStore } from "react";
+var ApiModuleContext = createContext(null);
+var ApiModuleProvider = ApiModuleContext.Provider;
+
+// src/core/client.ts
+import axios3 from "axios";
+import { v4 as uuidv4 } from "uuid";
+
+// src/core/cache.ts
+var CacheManager = class {
+  constructor() {
+    __publicField(this, "cache", /* @__PURE__ */ new Map());
+    __publicField(this, "defaultDuration", 15 * 60 * 1e3);
+  }
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  /**
+   * [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
+   * الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
+   */
+  getWithMeta(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  invalidateByPrefix(prefix) {
+    const keysToDelete = [];
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+    keysToDelete.forEach((key) => this.cache.delete(key));
+    console.log(`Invalidated ${keysToDelete.length} cache entries with prefix: ${prefix}`);
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/cacheKey.ts
 var generateCacheKey = (moduleName, actionName, input, callOptions = {}) => {
   const params = { path: callOptions.pathParams, body: input };
   try {
     return `${moduleName}/${actionName}::${JSON.stringify(params)}`;
   } catch (error) {
+    console.warn("Could not stringify cache key params, falling back to timestamp.", { moduleName, actionName, error });
     return `${moduleName}/${actionName}::${Date.now()}`;
   }
 };
+
+// src/server.ts
 function createServerApi(apiClient, moduleConfig) {
   return {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-core-lib",
-  "version": "12.0.12",
+  "version": "12.0.14",
   "description": "A flexible and powerful API client library for modern web applications.",
   "type": "module",