Simple HTTP requests for node and the browser
Switch branches/tags
Clone or download
Latest commit f2710cd May 24, 2018

README.md

Popsicle

NPM version NPM downloads Build status Test coverage Bundle size

Advanced HTTP requests in node.js and browsers, using Servie.

Installation

npm install popsicle --save

Usage

import { transport, request } from 'popsicle'

const req = request('http://example.com') // Creates a `Request` instance.
const res = await transport()(req) // Transports `Request` and returns `Response` instance.

Thin wrapper to transport Servie HTTP request interfaces.

P.S. The default export from popsicle is universal.js. In TypeScript, this can cause trouble with types. Use specific imports such as popsicle/dist/{browser,node,universal} instead, depending on preference.

Node.js Normalization

Normalizes some behavior that happens automatically in browsers (each normalization can be disabled).

  • Default User-Agent insertion
  • Default unzip behaviour of gzip and deflate encoding
  • Follows HTTP redirects

Built-in Transports

HTTP (node.js)

  • unzip: boolean Automatically unzip response bodies (default: true)
  • follow: boolean Automatically follow HTTP redirects (default: true)
  • jar: CookieJar An instance of a cookie jar (jar() from node.js import)
  • maxRedirects: number Override the number of redirects allowed (default: 5)
  • confirmRedirect: Function Validate 307 and 308 redirects (default: () => false)
  • rejectUnauthorized: boolean Reject invalid SSL certificates (default: true)
  • agent: http.Agent Custom http.request agent
  • ca: string | Buffer A string, Buffer or array of strings or Buffers of trusted certificates in PEM format
  • key: string | Buffer Private key to use for SSL
  • cert: string | Buffer Public x509 certificate to use
  • secureProtocol: string Optional SSL method to use

XHR (browsers)

  • type: XMLHttpRequestResponseType Handle the XHR response (default: text)
  • withCredentials: boolean Send cookies with CORS requests (default: false)
  • overrideMimeType: string Override the XHR response MIME type

Errors

Transports can return an error. Errors have a request property set to the request object and a code string. The built-in codes are documented below:

  • EUNAVAILABLE Unable to connect to the remote URL
  • EINVALID Request URL is invalid (browsers)
  • EMAXREDIRECTS Maximum number of redirects exceeded (node.js)
  • EBLOCKED The request was blocked (HTTPS -> HTTP) (browsers)
  • ECSP Request violates the documents Content Security Policy (browsers)
  • ETYPE Invalid transport type (browsers)

Plugins

Coming back soon.

Helpful Utilities

  • throat - Throttle promise-based functions with concurrency support
  • is-browser - Check if your in a browser environment (E.g. Browserify, Webpack)
  • parse-link-header - Handy for parsing HTTP link headers

Creating Plugins

See Throwback for more information:

type Plugin = (req: Request, next: (req?: Request) => Promise<Response>) => Promise<Response>

Transportation Layers

See Servie for more information:

type Transport = (req: Request) => Promise<Response>

TypeScript

This project is written using TypeScript and publishes the types to NPM alongside the package.

Related Projects

  • Superagent - HTTP requests for node and browsers
  • Fetch - Browser polyfill for promise-based HTTP requests
  • Axios - HTTP request API based on Angular's $http service

License

MIT