popsicle
    TypeScript icon, indicating that this package has built-in type declarations

    12.1.0 • Public • Published

    Popsicle

    NPM version NPM downloads Build status Test coverage Bundle size

    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

    Creating Plugins

    See Throwback for more information:

    type Plugin = (
      reqRequest,
      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

    Install

    npm i popsicle

    DownloadsWeekly Downloads

    225,427

    Version

    12.1.0

    License

    MIT

    Unpacked Size

    22.7 kB

    Total Files

    19

    Last publish

    Collaborators

    • blakeembrey