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

package/README.md

@@ -0,0 +1,1017 @@
+# @ahsan-iftikhar-114/api-toolkit-react-query
+
+**A simple and reusable API toolkit for React applications using Axios and TanStack Query.**
+
+This package makes it easier to connect your React application with your backend API.
+
+You do not need to build API handling, loading states, error handling, authentication, caching, and request management from scratch.
+
+The package provides these features in one reusable solution.
+
+---
+
+## What is this package?
+
+When a React application needs information from a backend server, it has to send an **API request**.
+
+For example:
+
+* Get users
+* Create a user
+* Update a user
+* Delete a user
+* Get products
+* Submit a form
+* Login a user
+* Upload or send data
+* Refresh information from the server
+
+Normally, developers have to write a lot of code to manage these requests.
+
+This package provides a simpler and more consistent way to manage them.
+
+### In simple words
+
+You tell the package:
+
+**What is this API?**
+
+**Which HTTP method should it use?**
+
+**Which API URL should it call?**
+
+The package handles the rest.
+
+---
+
+# Who is this package for?
+
+This package is useful for:
+
+* React developers
+* Frontend developers
+* Backend developers working with React
+* Beginners learning API integration
+* Developers building dashboards
+* Developers building admin panels
+* Developers building SaaS applications
+* Developers building business applications
+* Teams that want a consistent API structure
+* Projects using Laravel, Node.js, PHP, .NET, Python or another backend
+
+You do not need to understand every internal part of Axios or TanStack Query to use the basic functionality.
+
+---
+
+# What problem does it solve?
+
+Without an API toolkit, developers often need to manage several things separately:
+
+* API requests
+* Axios configuration
+* Authentication tokens
+* Loading states
+* Error states
+* Request cancellation
+* API caching
+* Data refreshing
+* Cache invalidation
+* Query management
+* Mutation management
+
+This package brings these responsibilities together.
+
+### Instead of building everything separately
+
+You can use one consistent API system throughout your React application.
+
+---
+
+# How does it work?
+
+The basic idea is very simple.
+
+You define an API using three things:
+
+**1. Name**
+
+A name that identifies the API.
+
+**2. Method**
+
+The type of request:
+
+* GET
+* POST
+* PUT
+* PATCH
+* DELETE
+
+**3. URL**
+
+The backend API address.
+
+That's it.
+
+The package then automatically decides how that API should work inside React.
+
+---
+
+# What are GET, POST, PUT, PATCH and DELETE?
+
+You do not need to be an API expert to understand these.
+
+Think about a simple employee management system.
+
+### GET
+
+Used when you want to **get information**.
+
+Examples:
+
+* Get employees
+* Get users
+* Get products
+* Get invoices
+
+---
+
+### POST
+
+Used when you want to **create something new**.
+
+Examples:
+
+* Create employee
+* Create user
+* Create invoice
+* Submit form
+
+---
+
+### PUT
+
+Used when you want to **update existing information**.
+
+Examples:
+
+* Update employee
+* Update user
+* Update profile
+
+---
+
+### PATCH
+
+Also used to **update information**, usually when changing only part of it.
+
+Examples:
+
+* Change employee status
+* Update user name
+* Change invoice status
+
+---
+
+### DELETE
+
+Used when you want to **remove something**.
+
+Examples:
+
+* Delete employee
+* Delete user
+* Delete product
+
+---
+
+# How do I install it?
+
+Open your React project's terminal and install the package:
+
+```text
+npm install @ahsan-iftikhar-114/api-toolkit-react-query
+```
+
+The package works with:
+
+* React
+* Axios
+* TanStack Query
+
+If your project does not already have the required React Query package, install it as well.
+
+---
+
+# What do I need before using it?
+
+You need a React application.
+
+You also need:
+
+* React 18 or newer
+* TanStack Query 5 or newer
+* Axios 1 or newer
+
+TypeScript is recommended, but the package can also be used in JavaScript projects.
+
+---
+
+# Basic setup
+
+The setup can be understood in four simple steps.
+
+## Step 1 — Install the package
+
+Install the package in your React project.
+
+---
+
+## Step 2 — Tell the package your API address
+
+Your backend normally has a common address.
+
+For example:
+
+```text
+https://api.example.com
+```
+
+You configure this once.
+
+After that, you can use shorter API paths throughout your application.
+
+For example:
+
+```text
+/users
+/products
+/orders
+/invoices
+```
+
+---
+
+## Step 3 — Connect TanStack Query
+
+The package uses TanStack Query to manage server data.
+
+Your React application needs a Query Client.
+
+You can use the Query Client provided by the package or create your own TanStack Query client.
+
+This is normally configured once in your application.
+
+---
+
+## Step 4 — Create your APIs
+
+For every API, provide:
+
+* Name
+* Method
+* URL
+
+For example, conceptually:
+
+**Users**
+
+**GET**
+
+**/users**
+
+The package will treat this as a data-fetching API.
+
+For a create-user API:
+
+**Create User**
+
+**POST**
+
+**/users**
+
+The package will treat this as a data-changing API.
+
+---
+
+# GET APIs
+
+GET APIs are used when your application needs to **read information from the server**.
+
+For example:
+
+* Employee list
+* Customer list
+* Product list
+* Dashboard statistics
+* Notifications
+* User profile
+
+When you use a GET API, the package provides the information needed to manage the request, including:
+
+* Data
+* Loading state
+* Error state
+* Fetching state
+* Refetching
+* Cached data
+
+This means your application can easily know whether information is loading, successfully received, or failed.
+
+---
+
+# POST, PUT, PATCH and DELETE APIs
+
+These APIs are used when your application needs to **change information on the server**.
+
+For example:
+
+* Create employee
+* Update employee
+* Delete employee
+* Create invoice
+* Update invoice
+* Submit request
+
+The package manages these operations as mutations.
+
+You can easily know:
+
+* Whether the operation is running
+* Whether it succeeded
+* Whether it failed
+* What data was returned
+* What error occurred
+
+---
+
+# Sending information to the server
+
+When creating or updating something, your application usually needs to send information.
+
+For example, when creating an employee:
+
+* Name
+* Email
+* Department
+* Position
+
+The package allows you to send this information to your backend API.
+
+You can also send:
+
+* Query parameters
+* Request headers
+* Authentication information
+* Additional Axios configuration
+
+---
+
+# Authentication
+
+Many APIs require users to log in before they can access protected information.
+
+This package supports **Bearer Token authentication**.
+
+You can configure an authentication token globally.
+
+The token can be:
+
+* A fixed token
+* A dynamically retrieved token
+
+A dynamic token is useful when the token is stored in browser storage or another authentication system.
+
+The package automatically adds the token to API requests.
+
+This means you do not need to manually add the authentication header to every request.
+
+---
+
+# API Base URL
+
+You can configure one common API address for your application.
+
+For example:
+
+```text
+https://api.example.com
+```
+
+Then individual APIs only need their own path.
+
+For example:
+
+```text
+/users
+/employees
+/products
+/orders
+```
+
+This makes API configuration easier to maintain.
+
+If your backend address changes, you can update the main configuration instead of changing every API.
+
+---
+
+# Loading states
+
+When your application requests information from a server, the server may take some time to respond.
+
+The package provides request status information so your application can show things such as:
+
+* Loading...
+* Please wait...
+* Loading spinner
+* Refreshing...
+* Saving...
+* Deleting...
+
+This makes it easier to create a better user experience.
+
+---
+
+# Error handling
+
+API requests can fail for many reasons.
+
+For example:
+
+* Internet connection problem
+* Server error
+* Unauthorized request
+* Validation error
+* Not found
+* Request timeout
+
+The package provides a consistent error format so your application can handle API errors more easily.
+
+Instead of every API returning a completely different error structure to your application, the package normalizes common API errors.
+
+---
+
+# Query parameters
+
+Sometimes an API needs additional information in the URL.
+
+For example:
+
+* Page number
+* Number of records
+* Search text
+* Sorting
+* Filtering
+* Status
+
+The package supports query parameters.
+
+This makes it suitable for:
+
+* Search pages
+* Data tables
+* Pagination
+* Filters
+* Reports
+* Admin dashboards
+
+---
+
+# Caching
+
+One of the major features of this package is API data caching through TanStack Query.
+
+Caching means your application can temporarily remember information it has already received.
+
+This can reduce unnecessary API requests.
+
+For example:
+
+A user opens the employee page.
+
+The application gets the employee list from the server.
+
+If the same information is needed again, TanStack Query can use its cached data according to your configured caching rules.
+
+This can make applications feel faster and reduce unnecessary network requests.
+
+---
+
+# Refetching
+
+Sometimes information needs to be updated from the server.
+
+For example:
+
+* User clicks Refresh
+* User returns to a page
+* Application reconnects to the internet
+* Data becomes stale
+
+The package works with TanStack Query's refetching functionality.
+
+This allows your application to keep server data up to date.
+
+---
+
+# Cache invalidation
+
+Suppose you have an employee list.
+
+A user creates a new employee.
+
+The old employee list may no longer be correct.
+
+The package provides cache invalidation utilities that can tell TanStack Query:
+
+**"This data may have changed. Get the latest information."**
+
+This is especially useful after:
+
+* Creating records
+* Updating records
+* Deleting records
+* Changing statuses
+* Performing other server-side operations
+
+---
+
+# Request cancellation
+
+Sometimes a request is no longer needed.
+
+For example:
+
+A user starts searching for employees.
+
+Then immediately changes the search.
+
+The previous request may no longer be useful.
+
+The package supports request cancellation through `AbortSignal`.
+
+This can help prevent unnecessary work and improve request management.
+
+---
+
+# Advanced configuration
+
+Although the basic API is simple, the package also supports advanced configuration.
+
+Developers can use TanStack Query options such as:
+
+* Cache duration
+* Stale time
+* Retry behavior
+* Automatic refetching
+* Conditional requests
+* Placeholder data
+* Initial data
+* Data selection
+* Other compatible TanStack Query options
+
+This means beginners can start with the simple functionality while experienced developers can customize the behavior when needed.
+
+---
+
+# TypeScript support
+
+The package is designed with TypeScript support in mind.
+
+You can define the type of:
+
+* API response
+* Request data
+* Mutation context
+* Selected data
+
+This helps developers get:
+
+* Better autocomplete
+* Better editor support
+* Better type checking
+* Fewer mistakes
+* Easier maintenance
+
+TypeScript is especially useful for large applications.
+
+---
+
+# Works with different backends
+
+This package is designed for the frontend API layer.
+
+Your backend can be built using many different technologies.
+
+For example:
+
+* Laravel
+* PHP
+* Node.js
+* Express
+* NestJS
+* .NET
+* ASP.NET
+* Django
+* FastAPI
+* Spring Boot
+* Other REST APIs
+
+As long as your backend provides an API that your React application can communicate with, this package can be used as the API management layer.
+
+---
+
+# What happens behind the scenes?
+
+You do not need to manage all of these individually.
+
+The package combines:
+
+**React**
+
+↓
+
+**API Toolkit**
+
+↓
+
+**Axios**
+
+↓
+
+**Backend API**
+
+And for server data management:
+
+**TanStack Query**
+
+↓
+
+**Caching**
+
+↓
+
+**Refetching**
+
+↓
+
+**Loading & Error States**
+
+↓
+
+**Cache Invalidation**
+
+The goal is to give your application one consistent way to communicate with APIs.
+
+---
+
+# Why use this package?
+
+### Simple API creation
+
+Define an API using:
+
+* Name
+* Method
+* URL
+
+---
+
+### Less repeated code
+
+You do not have to repeatedly create the same API request structure.
+
+---
+
+### Centralized configuration
+
+Configure:
+
+* API URL
+* Timeout
+* Headers
+* Authentication
+
+in one place.
+
+---
+
+### Built-in React Query support
+
+Use the powerful server-state management capabilities of TanStack Query.
+
+---
+
+### Authentication support
+
+Bearer token authentication can be configured centrally.
+
+---
+
+### Consistent errors
+
+API errors are normalized into a common structure.
+
+---
+
+### Caching support
+
+Use TanStack Query caching to reduce unnecessary requests.
+
+---
+
+### Request cancellation
+
+Cancel requests when they are no longer required.
+
+---
+
+### TypeScript friendly
+
+Use types for safer development and better editor support.
+
+---
+
+### Flexible
+
+Beginners can use the simple API creation system, while experienced developers can use advanced Axios and TanStack Query options.
+
+---
+
+# Recommended for
+
+This package is particularly useful for applications such as:
+
+* Admin panels
+* HRMS systems
+* CRM systems
+* ERP systems
+* SaaS applications
+* E-commerce applications
+* Project management applications
+* Business management systems
+* Dashboards
+* Customer portals
+* Employee portals
+* Internal company applications
+* REST API based React applications
+
+---
+
+# Package Architecture
+
+The package internally separates different responsibilities.
+
+```text
+API Configuration
+        ↓
+Axios
+        ↓
+API Request Layer
+        ↓
+TanStack Query
+        ↓
+React Application
+```
+
+This separation keeps the package reusable and easier to maintain.
+
+---
+
+# Supported HTTP Methods
+
+The package supports:
+
+| Method | Purpose                      |
+| ------ | ---------------------------- |
+| GET    | Get information              |
+| POST   | Create information           |
+| PUT    | Update information           |
+| PATCH  | Partially update information |
+| DELETE | Delete information           |
+
+---
+
+# Important terms explained simply
+
+### API
+
+An API allows your application to communicate with a backend server.
+
+### Axios
+
+Axios is the technology used to send HTTP requests to the backend.
+
+### TanStack Query
+
+TanStack Query manages server data inside your React application.
+
+It helps with:
+
+* Loading
+* Errors
+* Caching
+* Refetching
+* Mutations
+* Server state
+
+### Query
+
+A query normally means:
+
+**"Get information from the server."**
+
+### Mutation
+
+A mutation normally means:
+
+**"Change something on the server."**
+
+### Cache
+
+Previously received server information that can temporarily be stored and reused.
+
+### Query invalidation
+
+Telling the application that previously cached information may now be outdated and should be refreshed.
+
+### Bearer Token
+
+A common way of sending an authentication token with an API request.
+
+---
+
+# Is this package difficult to use?
+
+No.
+
+The package is designed around a simple API creation concept.
+
+You mainly need to understand three things:
+
+**Name → Method → URL**
+
+For example:
+
+**Employees → GET → /employees**
+
+Once you understand this concept, you can create APIs for almost any resource in your application.
+
+---
+
+# Typical application example
+
+Imagine you are building an HRMS application.
+
+You might have APIs for:
+
+* Employees
+* Attendance
+* Leave
+* Payroll
+* Departments
+* Performance
+* Requests
+* Notifications
+
+You can use the same package structure for all of them.
+
+This gives your application a consistent API architecture instead of creating a different API implementation for every module.
+
+---
+
+# Browser Support
+
+This package is intended for modern React applications running in environments that support:
+
+* Promises
+* Fetch-compatible AbortSignal
+* Modern JavaScript features
+
+For older browser environments, appropriate polyfills may be required depending on the application's setup.
+
+---
+
+# Security Note
+
+This package helps send authentication tokens, but it does not provide a complete authentication system.
+
+Your application and backend are still responsible for:
+
+* Login
+* User registration
+* Token generation
+* Token expiration
+* Token refresh
+* Permissions
+* Roles
+* Backend authorization
+* Secure token storage
+
+Never expose sensitive secrets such as backend private keys or server credentials in a React frontend.
+
+---
+
+# Performance
+
+The package uses TanStack Query for server-state management and caching.
+
+Performance will depend on:
+
+* API design
+* Backend performance
+* Database performance
+* Network speed
+* Query configuration
+* Cache configuration
+* Amount of requested data
+
+For large applications, developers should also use appropriate backend pagination, filtering, indexing and optimized API responses.
+
+---
+
+# Package Philosophy
+
+The main goal of this package is:
+
+> **Make API integration simple, reusable and consistent.**
+
+Instead of creating a separate API architecture for every React project, developers can use the same basic approach across different applications.
+
+Beginners can start with the simple functionality.
+
+Experienced developers can take advantage of advanced Axios and TanStack Query features.
+
+---
+
+# Technology
+
+This package is built around:
+
+* React
+* TypeScript
+* Axios
+* TanStack Query v5
+
+---
+
+# Keywords
+
+This package is useful for developers searching for:
+
+* React API client
+* React API toolkit
+* React Query API
+* TanStack Query API
+* Axios React Query
+* Axios API client
+* React API hooks
+* React Query hooks
+* React mutation hooks
+* React query hooks
+* TypeScript API client
+* React REST API client
+* API caching
+* React Query caching
+* API cache invalidation
+* Axios TypeScript
+* TanStack Query TypeScript
+* React API management
+* Generic React API client
+* Reusable React API hooks
+* API request management
+* React server state management
+
+---
+
+# Version
+
+Current version:
+
+**1.0.0**
+
+---
+
+# License
+
+This package is released under the **MIT License**.
+
+See the `LICENSE` file for more information.
+
+---
+
+# Author
+
+**Ahsan Iftikhar**
+
+---
+
+# Final Note
+
+If you are a beginner, start with the basic setup:
+
+**Install → Configure → Connect Query Client → Create API → Use API**
+
+You do not need to understand every advanced feature before starting.
+
+Once your application grows, you can use the advanced configuration, caching, authentication, cancellation, TypeScript and React Query features provided by the package.