Registry / http-networking / http-assert

http-assert

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-networking testing web-framework

npm install http-assert

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-ASSERT

http-assert

http-networkingjavascriptv1.5.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.

assert

✓ import assert from 'http-assert';

✗ import { assert } from 'http-assert';

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`.

assert.strictEqual

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

✗ const assert = require('http-assert'); assert.strictEqual(a, b, 400, 'Bad Request');

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

HttpError

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

✗ import { HttpError } from 'http-assert';

`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`.

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 issues

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`.

fix

Use `assert.strictEqual(a, b, status, message)` for strict equality comparisons to avoid type coercion issues. For objects, consider if `deepStrictEqual` from Node's native assert or another utility is more appropriate if `http-assert`'s deepEqual (which uses `==`) is too loose.

affects: >=1.0.0

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.

fix

Ensure that the `status` argument passed to `http-assert` functions is always a valid HTTP error status code (4xx or 5xx). For successful conditions, do not use `http-assert`; instead, proceed with normal execution flow.

affects: >=1.3.0

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.

fix

For ES Modules, use `import assert from 'http-assert';` to import the module's default export. The assertion methods (e.g., `strictEqual`) are then available as properties of the `assert` object (e.g., `assert.strictEqual`).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: assert is not a function

Attempting to use `import { assert } from 'http-assert'` in an ES module environment, where `http-assert` provides a default export.

fix

Change the import statement to `import assert from 'http-assert';` to correctly import the default export.

Error: 'status' must be a number

The `status` argument passed to an `http-assert` function was not a valid number, or was missing when a status code was expected.

fix

Ensure the status argument is a numeric HTTP status code, typically between 400 and 599. Example: `assert(condition, 400, 'Bad Request');`

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

http-errorsrequiredCore dependency for generating HTTP-specific error objects.

deep-equalrequiredUsed internally for deep equality comparisons in `assert.deepEqual` and `assert.notDeepEqual`.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jshttp/http-assert ↗

packagehttps://www.npmjs.com/package/http-assert ↗