api-core-lib 11.0.0 → 11.2.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
@@ -449,11 +450,134 @@ 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): ModuleActions<TModule>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
+
+/**
+ * Represents a standardized API error structure.
+ */
+interface ApiErrorRecord {
+    /** The HTTP status code of the error response (e.g., 404, 500). */
+    status?: number;
+    /** A user-friendly error message. */
+    message: string;
+    /** A dictionary of validation errors, where the key is the field name. */
+    validationErrors?: Record<string, string[]>;
+}
+/**
+ * Represents the standard wrapper for all API responses processed by the client.
+ * @template T The data type of the successful response payload.
+ */
+interface StandardResponseRecord<T> {
+    /** The data payload from the API on success, or null on failure. */
+    data: T | null;
+    /** A boolean indicating if the request was successful (e.g., status 2xx). */
+    success: boolean;
+    /** A boolean indicating if the request is currently in flight. */
+    loading: boolean;
+    /** An ApiError object if the request failed, otherwise null. */
+    error: ApiErrorRecord | null;
+    /** An optional success or error message from the API. */
+    message?: string;
+    /** Validation errors returned from the API (typically on 422 Unprocessable Entity responses). */
+    validationErrors?: Record<string, string[]>;
+    /** The raw Axios response object for advanced use cases. */
+    rawResponse?: AxiosResponse<T>;
+}
+/**
+ * The state object managed by the `useApiRecord` hook.
+ * It mirrors the StandardResponseRecord but separates the `loading` flag for more granular control.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordState<T> extends Omit<StandardResponseRecord<T>, 'loading'> {
+    /** A boolean indicating if a fetch or action is currently in progress. */
+    loading: boolean;
+}
+/**
+ * The set of functions provided by the hook to interact with the API record.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordActions<T> {
+    /**
+     * Manually re-fetches the record from the API.
+     * @returns A promise that resolves with the API response.
+     */
+    fetch: () => Promise<StandardResponseRecord<T>>;
+    /**
+     * Updates parts of the record using an HTTP PATCH request.
+     * @param updatedItem - An object containing only the fields to be updated.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response.
+     */
+    update: (updatedItem: Partial<T>, options?: AxiosRequestConfig) => Promise<StandardResponseRecord<T>>;
+    /**
+     * Replaces the entire record with new data using an HTTP PUT request.
+     * @param item - The complete new object for the record.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response.
+     */
+    put: (item: T, options?: AxiosRequestConfig) => Promise<StandardResponseRecord<T>>;
+    /**
+     * Deletes the record from the API using an HTTP DELETE request.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response (data will be null).
+     */
+    remove: (options?: AxiosRequestConfig) => Promise<StandardResponseRecord<null>>;
+    /** Resets the hook's state to its initial value. */
+    resetState: () => void;
+}
+/**
+ * The configuration object for the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordConfig<T> {
+    /** The base API endpoint for the resource (without the ID). Example: '/users' */
+    endpoint: string;
+    /** The unique identifier of the record to fetch, update, or delete. */
+    recordId?: string | number | null;
+    /** Optional initial data to display before the first fetch completes. Useful for optimistic UI. */
+    initialData?: T | null;
+    /** If `true`, the hook will automatically fetch the data on mount. Defaults to `true`. */
+    enabled?: boolean;
+    /** If `true`, the record will be re-fetched after any successful mutation (update, put, remove). Defaults to `true`. */
+    refetchOnSuccess?: boolean;
+    /** Additional Axios request config to be merged with every request made by the hook. */
+    requestConfig?: AxiosRequestConfig;
+    /** A callback function that fires upon any successful API operation. */
+    onSuccess?: (message: string, data?: T | null) => void;
+    /** A callback function that fires upon any failed API operation. */
+    onError?: (message: string, error?: ApiErrorRecord) => 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 and data. */
+    state: UseApiRecordState<T>;
+    /** A collection of functions to perform operations on the record. */
+    actions: UseApiRecordActions<T>;
+    /** A React state dispatcher to manually set the state (for advanced use cases). */
+    setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
+}
+
+/**
+ * A robust custom hook to manage the lifecycle of a single API record (fetch, update, delete).
+ * It handles state, loading, errors, and provides actions to interact with the API.
+ * This version is fortified against common issues like race conditions and infinite loops.
+ *
+ * @template T The expected type of the API record.
+ * @param {AxiosInstance} axiosInstance - A pre-configured Axios instance.
+ * @param {UseApiRecordConfig<T>} config - Configuration object for the hook.
+ * @returns {UseApiRecordReturn<T>} An object containing the state, setState function, and actions.
+ */
+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 +625,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 ApiErrorRecord, 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 StandardResponseRecord, 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
@@ -449,11 +450,134 @@ 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): ModuleActions<TModule>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
+
+/**
+ * Represents a standardized API error structure.
+ */
+interface ApiErrorRecord {
+    /** The HTTP status code of the error response (e.g., 404, 500). */
+    status?: number;
+    /** A user-friendly error message. */
+    message: string;
+    /** A dictionary of validation errors, where the key is the field name. */
+    validationErrors?: Record<string, string[]>;
+}
+/**
+ * Represents the standard wrapper for all API responses processed by the client.
+ * @template T The data type of the successful response payload.
+ */
+interface StandardResponseRecord<T> {
+    /** The data payload from the API on success, or null on failure. */
+    data: T | null;
+    /** A boolean indicating if the request was successful (e.g., status 2xx). */
+    success: boolean;
+    /** A boolean indicating if the request is currently in flight. */
+    loading: boolean;
+    /** An ApiError object if the request failed, otherwise null. */
+    error: ApiErrorRecord | null;
+    /** An optional success or error message from the API. */
+    message?: string;
+    /** Validation errors returned from the API (typically on 422 Unprocessable Entity responses). */
+    validationErrors?: Record<string, string[]>;
+    /** The raw Axios response object for advanced use cases. */
+    rawResponse?: AxiosResponse<T>;
+}
+/**
+ * The state object managed by the `useApiRecord` hook.
+ * It mirrors the StandardResponseRecord but separates the `loading` flag for more granular control.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordState<T> extends Omit<StandardResponseRecord<T>, 'loading'> {
+    /** A boolean indicating if a fetch or action is currently in progress. */
+    loading: boolean;
+}
+/**
+ * The set of functions provided by the hook to interact with the API record.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordActions<T> {
+    /**
+     * Manually re-fetches the record from the API.
+     * @returns A promise that resolves with the API response.
+     */
+    fetch: () => Promise<StandardResponseRecord<T>>;
+    /**
+     * Updates parts of the record using an HTTP PATCH request.
+     * @param updatedItem - An object containing only the fields to be updated.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response.
+     */
+    update: (updatedItem: Partial<T>, options?: AxiosRequestConfig) => Promise<StandardResponseRecord<T>>;
+    /**
+     * Replaces the entire record with new data using an HTTP PUT request.
+     * @param item - The complete new object for the record.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response.
+     */
+    put: (item: T, options?: AxiosRequestConfig) => Promise<StandardResponseRecord<T>>;
+    /**
+     * Deletes the record from the API using an HTTP DELETE request.
+     * @param options - Optional Axios request configuration to merge with the default config.
+     * @returns A promise that resolves with the API response (data will be null).
+     */
+    remove: (options?: AxiosRequestConfig) => Promise<StandardResponseRecord<null>>;
+    /** Resets the hook's state to its initial value. */
+    resetState: () => void;
+}
+/**
+ * The configuration object for the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordConfig<T> {
+    /** The base API endpoint for the resource (without the ID). Example: '/users' */
+    endpoint: string;
+    /** The unique identifier of the record to fetch, update, or delete. */
+    recordId?: string | number | null;
+    /** Optional initial data to display before the first fetch completes. Useful for optimistic UI. */
+    initialData?: T | null;
+    /** If `true`, the hook will automatically fetch the data on mount. Defaults to `true`. */
+    enabled?: boolean;
+    /** If `true`, the record will be re-fetched after any successful mutation (update, put, remove). Defaults to `true`. */
+    refetchOnSuccess?: boolean;
+    /** Additional Axios request config to be merged with every request made by the hook. */
+    requestConfig?: AxiosRequestConfig;
+    /** A callback function that fires upon any successful API operation. */
+    onSuccess?: (message: string, data?: T | null) => void;
+    /** A callback function that fires upon any failed API operation. */
+    onError?: (message: string, error?: ApiErrorRecord) => 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 and data. */
+    state: UseApiRecordState<T>;
+    /** A collection of functions to perform operations on the record. */
+    actions: UseApiRecordActions<T>;
+    /** A React state dispatcher to manually set the state (for advanced use cases). */
+    setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
+}
+
+/**
+ * A robust custom hook to manage the lifecycle of a single API record (fetch, update, delete).
+ * It handles state, loading, errors, and provides actions to interact with the API.
+ * This version is fortified against common issues like race conditions and infinite loops.
+ *
+ * @template T The expected type of the API record.
+ * @param {AxiosInstance} axiosInstance - A pre-configured Axios instance.
+ * @param {UseApiRecordConfig<T>} config - Configuration object for the hook.
+ * @returns {UseApiRecordReturn<T>} An object containing the state, setState function, and actions.
+ */
+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 +625,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 ApiErrorRecord, 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 StandardResponseRecord, 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 };