api-core-lib 5.5.5 → 6.6.5

package/dist/index.d.mts

@@ -1,5 +1,4 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
-import * as react from 'react';
 
 /**
  * @file src/types.ts
@@ -339,34 +338,84 @@ declare const cacheManager: CacheManager;
  */
 declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
+/**
+ * @file src/hooks/useApi.types.ts
+ * @description This file defines the professional, publicly-facing types
+ * returned by the `useApi` hook, providing a clean and stable contract for consumers.
+ */
+
+/**
+ * The primary state object managed by the `useApi` hook.
+ * 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[]>;
+/**
+ * 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> {
+    /** Fetches or refetches the list of data. */
+    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. */
+    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
+ * used for fetching data, such as pagination, sorting, and filtering.
+ */
+interface UseApiQuery {
+    /** The current query options state. */
+    options: QueryOptions;
+    /** A function to set the entire query options object at once. */
+    setOptions: React.Dispatch<React.SetStateAction<QueryOptions>>;
+    /** Sets the current page number and resets to the first page. */
+    setPage: (page: number) => void;
+    /** Sets the number of items per page and resets to the first page. */
+    setLimit: (limit: number) => void;
+    /** Sets the search term and resets to the first page. */
+    setSearchTerm: (search: string) => void;
+    /** Sets the sorting configuration. */
+    setSorting: (sortBy: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[]) => void;
+    /** Sets the filter object and resets to the first page. */
+    setFilters: (filter: Record<string, any>) => void;
+    /** Sets a single, custom query parameter and resets to the first page. */
+    setQueryParam: (key: string, value: any) => void;
+    /** Resets the query options to their initial state. */
+    reset: () => void;
+}
+/**
+ * The complete return type of the `useApi` hook.
+ * It encapsulates the state, actions, and query controls for a given API resource.
+ * @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>): {
-    state: StandardResponse<T | T[]>;
-    setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
-    actions: {
-        fetch: (options?: QueryOptions) => Promise<void>;
-        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        put: (id: string, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
-        bulkRemove: (ids: string[], options?: ActionOptions) => Promise<StandardResponse<any>>;
-        upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    };
-    query: {
-        options: QueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
-        setPage: (page: number) => void;
-        setLimit: (limit: number) => void;
-        setSearchTerm: (search: string) => void;
-        setSorting: (sortBy: {
-            key: string;
-            direction: "asc" | "desc";
-        }[]) => void;
-        setFilters: (filter: Record<string, any>) => void;
-        setQueryParam: (key: string, value: any) => void;
-        reset: () => void;
-    };
-};
+}>(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 UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+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

@@ -1,5 +1,4 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
-import * as react from 'react';
 
 /**
  * @file src/types.ts
@@ -339,34 +338,84 @@ declare const cacheManager: CacheManager;
  */
 declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
+/**
+ * @file src/hooks/useApi.types.ts
+ * @description This file defines the professional, publicly-facing types
+ * returned by the `useApi` hook, providing a clean and stable contract for consumers.
+ */
+
+/**
+ * The primary state object managed by the `useApi` hook.
+ * 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[]>;
+/**
+ * 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> {
+    /** Fetches or refetches the list of data. */
+    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. */
+    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
+ * used for fetching data, such as pagination, sorting, and filtering.
+ */
+interface UseApiQuery {
+    /** The current query options state. */
+    options: QueryOptions;
+    /** A function to set the entire query options object at once. */
+    setOptions: React.Dispatch<React.SetStateAction<QueryOptions>>;
+    /** Sets the current page number and resets to the first page. */
+    setPage: (page: number) => void;
+    /** Sets the number of items per page and resets to the first page. */
+    setLimit: (limit: number) => void;
+    /** Sets the search term and resets to the first page. */
+    setSearchTerm: (search: string) => void;
+    /** Sets the sorting configuration. */
+    setSorting: (sortBy: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[]) => void;
+    /** Sets the filter object and resets to the first page. */
+    setFilters: (filter: Record<string, any>) => void;
+    /** Sets a single, custom query parameter and resets to the first page. */
+    setQueryParam: (key: string, value: any) => void;
+    /** Resets the query options to their initial state. */
+    reset: () => void;
+}
+/**
+ * The complete return type of the `useApi` hook.
+ * It encapsulates the state, actions, and query controls for a given API resource.
+ * @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>): {
-    state: StandardResponse<T | T[]>;
-    setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
-    actions: {
-        fetch: (options?: QueryOptions) => Promise<void>;
-        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        put: (id: string, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
-        bulkRemove: (ids: string[], options?: ActionOptions) => Promise<StandardResponse<any>>;
-        upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    };
-    query: {
-        options: QueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
-        setPage: (page: number) => void;
-        setLimit: (limit: number) => void;
-        setSearchTerm: (search: string) => void;
-        setSorting: (sortBy: {
-            key: string;
-            direction: "asc" | "desc";
-        }[]) => void;
-        setFilters: (filter: Record<string, any>) => void;
-        setQueryParam: (key: string, value: any) => void;
-        reset: () => void;
-    };
-};
+}>(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 UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+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 };