Registry / http-networking / http-assert

http-assert

JSON →
library1.5.0jsnpmunverified

http-assert is a Node.js module that provides assertion functions designed specifically for HTTP contexts, throwing `HttpError` instances from the widely used `http-errors` package upon assertion failure. It closely mimics the API of Node.js's native `assert` module but extends it by allowing developers to specify an HTTP status code, message, and additional properties for the error object. The current stable version is 1.5.0, with its latest release in 2020. This package maintains a very stable, albeit infrequent, release cadence, often updating to align with new major versions of its core dependency, `http-errors`. Its primary differentiator is the seamless integration of HTTP error status codes into standard assertion patterns, making it particularly well-suited for web frameworks like Koa, where it offers functionality akin to `ctx.throw()` but with a conditional, guard-like behavior.

http-networkingtestingweb-framework
github ↗package ↗
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.

The package primarily uses CommonJS `module.exports` as a function. In ESM, it's typically imported as a default export, not a named export. Direct named import `import { assert }` will likely result in a `TypeError`.

import assert from 'http-assert';

While CommonJS `require` is the original usage, modern Node.js environments often use ESM. This example shows ESM usage of a nested assertion method.

import assert from 'http-assert'; assert.strictEqual(a, b, 400, 'Bad Request');

`HttpError` is thrown by `http-assert` but is not directly exported *from* `http-assert`. It originates from the underlying `http-errors` package. To import `HttpError` directly for `instanceof` checks, import it from `http-errors`.

import createError from 'http-errors'; // Or if using http-assert: try { assert(false, 400, 'Invalid'); } catch (err) { /* err is an instance of HttpError */ }

This example demonstrates how to use `http-assert` for various checks in a request processing function, catching and handling the `HttpError` instances it throws, and distinguishing them from other errors.

import assert from 'http-assert'; import createError from 'http-errors'; const user = { id: 123, role: 'admin' }; const requestedUserId = '123'; const requiredRole = 'admin'; function processRequest(data) { try { // Assert that 'data' exists assert(data, 400, 'Request body is required'); // Assert strict equality for user IDs assert.strictEqual(user.id.toString(), requestedUserId, 403, 'User ID mismatch'); // Assert user role assert(user.role === requiredRole, 401, 'Unauthorized: Insufficient permissions'); // If all assertions pass, continue processing console.log('Request processed successfully!'); return { status: 200, message: 'Success' }; } catch (err) { if (createError.isHttpError(err)) { console.error(`HTTP Error ${err.status}: ${err.message}`); return { status: err.status, message: err.message, expose: err.expose }; } else { console.error(`Unexpected error: ${err.message}`); return { status: 500, message: 'Internal Server Error' }; } } } // Example usage: processRequest({ someData: 'value' }); processRequest(null); processRequest({ invalidUser: true }); // Will fail strictEqual if 'user.id' doesn't match
Debug
Known footguns
gotchaThe `assert.equal` and `assert.deepEqual` methods use the Abstract Equality Comparison (`==`), which performs type coercion. This can lead to unexpected results for developers accustomed to strict equality (`===`) in JavaScript. For strict checks, always use `assert.strictEqual` or `assert.notStrictEqual`.
deprecatedThe underlying `http-errors` package, which `http-assert` depends on, deprecated the use of non-error status codes (e.g., 2xx, 3xx) in version `1.6.1`. While `http-assert` may still accept them, using a status code outside the 4xx or 5xx range for assertions is strongly discouraged and may lead to unexpected behavior or future breakage.
gotchaWhen migrating from CommonJS (`require`) to ES Modules (`import`), attempting to use `import { assert } from 'http-assert';` will result in a `TypeError` because `http-assert` exports a default function/object, not named exports. This is a common pattern for older CommonJS modules.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
13 hits · last 30 days
gptbot
4
ahrefsbot
4
amazonbot
4
script
1
Resources
githubhttps://github.com/jshttp/http-assert ↗
packagehttps://www.npmjs.com/package/http-assert ↗