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 { 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: () => 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