Registry / http-networking / popsicle-status

popsicle-status

library3.0.0jsnpmunverified

Popsicle Status is a middleware for the `popsicle` HTTP client library, designed to automatically reject HTTP responses with undesirable status codes. It provides a simple function, `status(min?: number, max?: number)`, which returns a middleware that validates a response's status code against a specified inclusive `min` and exclusive `max` range. By default, it rejects any status outside the 200-399 range (i.e., anything not a 2xx or 3xx success/redirection code). The current stable version is `3.0.0`. This library is actively maintained, with releases primarily aligning with major updates to its peer dependencies, `popsicle` and `servie`, to ensure compatibility. Its key differentiator is its seamless integration into the `popsicle` middleware chain, simplifying error handling by transforming invalid HTTP responses into thrown errors, making control flow clearer than manual status checks.

http-networking

npm install popsicle-status

github ↗package ↗

INSTALL

IMPORT

SIG · POPSICLE-STATUS

popsicle-status

http-networkingjavascriptv3.0.0

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.

status

✓ import { status } from 'popsicle-status';

✗ const { status } = require('popsicle-status');

The library is written in TypeScript and primarily designed for ESM consumption, though CJS builds are provided. Prefer named imports for tree-shaking and type safety.

Middleware

✓ import type { Middleware } from 'popsicle';

✗ import { Middleware } from 'popsicle-status';

While `popsicle-status` produces a `Middleware` function, the `Middleware` type itself is typically imported from `popsicle` or `servie` if needed for type annotations.

Demonstrates how to apply the `status` middleware to a `popsicle` request, configuring it to only allow 2xx responses, and handling both successful and rejected outcomes.

import { status } from 'popsicle-status'; import { Request, Response } from 'popsicle'; // Assuming popsicle types are available async function main() { const statusMiddleware = status(200, 300); // Configure to only allow 2xx responses // Mock popsicle's internal `send` function for demonstration const mockSend = async (req: Request): Promise<Response> => { if (req.url === 'https://example.com/success') { return { url: req.url, status: 200, statusText: 'OK', headers: {}, body: 'Success!', clone: () => ({ ...this }) } as Response; } if (req.url === 'https://example.com/bad-request') { return { url: req.url, status: 400, statusText: 'Bad Request', headers: {}, body: 'Bad', clone: () => ({ ...this }) } as Response; } throw new Error('Unexpected request URL'); }; // Create a dummy request object const createRequest = (url: string): Request => ({ url, method: 'GET', headers: {}, body: null, clone: () => ({ ...this }) } as Request); console.log('--- Testing a successful request (200 OK) ---'); try { const reqSuccess = createRequest('https://example.com/success'); const resSuccess = await statusMiddleware(reqSuccess, mockSend); console.log(`Success! Status: ${resSuccess.status}, Body: ${await resSuccess.body}`); } catch (err: any) { console.error(`Unexpected error for success: ${err.message}`); } console.log('\n--- Testing a failing request (400 Bad Request) ---'); try { const reqFail = createRequest('https://example.com/bad-request'); const resFail = await statusMiddleware(reqFail, mockSend); // This should throw due to status filter console.log(`Unexpected success for failure: Status: ${resFail.status}`); } catch (err: any) { console.error(`Caught expected error: ${err.message}`); if (err.res) { console.log(`Error includes response object. Status: ${err.res.status}`); } } } main();

Debug

Known issues

breakingVersion 3.0.0 introduced a refactor for 'Servie 4' compatibility. This means users of `popsicle-status` will need to ensure their `servie` peer dependency is at version 4.x.

fix

Update the `servie` peer dependency to `^4.0.0`. If unable to update, remain on `popsicle-status@2.x`.

affects: >=3.0.0

breakingVersion 2.0.0 updated the middleware signature to align with `popsicle@6.x`. Middleware functions now expect a different signature, which will break compatibility with older `popsicle` versions (e.g., `5.x` or earlier).

fix

Ensure `popsicle` is updated to version `6.x` or newer. If stuck on an older `popsicle` version, use `popsicle-status@1.x`.

affects: >=2.0.0

breakingVersion 0.2.1 changed the error handling mechanism from resolving with a `Promise` to explicitly throwing an error. Code that previously awaited a rejected promise might now require `try/catch` blocks.

fix

Refactor error handling code to use `try/catch` blocks around calls that use `popsicle-status` middleware, as it will now throw an `Error` directly instead of returning a rejected promise.

affects: >=0.2.1

gotchaSince version 2.0.1, the error object thrown by `popsicle-status` now includes a `res` property, providing direct access to the `Response` object that caused the error. This is not a breaking change but alters the error object's structure.

fix

When catching errors from `popsicle-status`, you can now safely access `err.res` for the full response object if you need to inspect headers or other response details.

affects: >=2.0.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'url') or The middleware function signature is incorrect.

Using `popsicle-status@2.x` or higher with an incompatible version of `popsicle` (e.g., `popsicle@5.x`), leading to a mismatch in the middleware function signature.

fix

Update `popsicle` to `^6.0.0` or downgrade `popsicle-status` to `1.x` to match your `popsicle` version.

Error: Peer dependency 'servie' is not met. Required: '^4.0.0'

`popsicle-status@3.x` requires `servie@^4.0.0` as a peer dependency, but an older or incompatible version is installed or missing.

fix

Install or update `servie` to a compatible version: `npm install servie@^4.0.0` or `yarn add servie@^4.0.0`.

UnhandledPromiseRejectionWarning: HttpError: Bad Request (400)

Code written for `popsicle-status` versions prior to `0.2.1` that expected rejected promises for bad statuses, but `0.2.1` and later throw errors directly, leading to unhandled rejections if not caught.

fix

Wrap your `popsicle` requests using `popsicle-status` middleware in `try/catch` blocks to explicitly handle the thrown `HttpError`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

servierequiredPeer dependency required for middleware signature compatibility, especially since v3.0.0 which refactored for Servie 4 support.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/blakeembrey/popsicle-status ↗

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