tessl/npm-superagent

Elegant & feature rich browser / node HTTP with a fluent API

—

Pending

Overview

Eval results

Files

Request Building

Name: tessl/npm-superagent
Author: tessl

Comprehensive request configuration with headers, query parameters, body data, and request options for building HTTP requests with the fluent chainable interface.

Capabilities

Header Management

Methods for setting, getting, and removing HTTP headers.

/**
 * Set request header field to value
 * @param {string|object} field - Header field name or object of field/value pairs
 * @param {string} [value] - Header field value (when field is string)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.set(field, value?): Request;

/**
 * Get request header field value
 * @param {string} field - Header field name
 * @returns {string} Header field value
 */
Request.prototype.get(field): string;

/**
 * Alias for get() - Get request header field value
 * @param {string} field - Header field name
 * @returns {string} Header field value
 */
Request.prototype.getHeader(field): string;

/**
 * Remove request header field
 * @param {string} field - Header field name to remove
 * @returns {Request} Request instance for chaining
 */
Request.prototype.unset(field): Request;

Usage Examples:

const superagent = require('superagent');

// Set single header
superagent
  .post('https://api.example.com/users')
  .set('Authorization', 'Bearer token123')
  .set('User-Agent', 'MyApp/1.0');

// Set multiple headers with object
superagent
  .post('https://api.example.com/users')
  .set({
    'Authorization': 'Bearer token123',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  });

// Get header value
const request = superagent.post('https://api.example.com/users');
request.set('Authorization', 'Bearer token123');
console.log(request.get('Authorization')); // 'Bearer token123'

// Remove header
request.unset('Authorization');

Content Type Management

Convenient methods for setting Content-Type and Accept headers.

/**
 * Set Content-Type header using MIME type or shorthand
 * @param {string} type - MIME type or shorthand (json, form, xml)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.type(type): Request;

/**
 * Set Accept header using MIME type or shorthand
 * @param {string} type - MIME type or shorthand (json, form, xml)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.accept(type): Request;

Usage Examples:

// Using MIME types
superagent
  .post('https://api.example.com/users')
  .type('application/json')
  .accept('application/json');

// Using shorthands
superagent
  .post('https://api.example.com/users')
  .type('json')      // Sets Content-Type: application/json
  .accept('json');   // Sets Accept: application/json

// Common shorthands
superagent.post('/form').type('form');     // application/x-www-form-urlencoded
superagent.post('/xml').type('xml');       // application/xml
superagent.get('/data').accept('text');    // text/plain

Query Parameters

Methods for adding query string parameters to requests.

/**
 * Add query parameters to request URL
 * @param {string|object} value - Query string or object of key/value pairs
 * @returns {Request} Request instance for chaining
 */
Request.prototype.query(value): Request;

Usage Examples:

// Query with object
superagent
  .get('https://api.example.com/users')
  .query({ page: 1, limit: 10, sort: 'name' });
// Results in: https://api.example.com/users?page=1&limit=10&sort=name

// Query with string
superagent
  .get('https://api.example.com/users')
  .query('page=1&limit=10');

// Multiple query calls (cumulative)
superagent
  .get('https://api.example.com/users')
  .query({ page: 1 })
  .query({ limit: 10 })
  .query('sort=name');

// Array values
superagent
  .get('https://api.example.com/users')
  .query({ tags: ['javascript', 'node'] });
// Results in: https://api.example.com/users?tags=javascript&tags=node

Request Body Data

Methods for sending data in the request body.

/**
 * Send data as request body
 * @param {any} data - Data to send (object, string, Buffer, etc.)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.send(data): Request;

Usage Examples:

// JSON data (automatically sets Content-Type)
superagent
  .post('https://api.example.com/users')
  .send({ name: 'John', email: 'john@example.com' });

// Form data
superagent
  .post('https://api.example.com/login')
  .type('form')
  .send({ username: 'user', password: 'pass' });

// String data
superagent
  .post('https://api.example.com/data')
  .type('text')
  .send('Hello World');

// Buffer data
const buffer = Buffer.from('binary data');
superagent
  .post('https://api.example.com/upload')
  .type('application/octet stream')
  .send(buffer);

// Multiple send calls (merged for objects)
superagent
  .post('https://api.example.com/users')
  .send({ name: 'John' })
  .send({ email: 'john@example.com' });
// Results in: { name: 'John', email: 'john@example.com' }

Response Configuration

Methods for configuring response handling and parsing.

/**
 * Set binary response type for browser environments
 * @param {string} type - Response type: 'blob', 'arraybuffer' (browser only)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.responseType(type): Request;

/**
 * Enable or disable response buffering
 * @param {boolean} [enable=true] - Whether to buffer response
 * @returns {Request} Request instance for chaining
 */
Request.prototype.buffer(enable?): Request;

/**
 * Override response parser function
 * @param {function} fn - Custom parser function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.parse(fn): Request;

/**
 * Override request serializer function
 * @param {function} fn - Custom serializer function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.serialize(fn): Request;

Usage Examples:

// Set response type (browser)
superagent
  .get('https://api.example.com/file.pdf')
  .responseType('blob');

// Disable buffering for large responses
superagent
  .get('https://api.example.com/large-file')
  .buffer(false);

// Custom parser
superagent
  .get('https://api.example.com/csv')
  .parse((res, callback) => {
    // Custom CSV parsing logic
    const data = res.text.split('\n').map(line => line.split(','));
    callback(null, data);
  });

// Custom serializer
superagent
  .post('https://api.example.com/data')
  .serialize((obj) => {
    // Custom serialization logic
    return JSON.stringify(obj, null, 2);
  });

Advanced Request Options

Additional configuration options for specialized request handling.

/**
 * Set maximum response size in bytes
 * @param {number} size - Maximum response size
 * @returns {Request} Request instance for chaining
 */
Request.prototype.maxResponseSize(size): Request;

/**
 * Configure redirect handling
 * @param {number} count - Maximum number of redirects to follow
 * @returns {Request} Request instance for chaining
 */
Request.prototype.redirects(count): Request;

/**
 * Custom success condition function
 * @param {function} fn - Function that returns true for successful responses
 * @returns {Request} Request instance for chaining
 */
Request.prototype.ok(fn): Request;

/**
 * Sort query parameters alphabetically
 * @param {boolean} [enabled=true] - Whether to sort query parameters
 * @returns {Request} Request instance for chaining
 */
Request.prototype.sortQuery(enabled?): Request;

Usage Examples:

// Limit response size
superagent
  .get('https://api.example.com/data')
  .maxResponseSize(1024 * 1024); // 1MB limit

// Configure redirects
superagent
  .get('https://api.example.com/redirect')
  .redirects(3); // Follow up to 3 redirects

// Custom success condition
superagent
  .get('https://api.example.com/data')
  .ok(res => res.status < 500); // Treat 4xx as success

// Sort query parameters
superagent
  .get('https://api.example.com/users')
  .query({ z: 1, a: 2, m: 3 })
  .sortQuery(); // Results in: ?a=2&m=3&z=1

Browser & CORS Configuration

Configuration methods for browser environments and cross-origin requests.

/**
 * Enable cross-origin credentials (cookies, authorization headers, TLS client certificates)
 * @param {boolean} [enabled=true] - Whether to send credentials with cross-origin requests
 * @returns {Request} Request instance for chaining
 */
Request.prototype.withCredentials(enabled?): Request;

/**
 * Use plugin or middleware function
 * @param {function} fn - Plugin function that receives and modifies the request
 * @returns {Request} Request instance for chaining
 */
Request.prototype.use(fn): Request;

Usage Examples:

// Enable credentials for cross-origin requests
superagent
  .get('https://api.example.com/private')
  .withCredentials()
  .set('Authorization', 'Bearer token');

// Disable credentials (default for cross-origin)
superagent
  .get('https://api.example.com/public')
  .withCredentials(false);

// Use plugin for request modification
function authPlugin(token) {
  return (req) => {
    req.set('Authorization', `Bearer ${token}`);
  };
}

superagent
  .get('https://api.example.com/data')
  .use(authPlugin('my-token'));

// Multiple plugins can be chained
superagent
  .get('https://api.example.com/data')
  .use(authPlugin('token'))
  .use((req) => {
    req.set('User-Agent', 'MyApp/1.0');
  });

Request Serialization

Methods for converting the request to other formats.

/**
 * Return a JSON representation of the request
 * @returns {object} JSON representation of the request
 */
Request.prototype.toJSON(): object;

Usage Examples:

const request = superagent
  .post('https://api.example.com/users')
  .set('Authorization', 'Bearer token')
  .send({ name: 'John' });

// Get JSON representation
const requestData = request.toJSON();
console.log(requestData);
// {
//   method: 'POST',
//   url: 'https://api.example.com/users',
//   data: { name: 'John' },
//   header: { Authorization: 'Bearer token' }
// }

Install with Tessl CLI