api-core-lib 11.11.10 → 12.0.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,98 @@ 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 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.
+ */
+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 for the resource (e.g., '/users'). */
+    endpoint: string;
+    /** 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.
+ */
+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 +589,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
@@ -449,11 +450,98 @@ 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 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.
+ */
+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 for the resource (e.g., '/users'). */
+    endpoint: string;
+    /** 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.
+ */
+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 +589,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 };