Awesome Open Source
Awesome Open Source

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 { fetch } from "popsicle";

const res = await fetch("http://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:

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("http://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

Creating Plugins

See Throwback for more information:

type Plugin = (
  req: Request,
  next: () => Promise<Response>
) => 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


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (67,985
typescript (10,331
node (951
http (894
browser (431
promise (200
plugins (134
request (80
transport (38

Find Open Source By Browsing 7,000 Topics Across 59 Categories