# popsicle

> Advanced HTTP requests in node.js and browsers

Latest version **12.1.2** (published 2023-11-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install popsicle
pnpm add popsicle
yarn add popsicle
bun add popsicle
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 12.1.2 |
| Published | 2023-11-21 |
| First published | 2014-11-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 8 |
| Unpacked size | 22.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 245 |
| Author | Blake Embrey |
| Maintainers | blakeembrey |
| Keywords | request, http, middleware, node, ajax, browser, promise |

## Links

- npm: https://www.npmjs.com/package/popsicle
- Repository: https://github.com/serviejs/popsicle
- Issues: https://github.com/serviejs/popsicle/issues
- npm.io page: https://npm.io/package/popsicle

## Dependencies (8)

- [servie](https://npm.io/package/servie.md) ^4.3.3
- [throwback](https://npm.io/package/throwback.md) ^4.1.0
- [popsicle-redirects](https://npm.io/package/popsicle-redirects.md) ^1.1.0
- [popsicle-cookie-jar](https://npm.io/package/popsicle-cookie-jar.md) ^1.0.1
- [popsicle-user-agent](https://npm.io/package/popsicle-user-agent.md) ^1.0.0
- [popsicle-transport-xhr](https://npm.io/package/popsicle-transport-xhr.md) ^2.0.0
- [popsicle-transport-http](https://npm.io/package/popsicle-transport-http.md) ^1.1.0
- [popsicle-content-encoding](https://npm.io/package/popsicle-content-encoding.md) ^1.0.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 12.1.2 (latest) — 2023-11-21
- 11.0.0-3 (next) — 2018-05-24
- 10.0.1 (legacy) — 2018-05-23
- 12.1.1 — 2023-11-21
- 12.1.0 — 2020-10-07
- 12.0.6 — 2020-09-11
- 12.0.5 — 2019-11-03
- 12.0.4 — 2019-07-05
- 12.0.3 — 2019-06-13
- 12.0.2 — 2019-06-12
- 12.0.1 — 2019-06-11
- 12.0.0 — 2019-06-11
- 11.0.5 — 2019-06-05
- 11.0.4 — 2018-12-05
- 11.0.3 — 2018-11-29
- … 84 more at https://npm.io/package/popsicle/versions

## README

# ![Popsicle](logo.svg)

[![NPM version](https://img.shields.io/npm/v/popsicle.svg?style=flat)](https://npmjs.org/package/popsicle)
[![NPM downloads](https://img.shields.io/npm/dm/popsicle.svg?style=flat)](https://npmjs.org/package/popsicle)
[![Build status](https://img.shields.io/travis/serviejs/popsicle.svg?style=flat)](https://travis-ci.org/serviejs/popsicle)
[![Test coverage](https://img.shields.io/coveralls/serviejs/popsicle.svg?style=flat)](https://coveralls.io/r/serviejs/popsicle?branch=master)
[![Bundle size](https://img.shields.io/bundlephobia/minzip/popsicle.svg)](https://bundlephobia.com/result?p=popsicle)

> Advanced HTTP requests in node.js and browsers, using [Servie](https://github.com/serviejs/servie).

## Installation

```
npm install popsicle --save
```

## Usage

```js
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`](https://github.com/serviejs/servie). The `fetch` function accepts the same arguments as [`Request`](https://github.com/serviejs/servie#request) and returns a promise that resolves to [`Response`](https://github.com/serviejs/servie#response). You can use the [`Signal`](https://github.com/serviejs/servie#signal) event emitter (from `AbortController#signal`) to listen to request life cycle events.

### [Browser](./src/browser.ts)

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](./src/node.ts)

The middleware stack for node.js includes normalization to act similar to browsers:

- Default `User-Agent` ([Learn more](https://github.com/serviejs/popsicle-user-agent))
- Decodes `gzip`, `deflate` and `brotli` ([Learn more](https://github.com/serviejs/popsicle-content-encoding))
- Follows HTTP redirects ([Learn more](https://github.com/serviejs/popsicle-redirects))
- In-memory cookie cache ([Learn more](https://github.com/serviejs/popsicle-cookie-jar))
- Automatic HTTP2 and HTTP1 support and DNS caching ([Learn more](https://github.com/serviejs/popsicle-transport-http))

> **Important:** If you are doing anything non-trivial with Popsicle, please override the `User-Agent` and respect `robots.txt`.

### Recipes

#### Aborting a Request

```ts
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`](./src/node.ts) for an example.

## Plugins

- [Popsicle Status](https://github.com/serviejs/popsicle-status) - Reject on invalid HTTP status codes
- [Popsicle Retry](https://github.com/serviejs/popsicle-retry) - Retry HTTP requests on bad server responses

### Creating Plugins

See [Throwback](https://github.com/serviejs/throwback#usage) for more information:

```ts
type Plugin = (
  req: Request,
  next: () => Promise<Response>,
) => Promise<Response>;
```

## TypeScript

This project is written using [TypeScript](https://github.com/Microsoft/TypeScript) and publishes the types to NPM alongside the package.

## Related Projects

- [Superagent](https://github.com/visionmedia/superagent) - HTTP requests for node and browsers
- [Fetch](https://github.com/github/fetch) - Browser polyfill for promise-based HTTP requests
- [Axios](https://github.com/mzabriskie/axios) - HTTP request API based on Angular's `$http` service

## License

MIT

---
_Source: https://npm.io/package/popsicle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._