api-core-lib 12.5.0 → 12.6.4

package/dist/index.d.mts

@@ -155,8 +155,11 @@ interface UseApiConfig<T> {
     refetchAfterChange?: boolean;
     /** A default `RequestConfig` to apply to all GET requests made by the hook. */
     requestConfig?: RequestConfig;
-    encodeQuery?: boolean;
+    /**
+     * [NEW] كائن يحتوي على قيم المتغيرات في قالب المسار.
+     */
     pathParams?: Record<string, string | number>;
+    encodeQuery?: boolean;
     /** Callback function executed on a successful action. */
     onSuccess?: (message: string, data?: T) => void;
     /** Callback function executed on a failed action. */
@@ -257,7 +260,7 @@ type UseApiState<T> = StandardResponse<T>;
  * @template T The type of the data entity being managed.
  */
 interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
-    fetch: () => Promise<void>;
+    fetch: (querryOptions?: QueryOptions) => 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>>;
@@ -320,6 +323,7 @@ interface UseApiModuleOptions {
     staleTime?: number;
     cacheTime?: number;
     refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
 }
 interface ActionState<TOutput> {
     data: TOutput | null;
@@ -327,6 +331,7 @@ interface ActionState<TOutput> {
     loading: boolean;
     success: boolean;
     called: boolean;
+    response: StandardResponse<TOutput> | null;
 }
 /**
  * The unified object for a single action, containing its state, executor, and controls.
@@ -378,13 +383,16 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
+interface BuildQueryOptions {
+    encode?: boolean;
+}
 /**
- * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
- * يتعامل مع البارامترات القياسية والمخصصة.
- * @param query - كائن من نوع QueryOptions.
+ * يبني سلسلة استعلام (query string) من كائن الخيارات.
+ * @param options - كائن خيارات الاستعلام (فلترة, ترتيب, ...).
+ * @param config - إعدادات إضافية مثل التحكم في التشفير.
  * @returns سلسلة استعلام جاهزة للإضافة للرابط.
  */
-declare function buildPaginateQuery(query: QueryOptions): string;
+declare function buildPaginateQuery(options: QueryOptions, config?: BuildQueryOptions): string;
 
 /**
  * Defines a single custom API action.
@@ -502,8 +510,17 @@ interface UseApiRecordActions<T> {
  * @template T The data type of the record.
  */
 interface UseApiRecordConfig<T> {
-    /** The base API endpoint for the resource (e.g., '/users'). */
+    /**
+     * The base API endpoint template for the resource.
+     * Can contain placeholders like `{endpointName}`.
+     * @example 'v1/dynamic/{endpointName}'
+     */
     endpoint: string;
+    /**
+     * An object containing key-value pairs to replace placeholders in the endpoint template.
+     * @example { endpointName: 'products' }
+     */
+    pathParams?: Record<string, string | number>;
     /** The unique identifier of the record to fetch or modify. */
     recordId?: string | number | null;
     /** Optional initial data to populate the state before the first fetch is complete. */
@@ -535,7 +552,7 @@ interface UseApiRecordReturn<T> {
 /**
  * A React hook for managing the lifecycle of a single API resource (a record).
  * It handles fetching, updating, replacing, and deleting a record, while managing
- * loading, error, and data states.
+ * loading, error, and data states. It supports dynamic path parameters for flexible API routing.
  *
  * @template T The data type of the record being managed.
  * @param {AxiosInstance} axiosInstance - The configured Axios instance for making API calls.

package/dist/index.d.ts

@@ -155,8 +155,11 @@ interface UseApiConfig<T> {
     refetchAfterChange?: boolean;
     /** A default `RequestConfig` to apply to all GET requests made by the hook. */
     requestConfig?: RequestConfig;
-    encodeQuery?: boolean;
+    /**
+     * [NEW] كائن يحتوي على قيم المتغيرات في قالب المسار.
+     */
     pathParams?: Record<string, string | number>;
+    encodeQuery?: boolean;
     /** Callback function executed on a successful action. */
     onSuccess?: (message: string, data?: T) => void;
     /** Callback function executed on a failed action. */
@@ -257,7 +260,7 @@ type UseApiState<T> = StandardResponse<T>;
  * @template T The type of the data entity being managed.
  */
 interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
-    fetch: () => Promise<void>;
+    fetch: (querryOptions?: QueryOptions) => 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>>;
@@ -320,6 +323,7 @@ interface UseApiModuleOptions {
     staleTime?: number;
     cacheTime?: number;
     refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
 }
 interface ActionState<TOutput> {
     data: TOutput | null;
@@ -327,6 +331,7 @@ interface ActionState<TOutput> {
     loading: boolean;
     success: boolean;
     called: boolean;
+    response: StandardResponse<TOutput> | null;
 }
 /**
  * The unified object for a single action, containing its state, executor, and controls.
@@ -378,13 +383,16 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
+interface BuildQueryOptions {
+    encode?: boolean;
+}
 /**
- * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
- * يتعامل مع البارامترات القياسية والمخصصة.
- * @param query - كائن من نوع QueryOptions.
+ * يبني سلسلة استعلام (query string) من كائن الخيارات.
+ * @param options - كائن خيارات الاستعلام (فلترة, ترتيب, ...).
+ * @param config - إعدادات إضافية مثل التحكم في التشفير.
  * @returns سلسلة استعلام جاهزة للإضافة للرابط.
  */
-declare function buildPaginateQuery(query: QueryOptions): string;
+declare function buildPaginateQuery(options: QueryOptions, config?: BuildQueryOptions): string;
 
 /**
  * Defines a single custom API action.
@@ -502,8 +510,17 @@ interface UseApiRecordActions<T> {
  * @template T The data type of the record.
  */
 interface UseApiRecordConfig<T> {
-    /** The base API endpoint for the resource (e.g., '/users'). */
+    /**
+     * The base API endpoint template for the resource.
+     * Can contain placeholders like `{endpointName}`.
+     * @example 'v1/dynamic/{endpointName}'
+     */
     endpoint: string;
+    /**
+     * An object containing key-value pairs to replace placeholders in the endpoint template.
+     * @example { endpointName: 'products' }
+     */
+    pathParams?: Record<string, string | number>;
     /** The unique identifier of the record to fetch or modify. */
     recordId?: string | number | null;
     /** Optional initial data to populate the state before the first fetch is complete. */
@@ -535,7 +552,7 @@ interface UseApiRecordReturn<T> {
 /**
  * A React hook for managing the lifecycle of a single API resource (a record).
  * It handles fetching, updating, replacing, and deleting a record, while managing
- * loading, error, and data states.
+ * loading, error, and data states. It supports dynamic path parameters for flexible API routing.
  *
  * @template T The data type of the record being managed.
  * @param {AxiosInstance} axiosInstance - The configured Axios instance for making API calls.