npm-axios

1
# Axios
2

3
Axios is a Promise-based HTTP client library that works in both browsers and Node.js environments. It provides a consistent, feature-rich API for making HTTP requests with automatic JSON data transformation, request/response interceptors, request cancellation, timeout handling, and built-in protection against common security vulnerabilities like XSRF.
4

5
## Package Information
6

7
- **Package Name**: axios
8
- **Package Type**: npm
9
- **Language**: JavaScript (with TypeScript definitions)
10
- **Installation**: `npm install axios`
11

12
## Core Imports
13

14
```javascript
15
import axios from 'axios';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const axios = require('axios');
22
```
23

24
TypeScript imports for additional types:
25

26
```typescript
27
import axios, { 
28
  AxiosRequestConfig, 
29
  AxiosResponse, 
30
  AxiosError,
31
  AxiosInstance 
32
} from 'axios';
33
```
34

35
## Basic Usage
36

37
```javascript
38
import axios from 'axios';
39

40
// GET request
41
const response = await axios.get('https://api.example.com/users');
42
console.log(response.data);
43

44
// POST request with data
45
const newUser = await axios.post('https://api.example.com/users', {
46
  name: 'John Doe',
47
  email: 'john@example.com'
48
});
49

50
// Using request config object
51
const config = {
52
  method: 'get',
53
  url: 'https://api.example.com/users',
54
  timeout: 5000,
55
  headers: {
56
    'Authorization': 'Bearer your-token'
57
  }
58
};
59
const response = await axios(config);
60
```
61

62
## Architecture
63

64
Axios is built around several key components:
65

66
- **Core Instance**: The main axios instance with default configuration and HTTP method aliases
67
- **Request/Response Cycle**: Configurable request and response transformation with interceptor support
68
- **Adapter System**: Platform-specific adapters (XHR for browsers, HTTP for Node.js) with automatic selection
69
- **Configuration System**: Hierarchical configuration merging from defaults, instance config, and request config
70
- **Error Handling**: Comprehensive error types with request/response context and status code validation
71
- **Cancellation**: Both modern AbortController and legacy CancelToken support for request cancellation
72

73
## Capabilities
74

75
### HTTP Client and Requests
76

77
Core HTTP client functionality with method aliases, request configuration, and response handling. Supports all standard HTTP methods with automatic JSON handling and platform-specific optimizations.
78

79
```javascript { .api }
80
// Main instance - callable function and object
81
axios(config: AxiosRequestConfig): Promise<AxiosResponse>;
82
axios(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
83

84
// HTTP method aliases
85
axios.get(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
86
axios.post(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
87
axios.put(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
88
axios.patch(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
89
axios.delete(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
90
axios.head(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
91
axios.options(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
92

93
// Form methods with automatic Content-Type
94
axios.postForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
95
axios.putForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
96
axios.patchForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
97
```
98

99
[HTTP Client and Requests](./http-client.md)
100

101
### Request and Response Interceptors
102

103
Middleware system for transforming requests before sending and responses before handling. Supports both synchronous and asynchronous interceptors with conditional execution and error handling.
104

105
```javascript { .api }
106
// Request interceptors
107
axios.interceptors.request.use(
108
  config => config,
109
  error => Promise.reject(error)
110
);
111

112
// Response interceptors  
113
axios.interceptors.response.use(
114
  response => response,
115
  error => Promise.reject(error)
116
);
117

118
interface AxiosInterceptorManager<V> {
119
  use<T = V>(
120
    onFulfilled?: (value: V) => T | Promise<T>,
121
    onRejected?: (error: any) => any,
122
    options?: AxiosInterceptorOptions
123
  ): number;
124
  eject(id: number): void;
125
}
126
```
127

128
[Interceptors](./interceptors.md)
129

130
### Configuration and Defaults
131

132
Comprehensive configuration system with default settings, instance-level configuration, and request-level overrides. Includes timeout handling, header management, and data transformation options.
133

134
```javascript { .api }
135
// Default configuration access
136
axios.defaults: AxiosDefaults;
137

138
// Key configuration options
139
interface AxiosRequestConfig {
140
  url?: string;
141
  method?: string;
142
  baseURL?: string;
143
  headers?: AxiosRequestHeaders;
144
  params?: any;
145
  data?: any;
146
  timeout?: number;
147
  auth?: AxiosBasicCredentials;
148
  responseType?: ResponseType;
149
  validateStatus?: (status: number) => boolean;
150
}
151
```
152

153
[Configuration](./configuration.md)
154

155
### Error Handling and Cancellation
156

157
Comprehensive error handling with detailed error information and multiple cancellation mechanisms. Supports both modern AbortController and legacy CancelToken patterns for request cancellation.
158

159
```javascript { .api }
160
// Error types
161
class AxiosError extends Error {
162
  config?: AxiosRequestConfig;
163
  code?: string;
164
  request?: any;
165
  response?: AxiosResponse;
166
  isAxiosError: boolean;
167
  status?: number;
168
}
169

170
// Cancellation with AbortController (modern)
171
const controller = new AbortController();
172
axios.get('/api/data', { signal: controller.signal });
173
controller.abort();
174

175
// Cancellation with CancelToken (legacy)
176
const source = axios.CancelToken.source();
177
axios.get('/api/data', { cancelToken: source.token });
178
source.cancel('Operation canceled');
179
```
180

181
[Error Handling and Cancellation](./error-handling.md)
182

183
### Utility Functions and Version Information
184

185
Utility functions for error checking, data transformation, Promise handling, and URI building, plus access to version information.
186

187
```javascript { .api }
188
// Instance creation and management
189
axios.create(config?: AxiosRequestConfig): AxiosInstance;
190

191
// URI building  
192
axios.getUri(config?: AxiosRequestConfig): string;
193

194
// Type checking utilities
195
axios.isAxiosError(payload: any): boolean;
196
axios.isCancel(value: any): boolean;
197

198
// Data conversion utilities  
199
axios.toFormData(sourceObj: object, targetFormData?: FormData, options?: FormSerializerOptions): FormData;
200
axios.formToJSON(form: FormData | HTMLFormElement): object;
201

202
// Promise utilities
203
axios.all<T>(values: Array<T | Promise<T>>): Promise<T[]>;
204
axios.spread<T, R>(callback: (...args: T[]) => R): (array: T[]) => R;
205

206
// Version information
207
axios.VERSION: string;
208
```
209

210
## TypeScript Support
211

212
Axios includes comprehensive TypeScript definitions with generic type support for request and response data:
213

214
```typescript { .api }
215
interface AxiosResponse<T = any, D = any> {
216
  data: T;
217
  status: number;
218
  statusText: string;
219
  headers: AxiosResponseHeaders;
220
  config: AxiosRequestConfig<D>;
221
  request?: any;
222
}
223

224
interface AxiosInstance {
225
  <T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
226
  <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
227
  
228
  get<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
229
  post<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
230
  // ... other methods
231
}
232
```