api-core-lib 10.10.10 → 11.0.0

package/dist/index.d.mts

@@ -88,7 +88,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -197,20 +196,6 @@ type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
  * An interface for a custom logger, compatible with the standard `console` object.
  * It now includes a `debug` method for more granular logging.
  */
-interface Logger {
-    /** Logs a standard message. In our wrapper, this is often an alias for `info` or `debug`. */
-    log(message?: any, ...optionalParams: any[]): void;
-    /** Logs an informational message. */
-    info(message?: any, ...optionalParams: any[]): void;
-    /** Logs a warning message. */
-    warn(message?: any, ...optionalParams: any[]): void;
-    /** Logs an error message. */
-    error(message?: any, ...optionalParams: any[]): void;
-    /**
-     * Logs a debug message, typically for verbose, development-only output.
-     */
-    debug(message?: any, ...optionalParams: any[]): void;
-}
 /**
  * The main configuration object for the `createApiClient` factory function.
  */
@@ -230,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[];
     /**
@@ -244,19 +228,10 @@ interface ApiClientConfig {
      * @default false
      */
     defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
 }
 
-/**
- * @file src/core/client.ts
- * @description This is the heart of the API client library.
- * The `createApiClient` function constructs and configures a sophisticated Axios instance.
- * It features intelligent, security-first token management, a flexible middleware system,
- * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
- */
-
-/**
- * Creates and configures a new Axios instance with advanced features.
- */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 /**
@@ -327,122 +302,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * يصف إجراءً واحدًا داخل وحدة 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;
@@ -539,21 +444,14 @@ declare class CacheManager {
 }
 declare const cacheManager: CacheManager;
 
-/**
- * A smart response processor that normalizes API responses.
- * It intelligently unwraps nested data from standard API envelopes
- * (like { success: true, data: {...} }) and provides direct access
- * to the core data, while still handling errors consistently.
- *
- * @param responseOrError The raw Axios response or a pre-processed ApiError.
- * @returns A standardized `StandardResponse` object with direct access to `.data`.
- */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
 
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API.
+ * 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): ModuleActions<TModule>;
 
@@ -603,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 Logger, 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 };
+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

@@ -88,7 +88,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -197,20 +196,6 @@ type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
  * An interface for a custom logger, compatible with the standard `console` object.
  * It now includes a `debug` method for more granular logging.
  */
-interface Logger {
-    /** Logs a standard message. In our wrapper, this is often an alias for `info` or `debug`. */
-    log(message?: any, ...optionalParams: any[]): void;
-    /** Logs an informational message. */
-    info(message?: any, ...optionalParams: any[]): void;
-    /** Logs a warning message. */
-    warn(message?: any, ...optionalParams: any[]): void;
-    /** Logs an error message. */
-    error(message?: any, ...optionalParams: any[]): void;
-    /**
-     * Logs a debug message, typically for verbose, development-only output.
-     */
-    debug(message?: any, ...optionalParams: any[]): void;
-}
 /**
  * The main configuration object for the `createApiClient` factory function.
  */
@@ -230,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[];
     /**
@@ -244,19 +228,10 @@ interface ApiClientConfig {
      * @default false
      */
     defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
 }
 
-/**
- * @file src/core/client.ts
- * @description This is the heart of the API client library.
- * The `createApiClient` function constructs and configures a sophisticated Axios instance.
- * It features intelligent, security-first token management, a flexible middleware system,
- * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
- */
-
-/**
- * Creates and configures a new Axios instance with advanced features.
- */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 /**
@@ -327,122 +302,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * يصف إجراءً واحدًا داخل وحدة 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;
@@ -539,21 +444,14 @@ declare class CacheManager {
 }
 declare const cacheManager: CacheManager;
 
-/**
- * A smart response processor that normalizes API responses.
- * It intelligently unwraps nested data from standard API envelopes
- * (like { success: true, data: {...} }) and provides direct access
- * to the core data, while still handling errors consistently.
- *
- * @param responseOrError The raw Axios response or a pre-processed ApiError.
- * @returns A standardized `StandardResponse` object with direct access to `.data`.
- */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
 
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API.
+ * 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): ModuleActions<TModule>;
 
@@ -603,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 Logger, 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 };
+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 };