popsicle

library0.9.6jsnpmunverified

Popsicle is an advanced HTTP client library designed for both Node.js and browser environments, currently stable at version 12.1.2. It provides a fetch-like API, built upon the `Servie` request and response interfaces, offering a universal solution without requiring environment-specific configuration by default. Releases typically involve patch updates for bug fixes and dependency management, with major versions introducing significant architectural changes, such as the `Servie 4` migration in v12.0.0. Key differentiators include its modular middleware architecture, which allows for extensive customization, and its optimized bundles for different environments. Node.js environments benefit from built-in features like User-Agent handling, content encoding decoding, redirect following, and an in-memory cookie cache, while browser builds are lighter, focusing solely on the `XMLHttpRequest` transport layer. This design allows developers to compose functionality and create highly tailored HTTP clients.

http-networking

npm install popsicle

github ↗package ↗

INSTALL

IMPORT

SIG · POPSICLE

popsicle

http-networkingjavascriptv0.9.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetch

✓ import { fetch } from 'popsicle';

✗ import fetch from 'popsicle';

The primary `fetch` function is a named export. For Node.js or browser-only environments, consider `import { fetch } from 'popsicle/dist/node';` or `import { fetch } from 'popsicle/dist/browser';` respectively to avoid `dom` types and optimize bundle size.

AbortController

✓ import { AbortController } from 'popsicle';

✗ const AbortController = require('popsicle').AbortController;

Re-exported from the underlying `servie` library, similar to the Web API `AbortController`.

Request, Response, Headers

✓ import { Request, Response, Headers } from 'popsicle';

✗ const Request = require('popsicle').Request;

These classes are re-exported from `servie` and are compatible with the Web Fetch API interfaces.

Demonstrates making an HTTP GET request using `fetch` and gracefully handling request abortion via `AbortController`.

import { fetch, AbortController } from "popsicle"; const controller = new AbortController(); const signal = controller.signal; // Simulate aborting the request after 500ms setTimeout(() => { console.log('Aborting request...'); controller.abort(); }, 500); async function makeRequest() { try { // Replace with a valid API endpoint for testing const res = await fetch("https://jsonplaceholder.typicode.com/todos/1", { signal }); if (!res.ok) { throw new Error(`HTTP error! Status: ${res.status}`); } const data = await res.json(); console.log("Response data:", data); } catch (error: any) { if (signal.aborted) { console.log(`Request was aborted: ${error.name}`); } else { console.error(`Request failed unexpectedly: ${error.message}`); } } } makeRequest();

Debug

Known issues

breakingVersion 12.0.0 introduced significant breaking changes by migrating to `Servie 4` interfaces and refactoring middleware. The `popsicle` package now primarily provides a `fetch`-like entry point, with most advanced middleware functionality extracted into separate reusable packages. Code relying on older middleware patterns or `Servie 3` interfaces will require updates.

fix

Review the new `Servie 4` documentation and update your request/response handling. Migrate custom middleware to the new plugin system, potentially leveraging `throwback` and `servie` for composition.

affects: >=12.0.0

gotchaThe default universal entry point (`popsicle`) requires DOM types in TypeScript projects, which can cause issues in pure Node.js environments if not configured correctly. This is due to its browser compatibility. To avoid this, explicit environment-specific imports are recommended.

fix

For Node.js-only projects, import from `popsicle/dist/node`. For browser-only projects, import from `popsicle/dist/browser`. This ensures you get an optimized bundle without unnecessary DOM types.

affects: >=12.0.0

gotchaA vulnerability in `popsicle-cookie-jar` (which `popsicle` uses in Node.js) was identified that could affect custom setups, particularly in versions prior to 12.1.1. This could lead to unexpected cookie handling or potential security issues.

fix

Upgrade to `popsicle@12.1.1` or newer to ensure you have the patched version of `popsicle-cookie-jar` and are protected from this vulnerability.

affects: <12.1.1

gotchaWhen performing non-trivial HTTP requests (e.g., scraping, interacting with public APIs), it is crucial to override the default `User-Agent` and respect `robots.txt` to avoid being blocked or violating server policies.

fix

Explicitly set the `User-Agent` header in your requests. Implement logic to parse and respect `robots.txt` directives for the target domain, and consider rate-limiting your requests.

affects: *

breakingMiddleware functionality underwent a significant architectural change in version 12.0.0. The core `popsicle` package now serves more as an example of middleware composition, with advanced functionalities like user-agent setting, content encoding, redirects, and cookie handling moved to independent `popsicle-*` packages. Existing custom middleware or configurations might break.

fix

Review the `serviejs` organization for specific `popsicle-*` middleware packages and adapt your application to explicitly import and compose the required middleware for advanced features.

affects: >=12.0.0

Errors

Common errors & fixes

Error: EUNAVAILABLE: Unable to connect to the remote URL

The HTTP client failed to establish a connection to the target server, often due to network issues, incorrect hostname, or the server being offline.

fix

Verify network connectivity, confirm the URL is correct and accessible, and ensure the target server is running and listening on the specified port.

TypeError: Invalid URL

The URL provided to the `fetch` function is syntactically incorrect or malformed, preventing the request from being initiated.

fix

Double-check the URL string passed to `fetch` for proper formatting, including the protocol (e.g., `http://` or `https://`), domain name, and path segments.

RangeError: EMAXREDIRECTS: Maximum number of redirects exceeded

The request followed too many HTTP redirects (default limit is typically 20), indicating a potential redirect loop or an overly long redirect chain on the server side (Node.js only).

fix

Inspect the URL and server configuration for redirect loops. If legitimate, you might be able to configure a higher redirect limit, though this is often a symptom of misconfiguration.

TypeError: fetch is not a function

This typically occurs when attempting to use `fetch` with CommonJS `require` syntax without correctly destructuring the named export, or incorrectly assuming it's a default export.

fix

For ESM, use `import { fetch } from 'popsicle';`. For CommonJS, use `const { fetch } = require('popsicle');`.

Upgrade

Version history

0.9.6latest on npm

Audit

Dependencies

servierequiredCore request and response interfaces, providing the underlying fetch-like API.

popsicle-cookie-jarrequiredHandles in-memory cookie caching and management for Node.js environments.

popsicle-transport-httprequiredProvides the HTTP/HTTPS transport layer for Node.js requests.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/serviejs/popsicle ↗

packagehttps://www.npmjs.com/package/popsicle ↗