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.
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.
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.
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