or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

core-requests.md index.md jquery-compat.md promise-interface.md utilities.md

tile.json

tessl/npm-reqwest

A wrapper for asynchronous HTTP requests supporting XMLHttpRequest, JSONP, CORS, and CommonJS Promises

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/reqwest@2.0.x

To install, run

npx @tessl/cli install tessl/npm-reqwest@2.0.0

Reqwest

Reqwest is a comprehensive AJAX library providing XMLHttpRequest, JSONP, CORS, and CommonJS Promises support. It offers a flexible API for making asynchronous HTTP requests with extensive configuration options, cross-browser compatibility (IE6+), and a promise-like interface for modern JavaScript development.

Package Information

Package Name: reqwest
Package Type: npm
Language: JavaScript
Installation: npm install reqwest

Core Imports

import reqwest from "reqwest";

For CommonJS:

const reqwest = require("reqwest");

For browser environments:

<script src="reqwest.js"></script>
<!-- reqwest is available as global variable -->

Basic Usage

// Simple GET request
reqwest('path/to/data.json', function(resp) {
  console.log(resp);
});

// POST request with data
reqwest({
  url: 'path/to/api',
  method: 'post',
  data: { name: 'John', age: 30 },
  success: function(resp) {
    console.log('Success:', resp);
  },
  error: function(err) {
    console.log('Error:', err);
  }
});

// Using promises
reqwest({
  url: 'path/to/data.json',
  type: 'json'
})
.then(function(resp) {
  console.log('Data:', resp);
})
.catch(function(err) {
  console.log('Error:', err);
});

Node.js Usage

Reqwest can be used in Node.js environments through the xhr2 peer dependency:

npm install reqwest xhr2

const reqwest = require('reqwest');

// Works the same as in browser environments
reqwest({
  url: 'https://api.example.com/data',
  type: 'json'
})
.then(function(data) {
  console.log('Data:', data);
})
.catch(function(err) {
  console.error('Error:', err);
});

Note: For comprehensive Node.js HTTP client functionality, consider using specialized libraries like mikeal/request as reqwest is primarily designed for browser environments.

Architecture

Reqwest provides a comprehensive AJAX solution built around several key concepts:

Universal API: Single function interface that handles multiple request patterns (URL string, options object)
Cross-browser Support: Automatic XHR selection (XMLHttpRequest, XDomainRequest, ActiveXObject) based on browser capabilities
Promise-like Interface: Chainable methods (then, fail, always, catch) for modern async patterns
Multiple Response Types: Automatic or manual content type handling (JSON, JSONP, XML, HTML, Text)
Utility Functions: Form serialization and query string utilities for data processing
Framework Integration: Built-in Ender support and jQuery compatibility layer

Capabilities

Core Request Functionality

Primary AJAX request functionality supporting all HTTP methods, multiple data formats, and comprehensive configuration options.

/**
 * Creates and executes an AJAX request
 * @param {string|Object} options - URL string or configuration object
 * @param {Function} callback - Optional success callback
 * @returns {Object} Request object with promise-like interface
 */
function reqwest(options, callback);

interface RequestOptions {
  url: string;
  method?: string; // Default: 'GET'
  type?: string; // 'json' | 'xml' | 'html' | 'text' | 'js' | 'jsonp'
  data?: any; // Request data (object, string, FormData)
  headers?: Object; // Custom headers
  contentType?: string; // Request content type
  timeout?: number; // Request timeout in milliseconds
  async?: boolean; // Asynchronous flag (default: true)
  processData?: boolean; // Whether to process data (default: true)
  crossOrigin?: boolean; // Enable cross-origin requests
  withCredentials?: boolean; // Include credentials in cross-origin requests
  success?: Function; // Success callback
  error?: Function; // Error callback
  complete?: Function; // Always-called completion callback
  before?: Function; // Pre-request callback with XHR object
  jsonpCallback?: string; // JSONP callback parameter name
  jsonpCallbackName?: string; // Specific JSONP callback function name
  xhr?: Function; // Custom XHR factory function
  dataFilter?: Function; // Response filtering function
}

Core Requests

Promise-like Interface

Chainable methods for handling request success, failure, and completion with modern async patterns.

interface RequestPromise {
  then(success?: Function, fail?: Function): RequestPromise;
  fail(fn: Function): RequestPromise;
  always(fn: Function): RequestPromise;
  catch(fn: Function): RequestPromise;
  abort(): RequestPromise;
  retry(): RequestPromise;
}

Promise Interface

Form Serialization Utilities

Comprehensive form handling utilities for converting form elements to various data formats (query strings, objects, arrays).

/**
 * Serializes form elements to various formats
 * @param {Element|NodeList} elements - Form elements to serialize
 * @param {Object} options - Serialization options
 * @returns {string|Object|Array} Serialized data
 */
reqwest.serialize(elements, options);

/**
 * Serializes form elements to array of name/value pairs
 * @param {Element|NodeList} elements - Form elements
 * @returns {Array} Array of {name, value} objects
 */
reqwest.serializeArray(elements);

/**
 * Converts object to URL query string
 * @param {Object} object - Data to serialize
 * @param {boolean} traditional - Use traditional array serialization
 * @returns {string} Query string
 */
reqwest.toQueryString(object, traditional);

/**
 * Gets the JSONP callback prefix used for generating callback names
 * @returns {string} Callback prefix string
 */
reqwest.getcallbackPrefix();

Utilities

Configuration and Compatibility

Global configuration options and jQuery/Zepto compatibility layer for seamless migration from other AJAX libraries.

/**
 * Sets global default options for all requests
 * @param {Object} options - Global configuration options
 */
reqwest.ajaxSetup(options);

/**
 * jQuery/Zepto compatibility layer
 * @param {Object} options - jQuery-style options
 * @param {Function} callback - Optional success callback
 * @returns {Object} Request object
 */
reqwest.compat(options, callback);

jQuery Compatibility

Types

/**
 * Callback function for successful requests
 * @param {any} response - Parsed response data (JSON, XML, HTML, text, etc.)
 */
type SuccessCallback = (response: any) => void;

/**
 * Callback function for failed requests
 * @param {XMLHttpRequest} xhr - XMLHttpRequest object that failed
 * @param {string} message - Error message ('Request is aborted: timeout', etc.)
 * @param {any} error - Additional error context (parsing errors, etc.)
 */
type ErrorCallback = (xhr: XMLHttpRequest, message: string, error: any) => void;

/**
 * Callback function always called on completion
 * @param {any} response - Response data (same as success) or XMLHttpRequest object (on error)
 */
type CompleteCallback = (response: any) => void;

/**
 * Pre-request callback function
 * @param {XMLHttpRequest} xhr - XMLHttpRequest object before sending
 */
type BeforeCallback = (xhr: XMLHttpRequest) => void;

/**
 * Response filtering function
 * @param {any} data - Raw response data
 * @param {string} type - Response type
 * @returns {any} Filtered response data
 */
type DataFilter = (data: any, type: string) => any;