@ahsan-iftikhar-114/api-toolkit-react-query 1.0.0

package/dist/config/config.d.ts

@@ -0,0 +1,12 @@
+import { ApiConfig } from "../types";
+/**
+ * Configure global API settings.
+ *
+ * Request-level configuration can override
+ * these settings.
+ */
+export declare const configureApi: (config: ApiConfig) => void;
+/**
+ * Get current global API configuration.
+ */
+export declare const getApiConfig: () => ApiConfig;

package/dist/config/config.js

@@ -0,0 +1,29 @@
+let apiConfig = {
+    baseURL: "",
+    timeout: 30000,
+    headers: {
+        "Content-Type": "application/json",
+    },
+};
+/**
+ * Configure global API settings.
+ *
+ * Request-level configuration can override
+ * these settings.
+ */
+export const configureApi = (config) => {
+    apiConfig = {
+        ...apiConfig,
+        ...config,
+        headers: {
+            ...apiConfig.headers,
+            ...config.headers,
+        },
+    };
+};
+/**
+ * Get current global API configuration.
+ */
+export const getApiConfig = () => {
+    return apiConfig;
+};

package/dist/core/api.d.ts

@@ -0,0 +1,26 @@
+import { AxiosResponse } from "axios";
+import { ApiMethod, ApiRequestPayload } from "../types";
+/**
+ * Generic API request.
+ */
+export declare const apiRequest: <TResponse = unknown, TRequest = unknown>(method: ApiMethod, url: string, payload?: ApiRequestPayload<TRequest>) => Promise<AxiosResponse<TResponse, any, {}, any>>;
+/**
+ * GET request.
+ */
+export declare const apiGet: <TResponse = unknown>(url: string, payload?: ApiRequestPayload) => Promise<AxiosResponse<TResponse, any, {}, any>>;
+/**
+ * POST request.
+ */
+export declare const apiPost: <TResponse = unknown, TRequest = unknown>(url: string, payload?: ApiRequestPayload<TRequest>) => Promise<AxiosResponse<TResponse, any, {}, any>>;
+/**
+ * PUT request.
+ */
+export declare const apiPut: <TResponse = unknown, TRequest = unknown>(url: string, payload?: ApiRequestPayload<TRequest>) => Promise<AxiosResponse<TResponse, any, {}, any>>;
+/**
+ * PATCH request.
+ */
+export declare const apiPatch: <TResponse = unknown, TRequest = unknown>(url: string, payload?: ApiRequestPayload<TRequest>) => Promise<AxiosResponse<TResponse, any, {}, any>>;
+/**
+ * DELETE request.
+ */
+export declare const apiDelete: <TResponse = unknown, TRequest = unknown>(url: string, payload?: ApiRequestPayload<TRequest>) => Promise<AxiosResponse<TResponse, any, {}, any>>;

package/dist/core/api.js

@@ -0,0 +1,88 @@
+import axios from "axios";
+import { getAxiosInstance, } from "./axios";
+import { normalizeApiError, } from "./error";
+const request = async (method, url, payload) => {
+    const axiosInstance = getAxiosInstance();
+    const config = {
+        ...(payload?.config || {}),
+        ...(payload?.params !== undefined
+            ? {
+                params: payload.params,
+            }
+            : {}),
+        ...(payload?.headers !== undefined
+            ? {
+                headers: payload.headers,
+            }
+            : {}),
+        ...(payload?.signal !== undefined
+            ? {
+                signal: payload.signal,
+            }
+            : {}),
+    };
+    try {
+        switch (method) {
+            case "GET":
+                return await axiosInstance.get(url, config);
+            case "POST":
+                return await axiosInstance.post(url, payload?.data, config);
+            case "PUT":
+                return await axiosInstance.put(url, payload?.data, config);
+            case "PATCH":
+                return await axiosInstance.patch(url, payload?.data, config);
+            case "DELETE":
+                return await axiosInstance.delete(url, {
+                    ...config,
+                    data: payload?.data,
+                });
+            default:
+                throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+    }
+    catch (error) {
+        /**
+         * Preserve Axios cancellation errors.
+         */
+        if (axios.isCancel(error)) {
+            throw error;
+        }
+        throw normalizeApiError(error);
+    }
+};
+/**
+ * Generic API request.
+ */
+export const apiRequest = (method, url, payload) => {
+    return request(method, url, payload);
+};
+/**
+ * GET request.
+ */
+export const apiGet = (url, payload) => {
+    return request("GET", url, payload);
+};
+/**
+ * POST request.
+ */
+export const apiPost = (url, payload) => {
+    return request("POST", url, payload);
+};
+/**
+ * PUT request.
+ */
+export const apiPut = (url, payload) => {
+    return request("PUT", url, payload);
+};
+/**
+ * PATCH request.
+ */
+export const apiPatch = (url, payload) => {
+    return request("PATCH", url, payload);
+};
+/**
+ * DELETE request.
+ */
+export const apiDelete = (url, payload) => {
+    return request("DELETE", url, payload);
+};

package/dist/core/axios.d.ts

@@ -0,0 +1,10 @@
+import { AxiosInstance } from "axios";
+/**
+ * Initialize Axios using the
+ * current global API configuration.
+ */
+export declare const initializeAxios: () => AxiosInstance;
+/**
+ * Get the current Axios instance.
+ */
+export declare const getAxiosInstance: () => AxiosInstance;

package/dist/core/axios.js

@@ -0,0 +1,38 @@
+import axios from "axios";
+import { getApiConfig, } from "../config/config";
+let axiosInstance = axios.create();
+/**
+ * Initialize Axios using the
+ * current global API configuration.
+ */
+export const initializeAxios = () => {
+    const config = getApiConfig();
+    axiosInstance = axios.create({
+        baseURL: config.baseURL,
+        timeout: config.timeout,
+        headers: config.headers,
+    });
+    axiosInstance.interceptors.request.use((request) => {
+        const currentConfig = getApiConfig();
+        if (currentConfig.token) {
+            const token = typeof currentConfig.token ===
+                "function"
+                ? currentConfig.token()
+                : currentConfig.token;
+            if (token) {
+                request.headers.Authorization =
+                    `Bearer ${token}`;
+            }
+        }
+        return request;
+    }, (error) => {
+        return Promise.reject(error);
+    });
+    return axiosInstance;
+};
+/**
+ * Get the current Axios instance.
+ */
+export const getAxiosInstance = () => {
+    return axiosInstance;
+};

package/dist/core/cache.d.ts

@@ -0,0 +1,20 @@
+import { QueryClient } from "@tanstack/react-query";
+/**
+ * Invalidate all queries belonging
+ * to a specific API name.
+ */
+export declare const invalidateApi: (name: string, queryClient: QueryClient) => Promise<void>;
+/**
+ * Invalidate multiple APIs.
+ */
+export declare const invalidateApis: (names: string[], queryClient: QueryClient) => Promise<void>;
+/**
+ * Invalidate every query
+ * in the provided QueryClient.
+ */
+export declare const invalidateAllApis: (queryClient: QueryClient) => Promise<void>;
+/**
+ * Cancel all queries belonging
+ * to a specific API name.
+ */
+export declare const cancelApi: (name: string, queryClient: QueryClient) => Promise<void>;

package/dist/core/cache.js

@@ -0,0 +1,39 @@
+/**
+ * Invalidate all queries belonging
+ * to a specific API name.
+ */
+export const invalidateApi = async (name, queryClient) => {
+    await queryClient.invalidateQueries({
+        queryKey: [
+            name,
+        ],
+    });
+};
+/**
+ * Invalidate multiple APIs.
+ */
+export const invalidateApis = async (names, queryClient) => {
+    await Promise.all(names.map((name) => queryClient.invalidateQueries({
+        queryKey: [
+            name,
+        ],
+    })));
+};
+/**
+ * Invalidate every query
+ * in the provided QueryClient.
+ */
+export const invalidateAllApis = async (queryClient) => {
+    await queryClient.invalidateQueries();
+};
+/**
+ * Cancel all queries belonging
+ * to a specific API name.
+ */
+export const cancelApi = async (name, queryClient) => {
+    await queryClient.cancelQueries({
+        queryKey: [
+            name,
+        ],
+    });
+};

package/dist/core/client.d.ts

@@ -0,0 +1,8 @@
+import { QueryClient, QueryClientConfig } from "@tanstack/react-query";
+/**
+ * Creates a QueryClient for the application.
+ *
+ * The package does not maintain a global
+ * QueryClient instance.
+ */
+export declare const createApiQueryClient: (options?: QueryClientConfig) => QueryClient;

package/dist/core/client.js

@@ -0,0 +1,10 @@
+import { QueryClient, } from "@tanstack/react-query";
+/**
+ * Creates a QueryClient for the application.
+ *
+ * The package does not maintain a global
+ * QueryClient instance.
+ */
+export const createApiQueryClient = (options) => {
+    return new QueryClient(options);
+};

package/dist/core/error.d.ts

@@ -0,0 +1,6 @@
+import { ApiError } from "../types";
+/**
+ * Normalize unknown API errors
+ * into a consistent ApiError structure.
+ */
+export declare const normalizeApiError: (error: unknown) => ApiError;

package/dist/core/error.js

@@ -0,0 +1,36 @@
+import axios from "axios";
+/**
+ * Normalize unknown API errors
+ * into a consistent ApiError structure.
+ */
+export const normalizeApiError = (error) => {
+    if (axios.isAxiosError(error)) {
+        const responseData = error.response?.data;
+        const dataObject = typeof responseData === "object" &&
+            responseData !== null
+            ? responseData
+            : undefined;
+        const message = typeof dataObject?.message === "string"
+            ? dataObject.message
+            : error.message ||
+                "Something went wrong";
+        return {
+            message,
+            status: error.response?.status,
+            statusText: error.response?.statusText,
+            data: responseData,
+            errors: dataObject?.errors,
+            originalError: error,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            originalError: error,
+        };
+    }
+    return {
+        message: "Something went wrong",
+        originalError: error,
+    };
+};

package/dist/core/mutation.d.ts

@@ -0,0 +1,13 @@
+import { UseMutationResult } from "@tanstack/react-query";
+import { ApiMethod, ApiRequestPayload, ApiMutationOptions, ApiError } from "../types";
+/**
+ * Creates a reusable mutation API hook.
+ *
+ * Supports:
+ *
+ * POST
+ * PUT
+ * PATCH
+ * DELETE
+ */
+export declare const createApiMutation: <TResponse = unknown, TRequest = unknown, TContext = unknown>(name: string, method: Exclude<ApiMethod, "GET">, url: string) => (options?: ApiMutationOptions<TResponse, TRequest, TContext>) => UseMutationResult<TResponse, ApiError, ApiRequestPayload<TRequest>, TContext>;

package/dist/core/mutation.js

@@ -0,0 +1,27 @@
+import { useMutation, } from "@tanstack/react-query";
+import { apiRequest, } from "./api";
+/**
+ * Creates a reusable mutation API hook.
+ *
+ * Supports:
+ *
+ * POST
+ * PUT
+ * PATCH
+ * DELETE
+ */
+export const createApiMutation = (name, method, url) => {
+    return (options) => {
+        return useMutation({
+            ...options,
+            mutationKey: [
+                name,
+                url,
+            ],
+            mutationFn: async (payload) => {
+                const response = await apiRequest(method, url, payload);
+                return response.data;
+            },
+        });
+    };
+};

package/dist/core/query.d.ts

@@ -0,0 +1,10 @@
+import { UseQueryResult } from "@tanstack/react-query";
+import { ApiRequestPayload, ApiQueryOptions, ApiError } from "../types";
+/**
+ * Creates a reusable GET API query hook.
+ *
+ * Supports all standard TanStack Query options,
+ * except queryKey and queryFn which are managed
+ * internally by this package.
+ */
+export declare const createApiQuery: <TResponse = unknown>(name: string, url: string) => <TData = TResponse>(payload?: ApiRequestPayload, options?: ApiQueryOptions<TResponse, TData>) => UseQueryResult<TData, ApiError>;

package/dist/core/query.js

@@ -0,0 +1,28 @@
+import { useQuery, } from "@tanstack/react-query";
+import { apiRequest, } from "./api";
+/**
+ * Creates a reusable GET API query hook.
+ *
+ * Supports all standard TanStack Query options,
+ * except queryKey and queryFn which are managed
+ * internally by this package.
+ */
+export const createApiQuery = (name, url) => {
+    return (payload, options) => {
+        return useQuery({
+            ...options,
+            queryKey: [
+                name,
+                url,
+                payload?.params,
+            ],
+            queryFn: async ({ signal, }) => {
+                const response = await apiRequest("GET", url, {
+                    ...payload,
+                    signal,
+                });
+                return response.data;
+            },
+        });
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { createApiQueryClient } from "./core/client";
+import { invalidateApi, invalidateApis, invalidateAllApis, cancelApi } from "./core/cache";
+import { ApiMethod, ApiRequestPayload, ApiConfig, ApiQueryOptions, ApiMutationOptions, ApiError, ApiResponse, ApiRequestDefinition } from "./types";
+/**
+ * Public types.
+ */
+export type { ApiMethod, ApiRequestPayload, ApiConfig, ApiQueryOptions, ApiMutationOptions, ApiError, ApiResponse, ApiRequestDefinition, };
+/**
+ * Public utilities.
+ */
+export { createApiQueryClient, invalidateApi, invalidateApis, invalidateAllApis, cancelApi, };
+/**
+ * Configure global API settings.
+ */
+export declare const configureApi: (config: ApiConfig) => void;
+/**
+ * Create a generic API hook.
+ *
+ * GET:
+ *     React Query query
+ *
+ * POST:
+ *     React Query mutation
+ *
+ * PUT:
+ *     React Query mutation
+ *
+ * PATCH:
+ *     React Query mutation
+ *
+ * DELETE:
+ *     React Query mutation
+ */
+export declare const createApi: <TResponse = unknown, TRequest = unknown, TContext = unknown>(name: string, method: ApiMethod, url: string) => (<TData = TResponse>(payload?: ApiRequestPayload, options?: ApiQueryOptions<TResponse, TData> | undefined) => import("@tanstack/react-query").UseQueryResult<TData, ApiError>) | ((options?: ApiMutationOptions<TResponse, TRequest, TContext> | undefined) => import("@tanstack/react-query").UseMutationResult<TResponse, ApiError, ApiRequestPayload<TRequest>, TContext>);

package/dist/index.js

@@ -0,0 +1,41 @@
+import { configureApi as configureApiConfig, } from "./config/config";
+import { initializeAxios, } from "./core/axios";
+import { createApiQuery, } from "./core/query";
+import { createApiMutation, } from "./core/mutation";
+import { createApiQueryClient, } from "./core/client";
+import { invalidateApi, invalidateApis, invalidateAllApis, cancelApi, } from "./core/cache";
+/**
+ * Public utilities.
+ */
+export { createApiQueryClient, invalidateApi, invalidateApis, invalidateAllApis, cancelApi, };
+/**
+ * Configure global API settings.
+ */
+export const configureApi = (config) => {
+    configureApiConfig(config);
+    initializeAxios();
+};
+/**
+ * Create a generic API hook.
+ *
+ * GET:
+ *     React Query query
+ *
+ * POST:
+ *     React Query mutation
+ *
+ * PUT:
+ *     React Query mutation
+ *
+ * PATCH:
+ *     React Query mutation
+ *
+ * DELETE:
+ *     React Query mutation
+ */
+export const createApi = (name, method, url) => {
+    if (method === "GET") {
+        return createApiQuery(name, url);
+    }
+    return createApiMutation(name, method, url);
+};

package/dist/types/index.d.ts

@@ -0,0 +1,97 @@
+import { AxiosRequestConfig, AxiosResponse } from "axios";
+import type { UseQueryOptions, UseMutationOptions, QueryKey } from "@tanstack/react-query";
+export type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Generic API request payload.
+ */
+export interface ApiRequestPayload<TRequest = unknown> {
+    /**
+     * Request body.
+     *
+     * Used by POST, PUT, PATCH and DELETE.
+     */
+    data?: TRequest;
+    /**
+     * URL query parameters.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Request-specific headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Advanced Axios configuration.
+     */
+    config?: AxiosRequestConfig;
+    /**
+     * Request cancellation signal.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Global API configuration.
+ */
+export interface ApiConfig {
+    /**
+     * Base API URL.
+     */
+    baseURL?: string;
+    /**
+     * Global request timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Global request headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Authentication token.
+     *
+     * Can be a static token or a function
+     * returning the latest token.
+     */
+    token?: string | (() => string | null | undefined);
+}
+/**
+ * Normalized API error.
+ */
+export interface ApiError {
+    message: string;
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+    errors?: unknown;
+    originalError?: unknown;
+}
+/**
+ * Standard API response.
+ */
+export interface ApiResponse<TResponse = unknown> {
+    data: TResponse;
+    status: number;
+    statusText: string;
+    headers: unknown;
+    response: AxiosResponse<TResponse>;
+}
+/**
+ * API definition.
+ */
+export interface ApiRequestDefinition {
+    name: string;
+    method: ApiMethod;
+    url: string;
+}
+/**
+ * Advanced React Query options.
+ *
+ * TQueryFnData:
+ *     Actual API response.
+ *
+ * TData:
+ *     Data returned after select().
+ */
+export type ApiQueryOptions<TQueryFnData = unknown, TData = TQueryFnData> = Omit<UseQueryOptions<TQueryFnData, ApiError, TData, QueryKey>, "queryKey" | "queryFn">;
+/**
+ * Advanced React Query mutation options.
+ */
+export type ApiMutationOptions<TResponse = unknown, TRequest = unknown, TContext = unknown> = Omit<UseMutationOptions<TResponse, ApiError, ApiRequestPayload<TRequest>, TContext>, "mutationKey" | "mutationFn">;

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ahsan-iftikhar-114/api-toolkit-react-query",
+  "version": "1.0.0",
+  "description": "A generic API toolkit for React applications using Axios and TanStack Query.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "react-query",
+    "tanstack-query",
+    "axios",
+    "typescript",
+    "api",
+    "api-client",
+    "react-api",
+    "react-api-client",
+    "react-query-axios",
+    "tanstack-query-axios",
+    "axios-react-query",
+    "api-toolkit",
+    "api-hooks",
+    "react-hooks",
+    "query-hooks",
+    "mutation-hooks",
+    "rest-api",
+    "rest-api-client",
+    "typescript-api-client",
+    "api-cache",
+    "cache-invalidation",
+    "request-cancellation",
+    "react-query-cache",
+    "react-query-typescript",
+    "axios-typescript"
+  ],
+  "author": "Ahsan Iftikhar",
+  "license": "MIT",
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}