api-core-lib 11.11.10 → 12.1.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+import { Dispatch, SetStateAction } from 'react';
 
 /**
  * @file src/types.ts
@@ -154,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. */
@@ -377,13 +381,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.
@@ -449,11 +456,112 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * 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.
+ * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API،
+ * مع فصل تام بين الدوال المستقرة والحالات المتغيرة لمنع الحلقات اللانهائية.
+ */
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
+
+/**
+ * Represents the internal state of the `useApiRecord` hook.
+ * It mirrors the `StandardResponse` structure, which is the unified response format
+ * used across the library.
+ * @template T The data type of the record.
+ */
+type UseApiRecordState<T> = StandardResponse<T>;
+/**
+ * Defines the action methods provided by the `useApiRecord` hook to interact with
+ * a single API resource.
+ * @template T The data type of the record.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+interface UseApiRecordActions<T> {
+    /**
+     * Manually fetches or refetches the record from the API.
+     */
+    fetch: () => Promise<void>;
+    /**
+     * Partially updates the record using an HTTP PATCH request.
+     * @param updatedItem An object containing the fields to update.
+     * @param options Additional request options, allowing overrides for this specific action.
+     * @returns A promise that resolves to the standard response object for the updated record.
+     */
+    update: (updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Replaces the entire record with a new one using an HTTP PUT request.
+     * @param item The complete new record object.
+     * @param options Additional request options.
+     * @returns A promise that resolves to the standard response object for the replaced record.
+     */
+    put: (item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Deletes the record using an HTTP DELETE request.
+     * @param options Additional request options.
+     * @returns A promise that resolves to a standard response object with a null data payload.
+     */
+    remove: (options?: ActionOptions) => Promise<StandardResponse<null>>;
+    /**
+     * Resets the hook's state to its initial value.
+     */
+    resetState: () => void;
+}
+/**
+ * Defines the configuration options for the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordConfig<T> {
+    /**
+     * 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. */
+    initialData?: T | null;
+    /** If `false`, the hook will not automatically fetch data on mount. Defaults to `true`. */
+    enabled?: boolean;
+    /** If `true`, the record will be refetched after a successful `update`, `put`, or `remove` action. Defaults to `true`. */
+    refetchAfterChange?: boolean;
+    /** Default `RequestConfig` to apply to the initial GET request made by the hook. */
+    requestConfig?: RequestConfig;
+    /** A callback function executed on a successful API action. */
+    onSuccess?: (message: string, data?: any) => void;
+    /** A callback function executed on a failed API action. */
+    onError?: (message: string, error?: ApiError) => void;
+}
+/**
+ * The return value of the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordReturn<T> {
+    /** The current state of the API request, including data, loading, and error status. */
+    state: UseApiRecordState<T>;
+    /** Action methods to manipulate the record. */
+    actions: UseApiRecordActions<T>;
+    /** A React dispatch function to manually set the hook's state. Use with caution. */
+    setState: Dispatch<SetStateAction<UseApiRecordState<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. 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.
+ * @param {UseApiRecordConfig<T>} config - Configuration options for the hook.
+ * @returns {UseApiRecordReturn<T>} An object containing the state, actions, and setState function.
+ */
+declare function useApiRecord<T>(axiosInstance: AxiosInstance, config: UseApiRecordConfig<T>): UseApiRecordReturn<T>;
+
+type EffectCallback = () => (void | (() => void));
+type DependencyList = readonly any[];
+declare function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList): void;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -501,4 +609,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 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 UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+import { Dispatch, SetStateAction } from 'react';
 
 /**
  * @file src/types.ts
@@ -154,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. */
@@ -377,13 +381,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.
@@ -449,11 +456,112 @@ declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiErro
 declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
 /**
- * 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.
+ * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API،
+ * مع فصل تام بين الدوال المستقرة والحالات المتغيرة لمنع الحلقات اللانهائية.
+ */
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
+
+/**
+ * Represents the internal state of the `useApiRecord` hook.
+ * It mirrors the `StandardResponse` structure, which is the unified response format
+ * used across the library.
+ * @template T The data type of the record.
+ */
+type UseApiRecordState<T> = StandardResponse<T>;
+/**
+ * Defines the action methods provided by the `useApiRecord` hook to interact with
+ * a single API resource.
+ * @template T The data type of the record.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+interface UseApiRecordActions<T> {
+    /**
+     * Manually fetches or refetches the record from the API.
+     */
+    fetch: () => Promise<void>;
+    /**
+     * Partially updates the record using an HTTP PATCH request.
+     * @param updatedItem An object containing the fields to update.
+     * @param options Additional request options, allowing overrides for this specific action.
+     * @returns A promise that resolves to the standard response object for the updated record.
+     */
+    update: (updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Replaces the entire record with a new one using an HTTP PUT request.
+     * @param item The complete new record object.
+     * @param options Additional request options.
+     * @returns A promise that resolves to the standard response object for the replaced record.
+     */
+    put: (item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Deletes the record using an HTTP DELETE request.
+     * @param options Additional request options.
+     * @returns A promise that resolves to a standard response object with a null data payload.
+     */
+    remove: (options?: ActionOptions) => Promise<StandardResponse<null>>;
+    /**
+     * Resets the hook's state to its initial value.
+     */
+    resetState: () => void;
+}
+/**
+ * Defines the configuration options for the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordConfig<T> {
+    /**
+     * 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. */
+    initialData?: T | null;
+    /** If `false`, the hook will not automatically fetch data on mount. Defaults to `true`. */
+    enabled?: boolean;
+    /** If `true`, the record will be refetched after a successful `update`, `put`, or `remove` action. Defaults to `true`. */
+    refetchAfterChange?: boolean;
+    /** Default `RequestConfig` to apply to the initial GET request made by the hook. */
+    requestConfig?: RequestConfig;
+    /** A callback function executed on a successful API action. */
+    onSuccess?: (message: string, data?: any) => void;
+    /** A callback function executed on a failed API action. */
+    onError?: (message: string, error?: ApiError) => void;
+}
+/**
+ * The return value of the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordReturn<T> {
+    /** The current state of the API request, including data, loading, and error status. */
+    state: UseApiRecordState<T>;
+    /** Action methods to manipulate the record. */
+    actions: UseApiRecordActions<T>;
+    /** A React dispatch function to manually set the hook's state. Use with caution. */
+    setState: Dispatch<SetStateAction<UseApiRecordState<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. 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.
+ * @param {UseApiRecordConfig<T>} config - Configuration options for the hook.
+ * @returns {UseApiRecordReturn<T>} An object containing the state, actions, and setState function.
+ */
+declare function useApiRecord<T>(axiosInstance: AxiosInstance, config: UseApiRecordConfig<T>): UseApiRecordReturn<T>;
+
+type EffectCallback = () => (void | (() => void));
+type DependencyList = readonly any[];
+declare function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList): void;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -501,4 +609,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 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 UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect };