0
# Core Requests
1

2
Primary AJAX request functionality providing comprehensive HTTP request capabilities with support for all HTTP methods, multiple data formats, cross-origin requests, and extensive configuration options.
3

4
## Capabilities
5

6
### Main Request Function
7

8
Creates and executes AJAX requests with flexible configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates and executes an AJAX request
13
 * @param {string|Object} options - URL string or configuration object
14
 * @param {Function} callback - Optional success callback for URL string form
15
 * @returns {Object} Request object with promise-like interface
16
 */
17
function reqwest(options, callback);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Simple URL form
24
reqwest('https://api.example.com/data', function(response) {
25
  console.log('Data:', response);
26
});
27

28
// Full configuration object
29
reqwest({
30
  url: 'https://api.example.com/users',
31
  method: 'POST',
32
  type: 'json',
33
  data: { name: 'Alice', email: 'alice@example.com' },
34
  headers: { 'Authorization': 'Bearer token123' },
35
  success: function(resp) { console.log('Created:', resp); },
36
  error: function(xhr, type, err) { console.log('Failed:', err); }
37
});
38
```
39

40
### HTTP Methods
41

42
Supports all standard HTTP methods through the `method` option.
43

44
```javascript { .api }
45
interface RequestOptions {
46
  method?: string; // 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
47
}
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
// GET request (default)
54
reqwest({ url: '/api/users' });
55

56
// POST request
57
reqwest({
58
  url: '/api/users',
59
  method: 'POST',
60
  data: { name: 'Bob', age: 25 }
61
});
62

63
// PUT request
64
reqwest({
65
  url: '/api/users/123',
66
  method: 'PUT',
67
  data: { name: 'Robert', age: 26 }
68
});
69

70
// DELETE request
71
reqwest({
72
  url: '/api/users/123',
73
  method: 'DELETE'
74
});
75
```
76

77
### Response Types
78

79
Automatic content type detection and manual type specification for various response formats.
80

81
```javascript { .api }
82
interface RequestOptions {
83
  type?: string; // 'json' | 'xml' | 'html' | 'text' | 'js' | 'jsonp'
84
}
85
```
86

87
**Usage Examples:**
88

89
```javascript
90
// JSON response (auto-parsed)
91
reqwest({
92
  url: '/api/data.json',
93
  type: 'json',
94
  success: function(data) {
95
    console.log(data.users); // Already parsed as JavaScript object
96
  }
97
});
98

99
// XML response
100
reqwest({
101
  url: '/api/data.xml',
102
  type: 'xml',
103
  success: function(xmlDoc) {
104
    const items = xmlDoc.getElementsByTagName('item');
105
  }
106
});
107

108
// JSONP for cross-domain requests
109
reqwest({
110
  url: 'https://external-api.com/data.jsonp?callback=?',
111
  type: 'jsonp',
112
  success: function(data) {
113
    console.log('External data:', data);
114
  }
115
});
116
```
117

118
### Request Data
119

120
Multiple formats for sending data with requests.
121

122
```javascript { .api }
123
interface RequestOptions {
124
  data?: any; // Object | string | FormData | Array
125
  processData?: boolean; // Whether to process data (default: true)
126
}
127
```
128

129
**Usage Examples:**
130

131
```javascript
132
// Object data (automatically serialized)
133
reqwest({
134
  url: '/api/users',
135
  method: 'POST',
136
  data: { name: 'Charlie', age: 30 }
137
});
138

139
// Array of name/value pairs
140
reqwest({
141
  url: '/api/search',
142
  method: 'POST',
143
  data: [
144
    { name: 'query', value: 'javascript' },
145
    { name: 'type', value: 'tutorial' }
146
  ]
147
});
148

149
// Pre-serialized string data
150
reqwest({
151
  url: '/api/raw',
152
  method: 'POST',
153
  data: 'name=Dave&age=35',
154
  processData: false
155
});
156

157
// FormData object
158
const formData = new FormData();
159
formData.append('file', fileInput.files[0]);
160
reqwest({
161
  url: '/api/upload',
162
  method: 'POST',
163
  data: formData,
164
  processData: false
165
});
166
```
167

168
### Headers and Content Type
169

170
Custom headers and content type specification.
171

172
```javascript { .api }
173
interface RequestOptions {
174
  headers?: Object; // Custom request headers
175
  contentType?: string; // Request Content-Type header
176
}
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
// Custom headers
183
reqwest({
184
  url: '/api/protected',
185
  headers: {
186
    'Authorization': 'Bearer ' + token,
187
    'X-Custom-Header': 'custom-value',
188
    'Accept': 'application/json'
189
  }
190
});
191

192
// JSON content type
193
reqwest({
194
  url: '/api/json-endpoint',
195
  method: 'POST',
196
  contentType: 'application/json',
197
  data: JSON.stringify({ key: 'value' }),
198
  processData: false
199
});
200

201
// Form content type (default)
202
reqwest({
203
  url: '/api/form-endpoint',
204
  method: 'POST',
205
  contentType: 'application/x-www-form-urlencoded',
206
  data: { field1: 'value1', field2: 'value2' }
207
});
208
```
209

210
### Cross-Origin Requests
211

212
CORS and credential support for cross-domain requests.
213

214
```javascript { .api }
215
interface RequestOptions {
216
  crossOrigin?: boolean; // Enable cross-origin requests
217
  withCredentials?: boolean; // Include credentials in cross-origin requests
218
}
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
// Basic cross-origin request
225
reqwest({
226
  url: 'https://api.external.com/data',
227
  crossOrigin: true,
228
  success: function(data) {
229
    console.log('Cross-origin data:', data);
230
  }
231
});
232

233
// Cross-origin with credentials (cookies, auth)
234
reqwest({
235
  url: 'https://secure.external.com/user-data',
236
  crossOrigin: true,
237
  withCredentials: true,
238
  headers: { 'Authorization': 'Bearer ' + token }
239
});
240
```
241

242
### JSONP Configuration
243

244
Specialized configuration for JSONP requests.
245

246
```javascript { .api }
247
interface RequestOptions {
248
  jsonpCallback?: string; // JSONP callback parameter name
249
  jsonpCallbackName?: string; // Specific callback function name
250
}
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
// Automatic JSONP callback
257
reqwest({
258
  url: 'https://api.example.com/data.jsonp?callback=?',
259
  type: 'jsonp',
260
  success: function(data) {
261
    console.log('JSONP data:', data);
262
  }
263
});
264

265
// Custom callback parameter name
266
reqwest({
267
  url: 'https://api.example.com/data.jsonp',
268
  type: 'jsonp',
269
  jsonpCallback: 'mycallback', // Uses ?mycallback=reqwest_12345
270
  success: function(data) {
271
    console.log('JSONP data:', data);
272
  }
273
});
274

275
// Specific callback function name
276
reqwest({
277
  url: 'https://api.example.com/data.jsonp?cb=handleData',
278
  type: 'jsonp',
279
  jsonpCallback: 'cb',
280
  jsonpCallbackName: 'handleData',
281
  success: function(data) {
282
    console.log('JSONP data:', data);
283
  }
284
});
285
```
286

287
### Advanced Configuration
288

289
Additional configuration options for specialized use cases.
290

291
```javascript { .api }
292
interface RequestOptions {
293
  timeout?: number; // Request timeout in milliseconds
294
  async?: boolean; // Asynchronous flag (default: true)
295
  xhr?: Function; // Custom XHR factory function
296
  before?: Function; // Pre-request callback with XHR object
297
  dataFilter?: Function; // Response filtering function
298
}
299
```
300

301
**Usage Examples:**
302

303
```javascript
304
// Request timeout
305
reqwest({
306
  url: '/api/slow-endpoint',
307
  timeout: 10000, // 10 seconds
308
  error: function(xhr, type, err) {
309
    if (type === 'timeout') {
310
      console.log('Request timed out');
311
    }
312
  }
313
});
314

315
// Custom XHR factory
316
reqwest({
317
  url: '/api/data',
318
  xhr: function() {
319
    const xhr = new XMLHttpRequest();
320
    xhr.upload.onprogress = function(e) {
321
      console.log('Upload progress:', (e.loaded / e.total) * 100 + '%');
322
    };
323
    return xhr;
324
  }
325
});
326

327
// Pre-request processing
328
reqwest({
329
  url: '/api/data',
330
  before: function(xhr) {
331
    xhr.setRequestHeader('X-Timestamp', Date.now());
332
    console.log('About to send request');
333
  }
334
});
335

336
// Response filtering
337
reqwest({
338
  url: '/api/wrapped-data',
339
  type: 'json',
340
  dataFilter: function(data, type) {
341
    // Remove wrapper from API response
342
    return type === 'json' ? data.result : data;
343
  }
344
});
345
```
346

347
## Request Object Methods
348

349
The object returned by `reqwest()` provides additional control methods:
350

351
### Abort Request
352

353
```javascript { .api }
354
/**
355
 * Aborts the current request
356
 * @returns {Object} Self for chaining
357
 */
358
abort(): RequestPromise;
359
```
360

361
### Retry Request
362

363
```javascript { .api }
364
/**
365
 * Retries the request with the same options
366
 * @returns {Object} Self for chaining
367
 */
368
retry(): RequestPromise;
369
```
370

371
**Usage Examples:**
372

373
```javascript
374
// Abort request
375
const request = reqwest({ url: '/api/large-data' });
376
setTimeout(() => {
377
  request.abort();
378
}, 5000);
379

380
// Retry failed request
381
reqwest({ url: '/api/unreliable' })
382
  .fail(function(xhr, type, err) {
383
    console.log('First attempt failed, retrying...');
384
    return this.retry();
385
  })
386
  .then(function(data) {
387
    console.log('Success on retry:', data);
388
  });
389
```