api-core-lib 9.9.8 → 10.9.9

package/dist/index.d.mts

@@ -259,6 +259,195 @@ interface ApiClientConfig {
  */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
+/**
+ * @file src/hooks/useApi.types.ts
+ * @description This file defines the professional, publicly-facing types for the `useApi` hook,
+ * providing a clean and stable contract for consumers.
+ */
+
+/**
+ * Configuration object for the `useApi` hook.
+ * @template T The type of the data entity.
+ */
+/**
+ * The primary state object managed by the `useApi` hook.
+ * It contains the fetched data, loading status, and any potential errors.
+ * @template T The type of the data entity being managed.
+ */
+type UseApiState<T> = StandardResponse<T>;
+/**
+ * A collection of callable functions for performing CRUD and other operations.
+ * These actions automatically handle state updates like loading and refetching.
+ * @template T The type of the data entity being managed.
+ */
+interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
+    fetch: () => Promise<void>;
+    create: (newItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    put: (id: string | number, item: TListItem, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    update: (id: string | number, updatedItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
+    bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+}
+/**
+ * A collection of functions and properties for controlling the query parameters
+ * used for fetching data, such as pagination, sorting, and filtering.
+ */
+interface UseApiQuery {
+    /** The current query options state. */
+    options: QueryOptions;
+    /** A function to set the entire query options object at once. */
+    setOptions: React.Dispatch<React.SetStateAction<QueryOptions>>;
+    /** Sets the current page number. */
+    setPage: (page: number) => void;
+    /** Sets the number of items per page and resets to the first page. */
+    setLimit: (limit: number) => void;
+    /** Sets the search term and resets to the first page. */
+    setSearchTerm: (search: string) => void;
+    /** Sets the sorting configuration. */
+    setSorting: (sortBy: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[]) => void;
+    /** Sets the filter object and resets to the first page. */
+    setFilters: (filter: Record<string, any>) => void;
+    /** Sets a single, custom query parameter. */
+    setQueryParam: (key: string, value: any) => void;
+    /** Resets the query options to their initial state. */
+    reset: () => void;
+}
+/**
+ * The complete return type of the `useApi` hook.
+ * It encapsulates the state, actions, and query controls for a given API resource.
+ * @template T The type of the data entity being managed.
+ */
+interface UseApiReturn<T> {
+    state: UseApiState<T>;
+    setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
+    actions: UseApiActions<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 نوع بيانات الإخراج.
+ */
+interface ExecutableAction<TInput, TOutput> {
+    /**
+     * الدالة الرئيسية لتنفيذ الإجراء.
+     * @param input بيانات الإدخال (الجسم أو معاملات الاستعلام).
+     * @param options خيارات إضافية للطلب مثل `pathParams` و `config` Axios.
+     * @returns `Promise` يحتوي على الاستجابة الموحدة `StandardResponse`.
+     */
+    execute: (input?: TInput, options?: {
+        pathParams?: Record<string, any>;
+        config?: AxiosRequestConfig;
+        query?: QueryOptions;
+    }) => Promise<StandardResponse<TOutput>>;
+    /** الحالة الحالية لهذا الإجراء المحدد. */
+    state: ActionState<TOutput>;
+    /** دالة لإعادة حالة هذا الإجراء إلى وضعها الأولي. */
+    reset: () => void;
+    /** أدوات التحكم بالاستعلام (pagination, sorting) متاحة فقط للإجراءات المعرفة بـ `isList: true`. */
+    query?: UseApiQuery;
+}
+/**
+ * النوع النهائي الذي يتم إرجاعه من الهوك `useApiModule`.
+ * وهو عبارة عن قاموس من الإجراءات القابلة للتنفيذ، مع أنواع مستنتجة بالكامل.
+ */
+type ModuleActions<TModule extends ApiModuleConfig> = {
+    [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<infer TInput, infer TOutput> ? ExecutableAction<TInput, TOutput> : never;
+};
+
 /**
  * A factory function to create a reusable set of API services for a specific endpoint.
  * It provides full CRUD operations plus advanced features like bulk deletion and file uploads,
@@ -325,13 +514,28 @@ declare function createApiActions<TActions extends Record<string, {
     [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
 };
 
+interface CacheItem<T> {
+    data: T;
+    timestamp: number;
+    duration: number;
+}
 declare class CacheManager {
     private cache;
     private defaultDuration;
     set<T>(key: string, data: T, duration?: number): void;
     get<T>(key: string): T | null;
+    /**
+     * [دالة جديدة] تعيد عنصر الـ Cache بالكامل (البيانات + معلومات إضافية)
+     * دون حذفه عند انتهاء الصلاحية. هذا يسمح لنا بتطبيق منطق stale-while-revalidate.
+     */
+    getWithMeta<T>(key: string): CacheItem<T> | null;
     delete(key: string): void;
     clear(): void;
+    /**
+     * [دالة جديدة] تقوم بإبطال (حذف) جميع عناصر الـ Cache التي تبدأ ببادئة معينة.
+     * أساسية لعملية invalidation التلقائية.
+     */
+    invalidateByPrefix(prefix: string): void;
 }
 declare const cacheManager: CacheManager;
 
@@ -346,74 +550,54 @@ declare const cacheManager: CacheManager;
  */
 declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
-/**
- * @file src/hooks/useApi.types.ts
- * @description This file defines the professional, publicly-facing types for the `useApi` hook,
- * providing a clean and stable contract for consumers.
- */
+declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
-/**
- * Configuration object for the `useApi` hook.
- * @template T The type of the data entity.
- */
-/**
- * The primary state object managed by the `useApi` hook.
- * It contains the fetched data, loading status, and any potential errors.
- * @template T The type of the data entity being managed.
- */
-type UseApiState<T> = StandardResponse<T>;
-/**
- * A collection of callable functions for performing CRUD and other operations.
- * These actions automatically handle state updates like loading and refetching.
- * @template T The type of the data entity being managed.
- */
-interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
-    fetch: () => Promise<void>;
-    create: (newItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    put: (id: string | number, item: TListItem, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    update: (id: string | number, updatedItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+
+type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
+interface UseApiResourceState<T> {
+    data: T | T[] | null;
+    error: ApiError | null;
+    status: ApiResourceStatus;
+    isFetching: boolean;
+    isMutating: boolean;
+    isSuccess: boolean;
+    lastResponse?: StandardResponse<any>;
 }
-/**
- * A collection of functions and properties for controlling the query parameters
- * used for fetching data, such as pagination, sorting, and filtering.
- */
-interface UseApiQuery {
-    /** The current query options state. */
-    options: QueryOptions;
-    /** A function to set the entire query options object at once. */
-    setOptions: React.Dispatch<React.SetStateAction<QueryOptions>>;
-    /** Sets the current page number. */
-    setPage: (page: number) => void;
-    /** Sets the number of items per page and resets to the first page. */
-    setLimit: (limit: number) => void;
-    /** Sets the search term and resets to the first page. */
-    setSearchTerm: (search: string) => void;
-    /** Sets the sorting configuration. */
-    setSorting: (sortBy: {
-        key: string;
-        direction: 'asc' | 'desc';
-    }[]) => void;
-    /** Sets the filter object and resets to the first page. */
-    setFilters: (filter: Record<string, any>) => void;
-    /** Sets a single, custom query parameter. */
-    setQueryParam: (key: string, value: any) => void;
-    /** Resets the query options to their initial state. */
+interface UseApiResourceActions<T, TCreate, TUpdate, TPathParams> {
+    fetch: (pathParams?: TPathParams, queryOptions?: QueryOptions) => Promise<StandardResponse<T[]>>;
+    fetchOne: (pathParams: TPathParams & {
+        id: string | number;
+    }, queryOptions?: QueryOptions) => Promise<StandardResponse<T>>;
+    create: (newItem: TCreate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    update: (id: string | number, updatedItem: TUpdate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    remove: (id: string | number, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<any>>;
     reset: () => void;
 }
-/**
- * The complete return type of the `useApi` hook.
- * It encapsulates the state, actions, and query controls for a given API resource.
- * @template T The type of the data entity being managed.
- */
-interface UseApiReturn<T> {
-    state: UseApiState<T>;
-    setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
-    actions: UseApiActions<T>;
+interface UseApiResourceConfig<TPathParams> {
+    /**
+     * The API endpoint template. Can be a static string or a function
+     * that builds the URL from parameters.
+     * @example '/users'
+     * @example (params) => `/modules/${params.moduleName}/records`
+     */
+    endpoint: string | ((params: TPathParams) => string);
+    /** Initial data to populate the state. */
+    initialData?: any;
+    /** Controls the verbosity of console logs for debugging. */
+    logLevel?: LogLevel;
+    /** Unique identifier for this hook instance, used in logging. */
+    logKey?: string;
+    /** Callback for success */
+    onSuccess?: (message: string, data?: any) => void;
+    /** Callback for error */
+    onError?: (message: string, error?: ApiError) => void;
+}
+interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
+    state: UseApiResourceState<T>;
+    actions: UseApiResourceActions<T, TCreate, TUpdate, TPathParams>;
     query: UseApiQuery;
+    setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
-
-export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type LogLevel, type Logger, type Middleware, type MiddlewareContext, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiQuery, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+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 };