To help you get started, we've collected the most common ways that popsicle is being used within popular public projects.

jcoreio / crater / test / integration / integrationTests.js View on Github

async function navigateTo(url) {
  if (process.env.DUMP_HTTP) {
    const res = await popsicle.get(url)
    /* eslint-disable no-console */
    console.log(`GET ${url} ${res.status}`)
    console.log(res.headers)
    console.log(res.body)
    /* eslint-enable no-console */
  }
  await browser.url(url)
}

View more ways to use popsicle

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

Installation

npm install popsicle --save

Usage

import { fetch } from "popsicle";

const res = await fetch("https://example.com");
const data = await res.text();

> Popsicle is a universal package, meaning node.js and browsers are supported without any configuration. This means the primary endpoint requires some dom types in TypeScript. When in a node.js or browser only environments prefer importing popsicle/dist/{node,browser} instead.

Popsicle re-exports Request, Response, Headers and AbortController from servie. The fetch function accepts the same arguments as Request and returns a promise that resolves to Response. You can use the Signal event emitter (from AbortController#signal) to listen to request life cycle events.

Browser

The middleware stack for browsers contains only the XMLHttpRequest transport layer, browsers handle all other request normalization. This means a smaller and faster package for browsers.

Node.js

The middleware stack for node.js includes normalization to act similar to browsers:

• Default User-Agent (Learn more)
• Decodes gzip, deflate and brotli (Learn more)
• Follows HTTP redirects (Learn more)
• In-memory cookie cache (Learn more)
• Automatic HTTP2 and HTTP1 support and DNS caching (Learn more)

> Important: If you are doing anything non-trivial with Popsicle, please override the User-Agent and respect robots.txt.

Recipes

Aborting a Request

import { fetch, AbortController } from "popsicle";

const controller = new AbortController();

setTimeout(() => controller.abort(), 500);

const res = fetch("https://example.com", {
  signal: controller.signal,
});

Errors

Transports can return an error. 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)

Customization

Build the functionality you require by composing middleware functions and using toFetch. See src/node.ts for an example.

Plugins

• Popsicle Status - Reject on invalid HTTP status codes
• Popsicle Retry - Retry HTTP requests on bad server responses

Creating Plugins

See Throwback for more information:

type Plugin = (
  req: Request,
  next: () => Promise,
) => Promise;

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