@argument-assertions/node-assert-plus

v2026.1.14

Published

4 months ago

Node.js assertion library on top of the built-in assert module with strict and flexible validation. Much more secure and up to 10 times faster than the original 'node-assert-plus', 80 % less CPU usage and memory consumption.

Downloads

Zu Deutsch wechseln

`@argument-assertions/node-assert-plus`

NPM version

What is `node-assert-plus`?

@argument-assertions/node-assert-plus is a modern and secure assertion library written in TypeScript by Roland Milto, designed as an enhanced implementation of Node’s built-in node:assert/strict.

It is a fork of the original assert-plus library, which is no longer maintained and has several security and performance issues. This new library from 2026 is up to ten times faster than the original assert-plus, while reducing CPU and memory usage by 50–80%.

Type guarding and strict primitive checks have been added, and problematic features such as caller have been removed to ensure compatibility with Strict Mode.

More details:

@argument-assertions/node-assert-plus simplifies testing by offering a broad set of ready-to-use assertions. As a simple example:

import { assert } from '@argument-assertions/node-assert-plus';

process.env.NODE_ENV = 'development';

function checkAccountDetails(options, callback)
{
  assert.plainObject(options, 'options');
  assert.integer(options.id, 'options.id');
  assert.string(options.name, 'options.name');
  assert.arrayOfString(options.email, 'options.email');
  assert.object(options.dateObject, 'options.dateObject');
  assert.boolean(options.isManager, 'options.isManager');
  assert.number(options.process, 'options.process');
  assert.function(callback, 'callback');

  // Do whatever you want with the account details!
  callback(null, {});
}

What is also new?

Thirty-six new assertions

| Type check | Optional checks | Check items in an isArray | Check items in an isArray (optional) | |-------------------------|--------------------------------|-------------------------------|---------------------------------------| | assert.bigInt | assert.optionalBigInt | assert.arrayOfBigInt | assert.optionalArrayOfBigInt | | assert.integer | assert.optionalInteger | assert.arrayOfInteger | assert.optionalArrayOfInteger | | assert.null | assert.optionalNull | assert.arrayOfNull | assert.optionalArrayOfNull | | assert.nullOrUndefined | assert.optionalNullOrUndefined | assert.arrayOfNullOrUndefined | assert.optionalArrayOfNullOrUndefined | | assert.plainObject | assert.optionalPlainObject | assert.arrayOfPlainObject | assert.optionalArrayOfPlainObject | | assert.promise | assert.optionalPromise | assert.arrayOfPromise | assert.optionalArrayOfPromise | | assert.symbol | assert.optionalSymbol | assert.arrayOfSymbol | assert.optionalArrayOfSymbol | | assert.undefined | assert.optionalUndefined | assert.arrayOfUndefined | assert.optionalArrayOfUndefined | | assert.ValidDate | assert.optionalValidDate | assert.arrayOfValidDate | assert.optionalArrayOfValidDate |

Aliases for `bool`, `func` and `regexp`

The following aliases have been added to the existing assertions and can be used instead of the initial names.

Forced (value must exist)

| New method alias | Original | - | New array-method alias | Original | |-------------------|-----------------|---|--------------------------|-------------------------| | assert.boolean | assert.bool | - | assert.arrayOfBoolean | assert.arrayOfBool | | assert.function | assert.func | - | assert.arrayOfFunction | assert.arrayOfFunc | | assert.regEx | assert.regexp | - | assert.arrayOfRegEx | assert.arrayOfRegexp |

Optional (value can be `undefined` or `null`)

| New method alias | Original | - | New array-method alias | Original | |---------------------------|-------------------------|---|----------------------------------|--------------------------------| | assert.optionalBoolean | assert.optionalBool | - | assert.optionalArrayOfBoolean | assert.optionalArrayOfBool | | assert.optionalFunction | assert.optionalFunc | - | assert.optionalArrayOfFunction | assert.optionalArrayOfFunc | | assert.optionalRegEx | assert.optionalRegexp | - | assert.optionalArrayOfRegEx | assert.optionalArrayOfRegexp |

Legacy Projects

For legacy codebases that still rely on assert-plus,
@argument-assertions/node-assert-plus can be used as a compatible drop-in replacement.

For new projects that require a stable assertion library with an extended feature set,
consider using @type-check/assertions.

It offers a modern and secure design, a broader range of functionality, a minimal bundle size, is straightforward to use and is well-documented.

The outdated process.env.NODE_NDEBUG has been replaced by the modern process.env.NODE_ENV. This must be adjusted accordingly in your code.

How to use `@argument-assertions/node-assert-plus`?

Installation via command line

npm install @argument-assertions/node-assert-plus

package.json

Ensure that @argument-assertions/node-assert-plus is included in your package.json dependencies and always use the latest version:

{
	"dependencies": {
		"@argument-assertions/node-assert-plus": "*"
	}
}

tsconfig.json

Since @argument-assertions/node-assert-plus is exported as an ESM module, it is necessary to adjust the moduleResolution option in the tsconfig.json file to avoid error messages from the TypeScript compiler:

{
	"compilerOptions": {
		"moduleResolution": "NodeNext"
	}
}

Import

Use @argument-assertions/node-assert-plus as local import:

import { assert } from '@argument-assertions/node-assert-plus';

Use @argument-assertions/node-assert-plus as global import, so you need to include it only once in your project:

import '@argument-assertions/node-assert-plus/register-global';

Usage

All methods that are not part of Node’s core assert API are assumed to take the value to validate followed by a string label, e.g. assert.FUNCTIONNAME(value, label). This label is not interpreted as a message.

process.env["NODE_ENV"] = 'development';          // Can be *any* string to enable strict mode

assert.integer(42, "my integer success label");   // Success
assert.string("foo", "my string success label");  // Success

assert.integer(42.4, "my integer failure label"); // Failure, maybe you should use assert.number instead? ;)
assert.string(54545, "my string failure label");  // Failure

let strings = ['Roland', 'Milto', 'from', 'Germany'];
assert.arrayOfString(strings, 'good strings');    // Success

strings.push(42);
assert.arrayOfString(strings, 'bad strings');     // Failure

process.env["NODE_ENV"] = 'production'            // Set to 'production' to disable strict mode

assert.plainObject(new Date(), "date");           // Will be ignored in production mode

The best way is to control the development mode via the environment variables of the code editor (e.g., WebStorm, Visual Studio Code, etc.).

It is enough not to set process.env.NODE_ENV in order for production mode to be recognized. Assertions can be disabled any time with process.env.["NODE_ENV"] = "production". Any value in process.env.NODE_ENV activates the mode.

What does it look like if a condition fails?

let meaningOfLife = 42.4;
assert.integer(meaningOfLife, "meaningOfLife label");

Will fail, because 42.4 is not an integer. The output will be an AssertionError with the following message:

AssertionError [ERR_ASSERTION]: At "meaningOfLife label" type of "integer" is required.
at new AssertionError (node:internal/assert/assertion_error:369:5)
at toss (file:///C:/@argument-assertions/node-assert-plus/dist/utils/toss.js:19:11)
at Object.integer (file:///C:/@argument-assertions/node-assert-plus/dist/caller/typeCheck.js:88:13)
at file:///C:/@argument-assertions/node-assert-plus/tests/test.mjs:11:8
at ModuleJob.run (node:internal/modules/esm/module_job:271:25)
at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:547:26)
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5) {
  generatedMessage: false,
  code: 'ERR_ASSERTION',
  actual: 'number',
  expected: 'integer',
  operator: '==='
}

Methods

Required Assertions

| Single Value Check |----------------------------------------| | assert.array(value, label) | assert.bigint(value, label) | assert.boolean(value, label) | assert.bool(value, label) | assert.buffer(value, label) | assert.date(value, label) | assert.finite(value, label) | assert.function(value, label) | assert.func(value, label) | assert.integer(value, label) | assert.null(value, label) | assert.nullOrUndefined(value, | assert.number(value, label) | assert.object(value, label) | assert.plainObject(value, label) | assert.promise(value, label) | assert.regexp(value, label) | assert.regEx(value, label) | assert.stream(value, label) | assert.string(value, label) | assert.symbol(value, label) | assert.undefined(value, label) | assert.uuid(value, label) | assert.validDate(value, label) | Array Check | Short Description | -----------------------------------------------|----------------------------------------------| | assert.arrayOfArray(array, label) | Checks if value(s) is an array. | | assert.arrayOfBigInt(array, label) | Checks if value(s) is a bigint. | | assert.arrayOfBoolean(array, label) | Checks if value(s) is a boolean. | | assert.arrayOfBool(array, label) | Alias for boolean check. | | assert.arrayOfBuffer(array, label) | Checks if value(s) is a buffer. | | assert.arrayOfDate(array, label) | Checks if value(s) is a date object. | | assert.arrayOfFinite(array, label) | Checks if value(s) is a finite number. | | assert.arrayOfFunction(array, label) | Checks if value(s) is a function. | | assert.arrayOfFunc(array, label) | Alias for function check. | | assert.arrayOfInteger(array, label) | Checks if value(s) is an integer. | | assert.arrayOfNull(array, label) | Checks if value(s) is exactly null. | label) | assert.arrayOfNullOrUndefined(array, label) | Checks if value(s) is null or undefined. | | assert.arrayOfNumber(array, label) | Checks if value(s) is a number. | | assert.arrayOfObject(array, label) | Checks if value(s) is an object. | | assert.arrayOfPlainObject(array, label) | Checks if value(s) is a plain object ({}). | | assert.arrayOfPromise(array, label) | Checks if value(s) is a promise. | | assert.arrayOfRegexp(array, label) | Checks if value(s) is a regular expression. | | assert.arrayOfRegEx(array, label) | Alias for regexp check. | | assert.arrayOfStream(array, label) | Checks if value(s) is a stream. | | assert.arrayOfString(array, label) | Checks if value(s) is a string. | | assert.arrayOfSymbol(array, label) | Checks if value(s) is a symbol. | | assert.arrayOfUndefined(array, label) | Checks if value(s) is exactly undefined. | | assert.arrayOfUuid(array, label) | Checks if value(s) is a valid UUID. | | assert.arrayOfValidDate(array, label) | Checks if value(s) is a valid date object. |

Optional Assertions

| Single Value Check (optional) | Array Check (optional) | Short Description | |------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------| | assert.optionalArray(value, label) | assert.optionalArrayOfArray(array, label) | Optionally checks if value(s) is an array. | | assert.optionalBigInt(value, label) | assert.optionalArrayOfBigInt(array, label) | Optionally checks if value(s) is a bigint. | | assert.optionalBoolean(value, label) | assert.optionalArrayOfBoolean(array, label) | Optionally checks if value(s) is a boolean. | | assert.optionalBool(value, label) | assert.optionalArrayOfBool(array, label) | Alias for optional boolean check. | | assert.optionalBuffer(value, label) | assert.optionalArrayOfBuffer(array, label) | Optionally checks if value(s) is a buffer. | | assert.optionalDate(value, label) | assert.optionalArrayOfDate(array, label) | Optionally checks if value(s) is a date object. | | assert.optionalFinite(value, label) | assert.optionalArrayOfFinite(array, label) | Optionally checks if value(s) is a finite number. | | assert.optionalFunction(value, label) | assert.optionalArrayOfFunction(array, label) | Optionally checks if value(s) is a function. | | assert.optionalFunc(value, label) | assert.optionalArrayOfFunc(array, label) | Alias for optional function check. | | assert.optionalInteger(value, label) | assert.optionalArrayOfInteger(array, label) | Optionally checks if value(s) is an integer. | | assert.optionalNull(value, label) | assert.optionalArrayOfNull(array, label) | Optionally checks if value(s) is exactly null. | | assert.optionalNullOrUndefined(value, label) | assert.optionalArrayOfNullOrUndefined(array, label) | Optionally checks if value(s) is null or undefined. | | assert.optionalNumber(value, label) | assert.optionalArrayOfNumber(array, label) | Optionally checks if value(s) is a number. | | assert.optionalObject(value, label) | assert.optionalArrayOfObject(array, label) | Optionally checks if value(s) is an object. | | assert.optionalPlainObject(value, label) | assert.optionalArrayOfPlainObject(array, label) | Optionally checks if value(s) is a plain object. | | assert.optionalPromise(value, label) | assert.optionalArrayOfPromise(array, label) | Optionally checks if value(s) is a promise. | | assert.optionalRegexp(value, label) | assert.optionalArrayOfRegexp(array, label) | Optionally checks if value(s) is a regular expression. | | assert.optionalRegEx(value, label) | assert.optionalArrayOfRegEx(array, label) | Alias for optional regexp check. | | assert.optionalStream(value, label) | assert.optionalArrayOfStream(array, label) | Optionally checks if value(s) is a stream. | | assert.optionalString(value, label) | assert.optionalArrayOfString(array, label) | Optionally checks if value(s) is a string. | | assert.optionalSymbol(value, label) | assert.optionalArrayOfSymbol(array, label) | Optionally checks if value(s) is a symbol. | | assert.optionalUndefined(value, label) | assert.optionalArrayOfUndefined(array, label) | Optionally checks if value(s) is exactly undefined. | | assert.optionalUuid(value, label) | assert.optionalArrayOfUuid(array, label) | Optionally checks if value(s) is a valid UUID. | | assert.optionalValidDate(value, label) | assert.optionalArrayOfValidDate(array, label) | Optionally checks if value(s) is a valid date object. |

Strict Node.js assertions

In addition to these checks, all methods provided by node:assert/strict are available, e.g.:

Contributing

If you would also like to contribute to the library, you are welcome to do so. You can find information about this in CONTRIBUTING.md. You will be also mentioned in the AUTHORS.md.