Popsicle HTTP Client

Common errors

• Error: EUNAVAILABLE: Unable to connect to the remote URL

  cause 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

  cause 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

  cause 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

  cause 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');`.

Warnings

• breaking Version 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.
• gotcha The 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.
• gotcha A 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.
• gotcha When 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.
• breaking Middleware 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.

Install

• npm install popsicle npm
• yarn add popsicle yarn
• pnpm add popsicle pnpm

Imports

• fetch
  wrong:

  import fetch from 'popsicle';

  correct:

  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
  wrong:

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

  correct:

  import { AbortController } from 'popsicle';

  Re-exported from the underlying `servie` library, similar to the Web API `AbortController`.
• Request, Response, Headers
  wrong:

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

  correct:

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

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

Quickstart

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();