popsicle

What is popsicle?

Popsicle is a versatile HTTP request library for Node.js and the browser. It provides a simple and consistent API for making HTTP requests, handling responses, and managing various aspects of HTTP communication such as headers, query parameters, and request/response bodies.

What are popsicle's main functionalities?

Making HTTP Requests

This feature allows you to make HTTP requests to a specified URL. The example demonstrates a GET request to a JSON placeholder API, logging the status and body of the response.

const { request } = require('popsicle');

request('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    console.log(response.status);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Handling Query Parameters

This feature allows you to include query parameters in your HTTP requests. The example demonstrates a GET request with a query parameter to filter posts by userId.

const { request } = require('popsicle');

request({
  url: 'https://jsonplaceholder.typicode.com/posts',
  query: { userId: 1 }
})
  .then(response => {
    console.log(response.status);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Setting Headers

This feature allows you to set custom headers for your HTTP requests. The example demonstrates setting the 'Content-Type' header to 'application/json'.

const { request } = require('popsicle');

request({
  url: 'https://jsonplaceholder.typicode.com/posts',
  headers: { 'Content-Type': 'application/json' }
})
  .then(response => {
    console.log(response.status);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Handling Request and Response Bodies

This feature allows you to handle request and response bodies. The example demonstrates a POST request with a JSON body to create a new post.

const { request } = require('popsicle');

request({
  method: 'POST',
  url: 'https://jsonplaceholder.typicode.com/posts',
  body: { title: 'foo', body: 'bar', userId: 1 },
  headers: { 'Content-Type': 'application/json' }
})
  .then(response => {
    console.log(response.status);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Other packages similar to popsicle

axios

Axios is a popular promise-based HTTP client for the browser and Node.js. It provides a simple API for making HTTP requests and handling responses, similar to Popsicle. Axios is known for its ease of use and wide adoption in the JavaScript community.

node-fetch

Node-fetch is a lightweight module that brings `window.fetch` to Node.js. It is a minimalistic library that provides a simple API for making HTTP requests, similar to the Fetch API in the browser. Node-fetch is often used for its simplicity and compatibility with the Fetch API standard.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with a similar API. It provides a flexible and powerful API for making HTTP requests and handling responses. Superagent is known for its extensive feature set and ease of use.

README

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:

• Default User-Agent
• Support for decoding compressed payloads
• Follows HTTP redirects
• Caches cookies in-memory

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

• 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 $http service

License

MIT