@krymskyimaksym/react-api-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @krymskyimaksym/react-api-client
+
+A lightweight, type-safe API client for React and React Native with built-in hooks for queries, mutations, and pagination.
+
+## Features
+
+- 🎯 **Type-Safe**: Full TypeScript support with generic types
+- 🪝 **React Hooks**: Built-in hooks for easy data fetching
+- 📦 **Lightweight**: Zero dependencies (except React)
+- 🔄 **Flexible**: Works with any HTTP client (fetch, axios, etc.)
+- 🚀 **Modern**: ESM and CJS support
+- 🎨 **Customizable**: Inject your own HTTP client and error handlers
+
+## Installation
+
+```bash
+npm install @krymskyimaksym/react-api-client
+# or
+yarn add @krymskyimaksym/react-api-client
+# or
+pnpm add @krymskyimaksym/react-api-client
+```
+
+## Quick Start
+
+### 1. Configure the API Client
+
+First, configure the global API client with your HTTP client and error handlers:
+
+```typescript
+import { configureApiClient } from '@krymskyimaksym/react-api-client';
+import { router } from 'expo-router'; // or your router
+
+// Create your HTTP client instance
+const httpClient = {
+  async get(url, config) {
+    const response = await fetch(url);
+    return response.json();
+  },
+  async request(url, config) {
+    const response = await fetch(url, {
+      method: config.method,
+      body: JSON.stringify(config.data),
+      headers: { 'Content-Type': 'application/json' },
+    });
+    return response.json();
+  },
+};
+
+// Configure once at app startup
+configureApiClient({
+  httpClient,
+  onUnauthorized: () => router.replace('/login'),
+});
+```
+
+### 2. Define Your API Endpoints
+
+```typescript
+import apiClient, { apiMutation, apiPaginate } from '@krymskyimaksym/react-api-client';
+
+// Types
+type User = {
+  id: string;
+  name: string;
+  email: string;
+};
+
+type CreateUserRequest = {
+  name: string;
+  email: string;
+};
+
+// GET endpoint
+export const userApi = apiClient<User, { id: string }>('/api/users/:id');
+
+// POST endpoint
+export const createUserApi = apiMutation<User, CreateUserRequest>(
+  '/api/users',
+  { method: 'POST' }
+);
+
+// Paginated endpoint
+export const usersListApi = apiPaginate<
+  { data: User[]; total: number },
+  User[]
+>('/api/users');
+```
+
+### 3. Use in Components
+
+#### Query (GET)
+
+```typescript
+function UserProfile({ userId }: { userId: string }) {
+  const { data, isLoading, error, refetch } = userApi.useFetch(
+    { id: userId },
+    {
+      onSuccess: (data) => console.log('User loaded:', data),
+      onError: (error) => console.error('Error:', error),
+    }
+  );
+
+  if (isLoading) return <LoadingSpinner />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return (
+    <div>
+      <h1>{data?.name}</h1>
+      <button onClick={refetch}>Refresh</button>
+    </div>
+  );
+}
+```
+
+#### Mutation (POST/PUT/PATCH/DELETE)
+
+```typescript
+function CreateUserForm() {
+  const { mutate, isLoading, isSuccess, error } = createUserApi.useMutation({
+    onSuccess: (data) => {
+      console.log('User created:', data);
+      // Navigate or update UI
+    },
+    onError: (error) => {
+      console.error('Failed to create user:', error);
+    },
+  });
+
+  const handleSubmit = (values: CreateUserRequest) => {
+    mutate(values);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? 'Creating...' : 'Create User'}
+      </button>
+      {isSuccess && <p>User created successfully!</p>}
+      {error && <p>Error: {error.message}</p>}
+    </form>
+  );
+}
+```
+
+#### Pagination
+
+```typescript
+function UsersList() {
+  const {
+    data,
+    isLoading,
+    hasNextPage,
+    fetchNextPage,
+    isFetchingNextPage,
+  } = usersListApi.usePaginate();
+
+  return (
+    <div>
+      {data.map(user => (
+        <UserCard key={user.id} user={user} />
+      ))}
+
+      {hasNextPage && (
+        <button onClick={fetchNextPage} disabled={isFetchingNextPage}>
+          {isFetchingNextPage ? 'Loading...' : 'Load More'}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `configureApiClient(config)`
+
+Configure the global API client. Must be called before using any API functions.
+
+```typescript
+type ApiClientConfig = {
+  httpClient: IHttpClient;
+  onUnauthorized?: () => void | Promise<void>;
+};
+```
+
+### `apiClient<ResponseType, RequestParamsType>(endpoint, config)`
+
+Creates a query client for GET requests.
+
+**Returns:**
+- `fetch(params)` - Async function to fetch data
+- `useFetch(params, options)` - React hook for data fetching
+
+### `apiMutation<ResponseType, RequestParamsType>(endpoint, config)`
+
+Creates a mutation client for POST/PUT/PATCH/DELETE requests.
+
+**Returns:**
+- `mutate(params)` - Async function to execute mutation
+- `useMutation(options)` - React hook for mutations
+
+### `apiPaginate<ResponseType, DataArrayType>(endpoint, config, options)`
+
+Creates a paginated query client.
+
+**Returns:**
+- `usePaginate(params, options)` - React hook for paginated data
+
+## Advanced Usage
+
+### Dynamic Endpoints
+
+```typescript
+const userApi = apiClient<User, { id: string }>(
+  (params) => `/api/users/${params.id}`
+);
+```
+
+### Custom Data Extractors for Pagination
+
+```typescript
+const usersApi = apiPaginate<
+  { users: User[]; count: number },
+  User[]
+>(
+  '/api/users',
+  { method: 'GET' },
+  {
+    dataExtractor: (response) => response.users,
+    totalExtractor: (response) => response.count,
+  }
+);
+```
+
+### Imperative API Calls
+
+```typescript
+// Without hooks
+const response = await userApi.fetch({ id: '123' });
+if (response.status) {
+  console.log('Success:', response);
+} else {
+  console.error('Error:', response.message);
+}
+```
+
+## HTTP Client Interface
+
+Your HTTP client must implement this interface:
+
+```typescript
+interface IHttpClient {
+  get<T>(url: string, config?: RequestConfig): Promise<T>;
+  request<T>(url: string, config: RequestConfig): Promise<T>;
+}
+```
+
+### Example with Axios
+
+```typescript
+import axios from 'axios';
+
+const httpClient = {
+  get: (url, config) => axios.get(url, config).then(res => res.data),
+  request: (url, config) => axios(url, config).then(res => res.data),
+};
+```
+
+### Example with Fetch
+
+```typescript
+const httpClient = {
+  async get(url, config) {
+    const params = new URLSearchParams(config?.params);
+    const response = await fetch(`${url}?${params}`);
+    if (!response.ok) throw new Error('Request failed');
+    return response.json();
+  },
+  async request(url, config) {
+    const response = await fetch(url, {
+      method: config.method,
+      headers: { 'Content-Type': 'application/json' },
+      body: config.data ? JSON.stringify(config.data) : undefined,
+    });
+    if (!response.ok) throw new Error('Request failed');
+    return response.json();
+  },
+};
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Support
+
+For issues and questions, please use [GitHub Issues](https://github.com/krymskyimaksym/react-api-client/issues).

package/dist/index.d.mts

@@ -0,0 +1,152 @@
+type RequestConfig = {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    requestParams?: Record<string, string>;
+};
+type ResponseWrapper<DataType, ErrorsType = unknown> = {
+    status: boolean;
+    message?: string;
+    errors?: ErrorsType;
+} & DataType;
+type UseFetchOptions<T> = {
+    enabled?: boolean;
+    refetchOnMount?: boolean;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+};
+type UseFetchResult<T> = {
+    data: T | null;
+    isLoading: boolean;
+    isRefetching: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+type UsePaginateOptions<T> = {
+    enabled?: boolean;
+    initialPage?: number;
+    initialLimit?: number;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+};
+type UsePaginateResult<TData extends unknown[]> = {
+    data: TData;
+    currentPage: number;
+    totalPages: number | null;
+    total: number | null;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isLoading: boolean;
+    isFetchingNextPage: boolean;
+    error: Error | null;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+    reset: () => void;
+};
+type UseMutationOptions<TData, TVariables> = {
+    onMutate?: (variables: TVariables) => void | Promise<void>;
+    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
+    onError?: (error: Error, variables: TVariables) => void | Promise<void>;
+    onSettled?: (data: TData | null, error: Error | null, variables: TVariables) => void | Promise<void>;
+};
+type UseMutationResult<TData, TVariables> = {
+    data: TData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    reset: () => void;
+};
+interface IHttpClient {
+    get<T>(url: string, config?: {
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    request<T>(url: string, config: {
+        method?: string;
+        data?: Record<string, unknown>;
+    }): Promise<T>;
+}
+type ApiClientConfig = {
+    httpClient: IHttpClient;
+    onUnauthorized?: () => void | Promise<void>;
+};
+type ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
+    fetch: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
+    useFetch: (params?: RequestParamsType, options?: UseFetchOptions<ResponseWrapper<ResponseType, ErrorResponseType>>) => UseFetchResult<ResponseWrapper<ResponseType, ErrorResponseType>>;
+};
+type ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
+    mutate: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
+    useMutation: (options?: UseMutationOptions<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>) => UseMutationResult<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>;
+};
+type ApiPaginateReturn<ResponseType, RequestParamsType, DataArrayType extends unknown[], ErrorResponseType = unknown> = {
+    usePaginate: (params?: Omit<RequestParamsType, 'page' | 'limit'>, options?: UsePaginateOptions<ResponseWrapper<ResponseType, ErrorResponseType>>) => UsePaginateResult<DataArrayType>;
+};
+
+/**
+ * Configure the API client globally
+ * @param config - API client configuration
+ *
+ * @example
+ * import { configureApiClient } from '@krymskyimaksym/react-api-client';
+ * import { router } from 'expo-router';
+ *
+ * configureApiClient({
+ *   httpClient: myHttpClient,
+ *   onUnauthorized: () => router.replace('/login')
+ * });
+ */
+declare function configureApiClient(config: ApiClientConfig): void;
+/**
+ * Get the current global configuration
+ * @throws Error if configuration is not set
+ */
+declare function getConfig(): ApiClientConfig;
+/**
+ * Check if the API client is configured
+ */
+declare function isConfigured(): boolean;
+
+/**
+ * Creates an API client for GET requests
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @returns Object with fetch method and useFetch hook
+ *
+ * @example
+ * const userApi = apiClient<User, { id: string }>('/api/users/:id')
+ * const { data } = userApi.useFetch({ id: '123' })
+ */
+declare function apiClient<ResponseType = void, RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig): ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType>;
+/**
+ * Creates an API client for mutation requests (POST/PUT/PATCH/DELETE)
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @returns Object with mutate method and useMutation hook
+ *
+ * @example
+ * const createUserApi = apiMutation<User, CreateUserRequest>('/api/users', { method: 'POST' })
+ * const { mutate, isLoading } = createUserApi.useMutation()
+ */
+declare function apiMutation<ResponseType = void, RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig): ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType>;
+/**
+ * Creates an API client for paginated requests
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @param options - Pagination options (data/total extractors)
+ * @returns Object with usePaginate hook
+ *
+ * @example
+ * const usersApi = apiPaginate<UsersResponse, User[], { search?: string }>('/api/users')
+ * const { data, fetchNextPage, hasNextPage } = usersApi.usePaginate()
+ */
+declare function apiPaginate<ResponseType extends {
+    data: TData;
+    total?: number;
+    page?: number;
+}, TData extends unknown[], RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig, options?: {
+    dataExtractor?: (response: ResponseType) => TData;
+    totalExtractor?: (response: ResponseType) => number;
+}): ApiPaginateReturn<ResponseType, RequestParamsType, TData, ErrorResponseType>;
+
+export { type ApiClientConfig, type IHttpClient, type ResponseWrapper, type UseFetchOptions, type UseFetchResult, type UseMutationOptions, type UseMutationResult, type UsePaginateOptions, type UsePaginateResult, apiMutation, apiPaginate, configureApiClient, apiClient as default, getConfig, isConfigured };

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+type RequestConfig = {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    requestParams?: Record<string, string>;
+};
+type ResponseWrapper<DataType, ErrorsType = unknown> = {
+    status: boolean;
+    message?: string;
+    errors?: ErrorsType;
+} & DataType;
+type UseFetchOptions<T> = {
+    enabled?: boolean;
+    refetchOnMount?: boolean;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+};
+type UseFetchResult<T> = {
+    data: T | null;
+    isLoading: boolean;
+    isRefetching: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+type UsePaginateOptions<T> = {
+    enabled?: boolean;
+    initialPage?: number;
+    initialLimit?: number;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+};
+type UsePaginateResult<TData extends unknown[]> = {
+    data: TData;
+    currentPage: number;
+    totalPages: number | null;
+    total: number | null;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isLoading: boolean;
+    isFetchingNextPage: boolean;
+    error: Error | null;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+    reset: () => void;
+};
+type UseMutationOptions<TData, TVariables> = {
+    onMutate?: (variables: TVariables) => void | Promise<void>;
+    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
+    onError?: (error: Error, variables: TVariables) => void | Promise<void>;
+    onSettled?: (data: TData | null, error: Error | null, variables: TVariables) => void | Promise<void>;
+};
+type UseMutationResult<TData, TVariables> = {
+    data: TData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    reset: () => void;
+};
+interface IHttpClient {
+    get<T>(url: string, config?: {
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    request<T>(url: string, config: {
+        method?: string;
+        data?: Record<string, unknown>;
+    }): Promise<T>;
+}
+type ApiClientConfig = {
+    httpClient: IHttpClient;
+    onUnauthorized?: () => void | Promise<void>;
+};
+type ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
+    fetch: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
+    useFetch: (params?: RequestParamsType, options?: UseFetchOptions<ResponseWrapper<ResponseType, ErrorResponseType>>) => UseFetchResult<ResponseWrapper<ResponseType, ErrorResponseType>>;
+};
+type ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
+    mutate: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
+    useMutation: (options?: UseMutationOptions<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>) => UseMutationResult<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>;
+};
+type ApiPaginateReturn<ResponseType, RequestParamsType, DataArrayType extends unknown[], ErrorResponseType = unknown> = {
+    usePaginate: (params?: Omit<RequestParamsType, 'page' | 'limit'>, options?: UsePaginateOptions<ResponseWrapper<ResponseType, ErrorResponseType>>) => UsePaginateResult<DataArrayType>;
+};
+
+/**
+ * Configure the API client globally
+ * @param config - API client configuration
+ *
+ * @example
+ * import { configureApiClient } from '@krymskyimaksym/react-api-client';
+ * import { router } from 'expo-router';
+ *
+ * configureApiClient({
+ *   httpClient: myHttpClient,
+ *   onUnauthorized: () => router.replace('/login')
+ * });
+ */
+declare function configureApiClient(config: ApiClientConfig): void;
+/**
+ * Get the current global configuration
+ * @throws Error if configuration is not set
+ */
+declare function getConfig(): ApiClientConfig;
+/**
+ * Check if the API client is configured
+ */
+declare function isConfigured(): boolean;
+
+/**
+ * Creates an API client for GET requests
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @returns Object with fetch method and useFetch hook
+ *
+ * @example
+ * const userApi = apiClient<User, { id: string }>('/api/users/:id')
+ * const { data } = userApi.useFetch({ id: '123' })
+ */
+declare function apiClient<ResponseType = void, RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig): ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType>;
+/**
+ * Creates an API client for mutation requests (POST/PUT/PATCH/DELETE)
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @returns Object with mutate method and useMutation hook
+ *
+ * @example
+ * const createUserApi = apiMutation<User, CreateUserRequest>('/api/users', { method: 'POST' })
+ * const { mutate, isLoading } = createUserApi.useMutation()
+ */
+declare function apiMutation<ResponseType = void, RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig): ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType>;
+/**
+ * Creates an API client for paginated requests
+ * @param endpoint - URL string or function that generates URL from params
+ * @param fetchConfig - Request configuration
+ * @param options - Pagination options (data/total extractors)
+ * @returns Object with usePaginate hook
+ *
+ * @example
+ * const usersApi = apiPaginate<UsersResponse, User[], { search?: string }>('/api/users')
+ * const { data, fetchNextPage, hasNextPage } = usersApi.usePaginate()
+ */
+declare function apiPaginate<ResponseType extends {
+    data: TData;
+    total?: number;
+    page?: number;
+}, TData extends unknown[], RequestParamsType = void, ErrorResponseType = unknown>(endpoint: string | ((arg0: RequestParamsType) => string), fetchConfig?: RequestConfig, options?: {
+    dataExtractor?: (response: ResponseType) => TData;
+    totalExtractor?: (response: ResponseType) => number;
+}): ApiPaginateReturn<ResponseType, RequestParamsType, TData, ErrorResponseType>;
+
+export { type ApiClientConfig, type IHttpClient, type ResponseWrapper, type UseFetchOptions, type UseFetchResult, type UseMutationOptions, type UseMutationResult, type UsePaginateOptions, type UsePaginateResult, apiMutation, apiPaginate, configureApiClient, apiClient as default, getConfig, isConfigured };