api-core-lib 11.9.8 → 11.10.9

package/dist/index.d.mts

@@ -1,12 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
 
-interface Logger {
-    debug: (message: string, ...args: any[]) => void;
-    info: (message: string, ...args: any[]) => void;
-    warn: (message: string, ...args: any[]) => void;
-    error: (message: string, ...args: any[]) => void;
-}
-
 /**
  * @file src/types.ts
  * @description This file serves as the central source for all data types and interfaces
@@ -95,7 +88,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -223,7 +215,6 @@ interface ApiClientConfig {
     /** A callback function executed if the token refresh process fails. */
     onRefreshError?: (error: any) => void;
     /** A custom logger instance. Defaults to the browser `console`. */
-    logger?: Logger;
     /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
     /**
@@ -311,144 +302,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * [إضافة جديدة]
- * يمثل الكائن الكامل الذي يتم إرجاعه من الهوك `useApiModule`.
- * يفصل بين الدوال المستقرة والحالات المتغيرة.
- * @template TModule نوع إعدادات الموديول.
- */
-interface UseApiModuleReturn<TModule extends ApiModuleConfig> {
-    /**
-     * قاموس من الإجراءات التنفيذية المستقرة.
-     * آمن للاستخدام في مصفوفات الاعتماديات مثل `useEffect`.
-     */
-    actions: ModuleActions<TModule>;
-    /**
-     * قاموس من الحالات المتغيرة لجميع الإجراءات.
-     * استخدم هذا الكائن لعرض البيانات، وحالات التحميل، والأخطاء في واجهة المستخدم.
-     */
-    states: Record<keyof TModule['actions'], ActionState<any>>;
-    /**
-     * قاموس من أدوات التحكم بالاستعلام لجميع الإجراءات التي تم تمييزها بـ `isList: true`.
-     */
-    queries: Record<string, UseApiQuery | undefined>;
-}
-/**
- * يصف إجراءً واحدًا داخل وحدة API، مع أنواع دقيقة للإدخال والإخراج.
- * @template TInput نوع بيانات الإدخال (الجسم أو معاملات الاستعلام).
- * @template TOutput نوع البيانات التي يتم إرجاعها في `data` عند النجاح.
- */
 interface ActionConfig<TInput = any, TOutput = any> {
-    /** نوع طلب HTTP. */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /**
-     * المسار النسبي للإجراء. يمكن أن يحتوي على متغيرات مثل `{id}` أو `{tenantId}`.
-     * مثال: '/{id}/activate'
-     */
     path: string;
-    /**
-     * وصف للإجراء، مفيد للتوثيق وتلميحات محرر الكود.
-     */
     description?: string;
-    /**
-     * إذا كان `true`، فهذا يعني أن الإجراء يجلب قائمة بيانات ويدعم معاملات الاستعلام (pagination, sorting).
-     * سيتم تزويد هذا الإجراء بأدوات التحكم `query` تلقائيًا.
-     */
     isList?: boolean;
-    /**
-     * قائمة بأسماء الإجراءات (من نفس الموديول) التي يجب إبطال بياناتها في الـ Cache بعد نجاح هذا الإجراء.
-     * أساسي لمزامنة البيانات تلقائيًا بعد عمليات التعديل (Mutations).
-     * مثال: إجراء `update` يجب أن يبطل `getOne` و `list`.
-     */
     invalidates?: string[];
 }
-/**
- * يمثل الإعداد الكامل لوحدة API. هذا هو "مصدر الحقيقة" لمجموعة من نقاط النهاية.
- */
 interface ApiModuleConfig {
-    /** نقطة النهاية الأساسية للموديول (مثل '/api/v1/products'). */
     baseEndpoint: string;
-    /** قاموس يحتوي على جميع الإجراءات المتاحة في هذا الموديول. المفتاح هو اسم الإجراء. */
     actions: Record<string, ActionConfig<any, any>>;
 }
-/**
- * إعدادات اختيارية لتخصيص سلوك الهوك `useApiModule`.
- */
 interface UseApiModuleOptions {
-    /**
-     * دالة callback تُنفذ عند نجاح أي إجراء.
-     * @param actionName اسم الإجراء الذي نجح.
-     * @param message رسالة النجاح من الـ API.
-     * @param data البيانات المُرجعة.
-     */
     onSuccess?: (actionName: string, message: string, data: any) => void;
-    /**
-     * دالة callback تُنفذ عند فشل أي إجراء.
-     * @param actionName اسم الإجراء الذي فشل.
-     * @param message رسالة الخطأ من الـ API.
-     * @param error كائن الخطأ الموحد.
-     */
     onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    /**
-     * المدة التي تعتبر فيها البيانات "حية" (fresh) بالمللي ثانية.
-     * خلال هذه المدة، لن يتم إرسال طلب شبكة جديد لنفس البيانات.
-     * الافتراضي: `0` (مما يعني أنها تعتبر "قديمة" stale فورًا).
-     */
     staleTime?: number;
-    /**
-     * مدة بقاء البيانات في الـ Cache (بالمللي ثانية) قبل أن يتم حذفها تلقائيًا.
-     * يمرر إلى `cacheManager.set`. إذا لم يتم تحديده، يستخدم `CacheManager` قيمته الافتراضية.
-     */
     cacheTime?: number;
-    /**
-     * إذا كان `true`، سيتم إعادة جلب جميع الإجراءات التي تم استدعاؤها عند عودة المستخدم إلى نافذة التطبيق.
-     * الافتراضي: `true`.
-     */
     refetchOnWindowFocus?: boolean;
 }
-/**
- * الحالة التي يديرها كل إجراء على حدة.
- * @template TOutput نوع بيانات الإخراج.
- */
 interface ActionState<TOutput> {
-    /** البيانات التي تم جلبها بنجاح. تكون `null` في البداية أو عند حدوث خطأ. */
     data: TOutput | null;
-    /** كائن الخطأ في حال فشل الطلب. */
     error: ApiError | null;
-    /** `true` أثناء تنفيذ طلب الشبكة. */
     loading: boolean;
-    /** `true` إذا كان آخر طلب قد نجح. */
     success: boolean;
-    /** `true` إذا تم استدعاء الإجراء مرة واحدة على الأقل. مفيد للتمييز بين الحالة الأولية وحالة "لم يتم العثور على بيانات". */
     called: boolean;
 }
 /**
- * الكائن التنفيذي للإجراء، يجمع بين دالة التنفيذ وحالته الخاصة.
- * @template TInput نوع بيانات الإدخال.
- * @template TOutput نوع بيانات الإخراج.
+ * The unified object for a single action, containing its state, executor, and controls.
+ * This is the new, more ergonomic return structure.
  */
 interface ExecutableAction<TInput, TOutput> {
-    /**
-     * الدالة الرئيسية لتنفيذ الإجراء.
-     * @param input بيانات الإدخال (الجسم أو معاملات الاستعلام).
-     * @param options خيارات إضافية للطلب مثل `pathParams` و `config` Axios.
-     * @returns `Promise` يحتوي على الاستجابة الموحدة `StandardResponse`.
-     */
+    /** The reactive state for this specific action. */
+    state: ActionState<TOutput>;
+    /** The stable function to execute the API call. */
     execute: (input?: TInput, options?: {
         pathParams?: Record<string, any>;
         config?: AxiosRequestConfig;
         query?: QueryOptions;
     }) => Promise<StandardResponse<TOutput>>;
-    /** الحالة الحالية لهذا الإجراء المحدد. */
-    state: ActionState<TOutput>;
-    /** دالة لإعادة حالة هذا الإجراء إلى وضعها الأولي. */
+    /** A stable function to reset the action's state to its initial value. */
     reset: () => void;
-    /** أدوات التحكم بالاستعلام (pagination, sorting) متاحة فقط للإجراءات المعرفة بـ `isList: true`. */
+    /** Query controls (pagination, sorting, etc.) available only if `isList: true`. */
     query?: UseApiQuery;
 }
 /**
- * النوع النهائي الذي يتم إرجاعه من الهوك `useApiModule`.
- * وهو عبارة عن قاموس من الإجراءات القابلة للتنفيذ، مع أنواع مستنتجة بالكامل.
+ * The final, fully-typed object returned by the useApiModule hook.
+ * It's a dictionary of executable actions.
  */
 type ModuleActions<TModule extends ApiModuleConfig> = {
     [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<infer TInput, infer TOutput> ? ExecutableAction<TInput, TOutput> : never;
@@ -550,11 +449,11 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * A sophisticated hook that dynamically builds a set of executable API actions from a module configuration.
- * It provides a clean separation between stable functions and reactive state, preventing infinite loops
- * and enabling advanced features like caching and automatic refetching with full type-safety and autocompletion.
+ * A production-ready custom hook that dynamically builds a set of executable and fully-typed API actions.
+ * It provides a unified, ergonomic API for each action, collocating state and execution logic,
+ * while guaranteeing stable function references to prevent re-renders.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): UseApiModuleReturn<TModule>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -602,4 +501,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { type ActionConfig, type ActionOptions, type ActionState, type ApiClientConfig, type ApiError, type ApiModuleConfig, type ApiResourceStatus, type ApiResponse, type ExecutableAction, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, 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 UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };
+export { type ActionConfig, type ActionOptions, type ActionState, type ApiClientConfig, type ApiError, type ApiModuleConfig, type ApiResourceStatus, type ApiResponse, type ExecutableAction, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };

package/dist/index.d.ts

@@ -1,12 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
 
-interface Logger {
-    debug: (message: string, ...args: any[]) => void;
-    info: (message: string, ...args: any[]) => void;
-    warn: (message: string, ...args: any[]) => void;
-    error: (message: string, ...args: any[]) => void;
-}
-
 /**
  * @file src/types.ts
  * @description This file serves as the central source for all data types and interfaces
@@ -95,7 +88,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -223,7 +215,6 @@ interface ApiClientConfig {
     /** A callback function executed if the token refresh process fails. */
     onRefreshError?: (error: any) => void;
     /** A custom logger instance. Defaults to the browser `console`. */
-    logger?: Logger;
     /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
     /**
@@ -311,144 +302,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * [إضافة جديدة]
- * يمثل الكائن الكامل الذي يتم إرجاعه من الهوك `useApiModule`.
- * يفصل بين الدوال المستقرة والحالات المتغيرة.
- * @template TModule نوع إعدادات الموديول.
- */
-interface UseApiModuleReturn<TModule extends ApiModuleConfig> {
-    /**
-     * قاموس من الإجراءات التنفيذية المستقرة.
-     * آمن للاستخدام في مصفوفات الاعتماديات مثل `useEffect`.
-     */
-    actions: ModuleActions<TModule>;
-    /**
-     * قاموس من الحالات المتغيرة لجميع الإجراءات.
-     * استخدم هذا الكائن لعرض البيانات، وحالات التحميل، والأخطاء في واجهة المستخدم.
-     */
-    states: Record<keyof TModule['actions'], ActionState<any>>;
-    /**
-     * قاموس من أدوات التحكم بالاستعلام لجميع الإجراءات التي تم تمييزها بـ `isList: true`.
-     */
-    queries: Record<string, UseApiQuery | undefined>;
-}
-/**
- * يصف إجراءً واحدًا داخل وحدة API، مع أنواع دقيقة للإدخال والإخراج.
- * @template TInput نوع بيانات الإدخال (الجسم أو معاملات الاستعلام).
- * @template TOutput نوع البيانات التي يتم إرجاعها في `data` عند النجاح.
- */
 interface ActionConfig<TInput = any, TOutput = any> {
-    /** نوع طلب HTTP. */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /**
-     * المسار النسبي للإجراء. يمكن أن يحتوي على متغيرات مثل `{id}` أو `{tenantId}`.
-     * مثال: '/{id}/activate'
-     */
     path: string;
-    /**
-     * وصف للإجراء، مفيد للتوثيق وتلميحات محرر الكود.
-     */
     description?: string;
-    /**
-     * إذا كان `true`، فهذا يعني أن الإجراء يجلب قائمة بيانات ويدعم معاملات الاستعلام (pagination, sorting).
-     * سيتم تزويد هذا الإجراء بأدوات التحكم `query` تلقائيًا.
-     */
     isList?: boolean;
-    /**
-     * قائمة بأسماء الإجراءات (من نفس الموديول) التي يجب إبطال بياناتها في الـ Cache بعد نجاح هذا الإجراء.
-     * أساسي لمزامنة البيانات تلقائيًا بعد عمليات التعديل (Mutations).
-     * مثال: إجراء `update` يجب أن يبطل `getOne` و `list`.
-     */
     invalidates?: string[];
 }
-/**
- * يمثل الإعداد الكامل لوحدة API. هذا هو "مصدر الحقيقة" لمجموعة من نقاط النهاية.
- */
 interface ApiModuleConfig {
-    /** نقطة النهاية الأساسية للموديول (مثل '/api/v1/products'). */
     baseEndpoint: string;
-    /** قاموس يحتوي على جميع الإجراءات المتاحة في هذا الموديول. المفتاح هو اسم الإجراء. */
     actions: Record<string, ActionConfig<any, any>>;
 }
-/**
- * إعدادات اختيارية لتخصيص سلوك الهوك `useApiModule`.
- */
 interface UseApiModuleOptions {
-    /**
-     * دالة callback تُنفذ عند نجاح أي إجراء.
-     * @param actionName اسم الإجراء الذي نجح.
-     * @param message رسالة النجاح من الـ API.
-     * @param data البيانات المُرجعة.
-     */
     onSuccess?: (actionName: string, message: string, data: any) => void;
-    /**
-     * دالة callback تُنفذ عند فشل أي إجراء.
-     * @param actionName اسم الإجراء الذي فشل.
-     * @param message رسالة الخطأ من الـ API.
-     * @param error كائن الخطأ الموحد.
-     */
     onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    /**
-     * المدة التي تعتبر فيها البيانات "حية" (fresh) بالمللي ثانية.
-     * خلال هذه المدة، لن يتم إرسال طلب شبكة جديد لنفس البيانات.
-     * الافتراضي: `0` (مما يعني أنها تعتبر "قديمة" stale فورًا).
-     */
     staleTime?: number;
-    /**
-     * مدة بقاء البيانات في الـ Cache (بالمللي ثانية) قبل أن يتم حذفها تلقائيًا.
-     * يمرر إلى `cacheManager.set`. إذا لم يتم تحديده، يستخدم `CacheManager` قيمته الافتراضية.
-     */
     cacheTime?: number;
-    /**
-     * إذا كان `true`، سيتم إعادة جلب جميع الإجراءات التي تم استدعاؤها عند عودة المستخدم إلى نافذة التطبيق.
-     * الافتراضي: `true`.
-     */
     refetchOnWindowFocus?: boolean;
 }
-/**
- * الحالة التي يديرها كل إجراء على حدة.
- * @template TOutput نوع بيانات الإخراج.
- */
 interface ActionState<TOutput> {
-    /** البيانات التي تم جلبها بنجاح. تكون `null` في البداية أو عند حدوث خطأ. */
     data: TOutput | null;
-    /** كائن الخطأ في حال فشل الطلب. */
     error: ApiError | null;
-    /** `true` أثناء تنفيذ طلب الشبكة. */
     loading: boolean;
-    /** `true` إذا كان آخر طلب قد نجح. */
     success: boolean;
-    /** `true` إذا تم استدعاء الإجراء مرة واحدة على الأقل. مفيد للتمييز بين الحالة الأولية وحالة "لم يتم العثور على بيانات". */
     called: boolean;
 }
 /**
- * الكائن التنفيذي للإجراء، يجمع بين دالة التنفيذ وحالته الخاصة.
- * @template TInput نوع بيانات الإدخال.
- * @template TOutput نوع بيانات الإخراج.
+ * The unified object for a single action, containing its state, executor, and controls.
+ * This is the new, more ergonomic return structure.
  */
 interface ExecutableAction<TInput, TOutput> {
-    /**
-     * الدالة الرئيسية لتنفيذ الإجراء.
-     * @param input بيانات الإدخال (الجسم أو معاملات الاستعلام).
-     * @param options خيارات إضافية للطلب مثل `pathParams` و `config` Axios.
-     * @returns `Promise` يحتوي على الاستجابة الموحدة `StandardResponse`.
-     */
+    /** The reactive state for this specific action. */
+    state: ActionState<TOutput>;
+    /** The stable function to execute the API call. */
     execute: (input?: TInput, options?: {
         pathParams?: Record<string, any>;
         config?: AxiosRequestConfig;
         query?: QueryOptions;
     }) => Promise<StandardResponse<TOutput>>;
-    /** الحالة الحالية لهذا الإجراء المحدد. */
-    state: ActionState<TOutput>;
-    /** دالة لإعادة حالة هذا الإجراء إلى وضعها الأولي. */
+    /** A stable function to reset the action's state to its initial value. */
     reset: () => void;
-    /** أدوات التحكم بالاستعلام (pagination, sorting) متاحة فقط للإجراءات المعرفة بـ `isList: true`. */
+    /** Query controls (pagination, sorting, etc.) available only if `isList: true`. */
     query?: UseApiQuery;
 }
 /**
- * النوع النهائي الذي يتم إرجاعه من الهوك `useApiModule`.
- * وهو عبارة عن قاموس من الإجراءات القابلة للتنفيذ، مع أنواع مستنتجة بالكامل.
+ * The final, fully-typed object returned by the useApiModule hook.
+ * It's a dictionary of executable actions.
  */
 type ModuleActions<TModule extends ApiModuleConfig> = {
     [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<infer TInput, infer TOutput> ? ExecutableAction<TInput, TOutput> : never;
@@ -550,11 +449,11 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * A sophisticated hook that dynamically builds a set of executable API actions from a module configuration.
- * It provides a clean separation between stable functions and reactive state, preventing infinite loops
- * and enabling advanced features like caching and automatic refetching with full type-safety and autocompletion.
+ * A production-ready custom hook that dynamically builds a set of executable and fully-typed API actions.
+ * It provides a unified, ergonomic API for each action, collocating state and execution logic,
+ * while guaranteeing stable function references to prevent re-renders.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): UseApiModuleReturn<TModule>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -602,4 +501,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { type ActionConfig, type ActionOptions, type ActionState, type ApiClientConfig, type ApiError, type ApiModuleConfig, type ApiResourceStatus, type ApiResponse, type ExecutableAction, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, 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 UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };
+export { type ActionConfig, type ActionOptions, type ActionState, type ApiClientConfig, type ApiError, type ApiModuleConfig, type ApiResourceStatus, type ApiResponse, type ExecutableAction, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };