api-core-lib 12.10.4 → 12.12.4

package/dist/index.d.mts

@@ -211,14 +211,6 @@ interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any
     baseEndpoint: string;
     actions: TActions;
 }
-/** @description Configuration options passed directly to the `useApiModule` hook. */
-interface UseApiModuleOptions {
-    onSuccess?: (actionName: string, message: string, data: unknown) => void;
-    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    refetchOnWindowFocus?: boolean;
-    pathParams?: Record<string, any>;
-    enabled?: boolean;
-}
 /** A utility type to infer the Input type (`TInput`) from an ActionConfigModule. */
 type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
 /** A utility type to infer the Output type (`TOutput`) from an ActionConfigModule. */
@@ -244,6 +236,34 @@ type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>
 type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
     [K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
 };
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+}
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+    /** [NEW.............] The dehydrated state string from the server to avoid re-fetching on the client. */
+    hydratedState?: string;
+}
+/** @description The complete, fully-typed return object of the `useApiModule` hook. */
+interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    states: ModuleStates<TActions>;
+    actions: ModuleActions<TActions>;
+    queries: {
+        [K in keyof TActions]?: TActions[K] extends {
+            hasQuery: true;
+        } ? UseApiQuery : never;
+    };
+}
 /** @description The complete, fully-typed return object of the `useApiModule` hook. */
 interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
     states: ModuleStates<TActions>;
@@ -253,6 +273,8 @@ interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<
             hasQuery: true;
         } ? UseApiQuery : never;
     };
+    /** [NEW.............] A function to serialize the current state of all queries in the hook's scope to a JSON string. */
+    dehydrate: () => string;
 }
 
 /**
@@ -270,6 +292,22 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint
     bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
     upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
 };
+/**
+ * [نسخة محدثة ومحسّنة]
+ * دالة عامة وصريحة لتنفيذ أي طلب API.
+ * تستقبل وسائط منظمة بدلاً من محاولة تخمينها.
+ *
+ * @param axiosInstance - نسخة Axios.
+ * @param baseEndpoint - نقطة النهاية الأساسية للموديول.
+ * @param actionConfig - إعدادات الإجراء المحدد.
+ * @param params - كائن يحتوي على جميع البارامترات اللازمة للطلب.
+ * @returns Promise<StandardResponse<any>>
+ */
+declare function callDynamicApi(axiosInstance: AxiosInstance, baseEndpoint: string, actionConfig: ActionConfigModule<any, any>, params: {
+    pathParams?: Record<string, string | number>;
+    body?: any;
+    config?: AxiosRequestConfig;
+}): Promise<StandardResponse<any>>;
 
 /**
  * [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
@@ -448,6 +486,46 @@ declare const ApiModuleProvider: React$1.Provider<UseApiModuleReturn<any> | null
 declare function useModuleContext<TActions extends Record<string, ActionConfigModule<any, any>>>(): UseApiModuleReturn<TActions>;
 declare function useApiModule<TActions extends Record<string, ActionConfigModule<any, any>>>(axiosInstance: AxiosInstance, moduleConfig: ApiModuleConfig<TActions>, options?: UseApiModuleOptions): UseApiModuleReturn<TActions>;
 
+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;
+
 /**
  * @file src/hooks/useApi.types.ts
  * @description This file defines the professional, publicly-facing types for the `useApi` hook,
@@ -529,4 +607,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };
+export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };

package/dist/index.d.ts

@@ -211,14 +211,6 @@ interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any
     baseEndpoint: string;
     actions: TActions;
 }
-/** @description Configuration options passed directly to the `useApiModule` hook. */
-interface UseApiModuleOptions {
-    onSuccess?: (actionName: string, message: string, data: unknown) => void;
-    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    refetchOnWindowFocus?: boolean;
-    pathParams?: Record<string, any>;
-    enabled?: boolean;
-}
 /** A utility type to infer the Input type (`TInput`) from an ActionConfigModule. */
 type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
 /** A utility type to infer the Output type (`TOutput`) from an ActionConfigModule. */
@@ -244,6 +236,34 @@ type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>
 type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
     [K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
 };
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+}
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+    /** [NEW.............] The dehydrated state string from the server to avoid re-fetching on the client. */
+    hydratedState?: string;
+}
+/** @description The complete, fully-typed return object of the `useApiModule` hook. */
+interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    states: ModuleStates<TActions>;
+    actions: ModuleActions<TActions>;
+    queries: {
+        [K in keyof TActions]?: TActions[K] extends {
+            hasQuery: true;
+        } ? UseApiQuery : never;
+    };
+}
 /** @description The complete, fully-typed return object of the `useApiModule` hook. */
 interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
     states: ModuleStates<TActions>;
@@ -253,6 +273,8 @@ interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<
             hasQuery: true;
         } ? UseApiQuery : never;
     };
+    /** [NEW.............] A function to serialize the current state of all queries in the hook's scope to a JSON string. */
+    dehydrate: () => string;
 }
 
 /**
@@ -270,6 +292,22 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint
     bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
     upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
 };
+/**
+ * [نسخة محدثة ومحسّنة]
+ * دالة عامة وصريحة لتنفيذ أي طلب API.
+ * تستقبل وسائط منظمة بدلاً من محاولة تخمينها.
+ *
+ * @param axiosInstance - نسخة Axios.
+ * @param baseEndpoint - نقطة النهاية الأساسية للموديول.
+ * @param actionConfig - إعدادات الإجراء المحدد.
+ * @param params - كائن يحتوي على جميع البارامترات اللازمة للطلب.
+ * @returns Promise<StandardResponse<any>>
+ */
+declare function callDynamicApi(axiosInstance: AxiosInstance, baseEndpoint: string, actionConfig: ActionConfigModule<any, any>, params: {
+    pathParams?: Record<string, string | number>;
+    body?: any;
+    config?: AxiosRequestConfig;
+}): Promise<StandardResponse<any>>;
 
 /**
  * [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
@@ -448,6 +486,46 @@ declare const ApiModuleProvider: React$1.Provider<UseApiModuleReturn<any> | null
 declare function useModuleContext<TActions extends Record<string, ActionConfigModule<any, any>>>(): UseApiModuleReturn<TActions>;
 declare function useApiModule<TActions extends Record<string, ActionConfigModule<any, any>>>(axiosInstance: AxiosInstance, moduleConfig: ApiModuleConfig<TActions>, options?: UseApiModuleOptions): UseApiModuleReturn<TActions>;
 
+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;
+
 /**
  * @file src/hooks/useApi.types.ts
  * @description This file defines the professional, publicly-facing types for the `useApi` hook,
@@ -529,4 +607,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };
+export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };