tessl/npm-superagent

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

SuperAgent

Name: tessl/npm-superagent
Author: tessl

SuperAgent is a comprehensive HTTP client library that provides a fluent, chainable API for making HTTP requests in both Node.js and browser environments. It offers advanced features including automatic request/response parsing, authentication support, file uploads, promise and callback support, request cancellation, built-in retry logic, and extensive plugin ecosystem.

Package Information

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

Core Imports

const superagent = require('superagent');

For ES modules:

import superagent from 'superagent';

For specific imports:

const { agent, serialize, parse } = require('superagent');

Basic Usage

const superagent = require('superagent');

// GET request with callback
superagent
  .get('https://api.example.com/users')
  .set('Authorization', 'Bearer token')
  .end((err, res) => {
    if (err) throw err;
    console.log(res.body);
  });

// POST request with promise
superagent
  .post('https://api.example.com/users')
  .send({ name: 'John', email: 'john@example.com' })
  .set('Content-Type', 'application/json')
  .then(res => console.log(res.body))
  .catch(err => console.error(err));

// Async/await usage
(async () => {
  try {
    const res = await superagent
      .get('https://api.example.com/users/123')
      .query({ include: 'profile' });
    console.log(res.body);
  } catch (err) {
    console.error(err);
  }
})();

Architecture

SuperAgent is built around several key components:

Request Factory: Main function that creates Request instances for different HTTP methods
Request Class: Chainable request builder with fluent API for configuration and execution
Response Class: Structured response object with parsed data, headers, and metadata
Agent Class: Session manager for cookie persistence, connection pooling, and default settings
Parser/Serializer System: Pluggable content-type handlers for request/response transformation
Plugin System: Extensible architecture via .use() method for custom middleware

Capabilities

HTTP Request Methods

Core HTTP method functions for making requests with fluent chainable interface.

function get(url, data?, callback?): Request;
function post(url, data?, callback?): Request;
function put(url, data?, callback?): Request;
function patch(url, data?, callback?): Request;
function del(url, data?, callback?): Request;
function delete(url, data?, callback?): Request;
function head(url, data?, callback?): Request;
function options(url, data?, callback?): Request;

HTTP Methods

Request Building

Comprehensive request configuration with headers, query parameters, body data, and request options.

// Request building methods
Request.prototype.set(field, value): Request;
Request.prototype.get(field): string;
Request.prototype.getHeader(field): string;
Request.prototype.unset(field): Request;
Request.prototype.type(type): Request;
Request.prototype.accept(type): Request;
Request.prototype.query(value): Request;  
Request.prototype.send(data): Request;
Request.prototype.withCredentials(enabled?): Request;
Request.prototype.use(fn): Request;
Request.prototype.toJSON(): object;

Request Building

Authentication & Security

Authentication methods and TLS/SSL certificate configuration for secure communications.

Request.prototype.auth(user, password?, options?): Request;
Request.prototype.http2(enabled?): Request;
Request.prototype.ca(cert): Request;
Request.prototype.key(cert): Request;
Request.prototype.cert(cert): Request;
Request.prototype.pfx(cert): Request;
Request.prototype.disableTLSCerts(): Request;

Authentication & Security

File Uploads

Multipart form data support for file uploads and form submissions.

Request.prototype.attach(field, file, options?): Request;
Request.prototype.field(name, value): Request;

File Uploads

Request Execution & Flow Control

Request execution, timeout management, retry logic, and response streaming.

Request.prototype.end(callback?): Request;
Request.prototype.then(resolve, reject?): Promise<Response>;
Request.prototype.catch(reject): Promise<Response>;
Request.prototype.timeout(options): Request;
Request.prototype.retry(count, callback?): Request;
Request.prototype.abort(): Request;
Request.prototype.pipe(stream, options?): stream;

Request Execution

Agent & Session Management

Agent-based session management with cookie persistence and connection pooling.

function agent(options?): Agent;

class Agent {
  constructor(options?);
  get(url, data?, callback?): Request;
  post(url, data?, callback?): Request;
  // ... all HTTP methods available
}

Agent & Sessions

Response Handling

Response object properties and methods for accessing response data, headers, and metadata.

class Response {
  status: number;
  statusCode: number;
  text: string;
  body: any;
  header: object;
  type: string;
  charset: string;
  redirects: string[];
  get(field): string;
}

Response Handling

Parsers & Serializers

Configurable content-type parsing and serialization for different data formats.

// Global configuration objects
serialize['application/json']: Function;
serialize['application/x-www-form-urlencoded']: Function;
parse['application/json']: Function;
parse['text/plain']: Function;
parse['image/*']: Function;

// Per-request customization
Request.prototype.parse(fn): Request;
Request.prototype.serialize(fn): Request;

Parsers & Serializers

Types

interface Request {
  method: string;
  url: string;
  header: object;
  cookies: string;
  qs: object;
}

interface Response {
  status: number;
  statusCode: number;
  text: string;
  body: any;
  header: object;
  type: string;
  charset: string;
  redirects: string[];
  files?: object;
  links: object;
  statusType: number;
  info: boolean;
  ok: boolean;
  redirect: boolean;
  clientError: boolean;
  serverError: boolean;
  error: boolean | Error;
  created: boolean;
  accepted: boolean;
  noContent: boolean;
  badRequest: boolean;
  unauthorized: boolean;
  forbidden: boolean;
  notFound: boolean;
  notAcceptable: boolean;
  unprocessableEntity: boolean;
  get(field: string): string;
  toError(): Error;
}

interface Agent {
  jar: CookieJar;
}

interface SerializerFunction {
  (obj: any): string;
}

interface ParserFunction {
  (res: Response, callback: (err: Error | null, body?: any, files?: object) => void): void;
}