api-core-lib 7.7.6 → 8.7.7

package/dist/index.d.mts

@@ -127,7 +127,7 @@ interface QueryOptions {
 /**
  * Defines additional options for action methods like create, update, or delete.
  */
-interface ActionOptions {
+interface ActionOptions extends RequestConfig {
     /**
      * Overrides the default endpoint for a specific action. Useful for specialized routes.
      * @example update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
@@ -146,7 +146,7 @@ interface UseApiConfig<T> {
     /** The base API endpoint for the resource (e.g., '/users'). */
     endpoint: string;
     /** Initial data to populate the state before the first fetch. */
-    initialData?: T | T[];
+    initialData?: T | null;
     /** Default query options to use for the initial fetch. */
     initialQuery?: QueryOptions;
     /** If false, the hook will not fetch data automatically on mount. */
@@ -259,20 +259,20 @@ interface ApiClientConfig {
  */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
-type CrudRequestConfig = RequestConfig & ActionOptions;
-/**
- * دالة مصنع (Factory Function) لإنشاء مجموعة خدمات API قابلة لإعادة الاستخدام لنقطة نهاية (endpoint) محددة.
- * توفر عمليات CRUD كاملة بالإضافة إلى ميزات متقدمة مثل الحذف الجماعي ورفع الملفات.
- */
-declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
-    get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
-    getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    put: (id: string, data: T, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
-    bulkDelete: (ids: string[], config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
-    upload: (file: File, additionalData?: Record<string, any>, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
+/**
+ * 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,
+ * with intelligent, dynamic URL building.
+ */
+declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint: string): {
+    get: (id?: string | number, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T>>;
+    post: (data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    put: (id: string | number, data: T, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    patch: (id: string | number, data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    remove: (id: string | number, config?: ActionOptions) => Promise<StandardResponse<any>>;
+    bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
+    upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -361,38 +361,19 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
  * 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 | T[]>;
+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> {
-    /**
-     * Manually triggers a refetch of the hook's primary data using the current query options.
-     * This is useful for manual refresh buttons.
-     */
-    /**
-     * Fetches data from an arbitrary path, independent of the hook's main state.
-     * This is useful for one-off requests that shouldn't affect the primary data.
-     * @param path The relative or absolute path to fetch from.
-     * @param pathParams Optional parameters to fill dynamic parts of the path.
-     * @param options Optional Axios request configuration.
-     * @returns A promise that resolves with the standard API response.
-     */
-    fetch: (options?: QueryOptions) => Promise<void>;
-    /** Creates a new item. */
-    create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Replaces an entire item. */
-    put: (id: string | number, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Partially updates an item. */
-    update: (id: string | number, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Deletes an item. */
+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>>;
-    /** Deletes multiple items in a single request. */
     bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    /** Uploads a file, optionally with additional data. */
-    upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
 }
 /**
  * A collection of functions and properties for controlling the query parameters
@@ -427,18 +408,13 @@ interface UseApiQuery {
  * @template T The type of the data entity being managed.
  */
 interface UseApiReturn<T> {
-    /** The current state of the API request (data, loading, error). */
     state: UseApiState<T>;
-    /** A function to manually set the state. Use with caution. */
     setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
-    /** An object containing all available data manipulation actions (create, update, delete, etc.). */
     actions: UseApiActions<T>;
-    /** An object for controlling the query parameters for data fetching. */
     query: UseApiQuery;
 }
 
-declare function useApi<T extends {
-    id?: string | number;
-}>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+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 };

package/dist/index.d.ts

@@ -127,7 +127,7 @@ interface QueryOptions {
 /**
  * Defines additional options for action methods like create, update, or delete.
  */
-interface ActionOptions {
+interface ActionOptions extends RequestConfig {
     /**
      * Overrides the default endpoint for a specific action. Useful for specialized routes.
      * @example update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
@@ -146,7 +146,7 @@ interface UseApiConfig<T> {
     /** The base API endpoint for the resource (e.g., '/users'). */
     endpoint: string;
     /** Initial data to populate the state before the first fetch. */
-    initialData?: T | T[];
+    initialData?: T | null;
     /** Default query options to use for the initial fetch. */
     initialQuery?: QueryOptions;
     /** If false, the hook will not fetch data automatically on mount. */
@@ -259,20 +259,20 @@ interface ApiClientConfig {
  */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
-type CrudRequestConfig = RequestConfig & ActionOptions;
-/**
- * دالة مصنع (Factory Function) لإنشاء مجموعة خدمات API قابلة لإعادة الاستخدام لنقطة نهاية (endpoint) محددة.
- * توفر عمليات CRUD كاملة بالإضافة إلى ميزات متقدمة مثل الحذف الجماعي ورفع الملفات.
- */
-declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
-    get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
-    getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    put: (id: string, data: T, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
-    bulkDelete: (ids: string[], config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
-    upload: (file: File, additionalData?: Record<string, any>, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
+/**
+ * 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,
+ * with intelligent, dynamic URL building.
+ */
+declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint: string): {
+    get: (id?: string | number, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T>>;
+    post: (data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    put: (id: string | number, data: T, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    patch: (id: string | number, data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    remove: (id: string | number, config?: ActionOptions) => Promise<StandardResponse<any>>;
+    bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
+    upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -361,38 +361,19 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
  * 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 | T[]>;
+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> {
-    /**
-     * Manually triggers a refetch of the hook's primary data using the current query options.
-     * This is useful for manual refresh buttons.
-     */
-    /**
-     * Fetches data from an arbitrary path, independent of the hook's main state.
-     * This is useful for one-off requests that shouldn't affect the primary data.
-     * @param path The relative or absolute path to fetch from.
-     * @param pathParams Optional parameters to fill dynamic parts of the path.
-     * @param options Optional Axios request configuration.
-     * @returns A promise that resolves with the standard API response.
-     */
-    fetch: (options?: QueryOptions) => Promise<void>;
-    /** Creates a new item. */
-    create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Replaces an entire item. */
-    put: (id: string | number, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Partially updates an item. */
-    update: (id: string | number, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-    /** Deletes an item. */
+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>>;
-    /** Deletes multiple items in a single request. */
     bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    /** Uploads a file, optionally with additional data. */
-    upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
 }
 /**
  * A collection of functions and properties for controlling the query parameters
@@ -427,18 +408,13 @@ interface UseApiQuery {
  * @template T The type of the data entity being managed.
  */
 interface UseApiReturn<T> {
-    /** The current state of the API request (data, loading, error). */
     state: UseApiState<T>;
-    /** A function to manually set the state. Use with caution. */
     setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
-    /** An object containing all available data manipulation actions (create, update, delete, etc.). */
     actions: UseApiActions<T>;
-    /** An object for controlling the query parameters for data fetching. */
     query: UseApiQuery;
 }
 
-declare function useApi<T extends {
-    id?: string | number;
-}>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+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 };