JarCasting
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
domtypes in TypeScript. When in a node.js or browser only environments prefer importingpopsicle/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,deflateandbrotli(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-Agentand respectrobots.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
- 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<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
$httpservice
License
MIT
