or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

assert-plus

assert-plus is a Node.js library that provides extended assertion capabilities on top of Node.js's built-in assert module. It offers 77 assertion functions including type checking, optional parameter validation, array homogeneity validation, and all standard Node.js assertions with the ability to disable all assertions in production environments.

Package Information

  • Package Name: assert-plus
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install assert-plus

Core Imports

const assert = require('assert-plus');

For ES modules:

import assert from 'assert-plus';

Basic Usage

const assert = require('assert-plus');

function createUser(options, callback) {
    // Basic type assertions
    assert.object(options, 'options');
    assert.string(options.name, 'options.name');
    assert.number(options.age, 'options.age');
    assert.func(callback, 'callback');
    
    // Optional parameter validation
    assert.optionalString(options.email, 'options.email');
    
    // Array type validation
    assert.arrayOfString(options.tags, 'options.tags');
    
    // Your application logic here
    callback(null, { id: 1, ...options });
}

// Usage
createUser({
    name: 'Alice',
    age: 30,
    email: 'alice@example.com',
    tags: ['developer', 'javascript']
}, (err, user) => {
    console.log(user);
});

Architecture

assert-plus uses a dynamic function generation system built around:

  • Type System: Internal type definitions for 12 core types (bool, func, string, number, object, finite, buffer, array, stream, date, regexp, uuid)
  • Pattern Generation: Automatically generates 4 assertion patterns for each type (basic, optional, arrayOf, optionalArrayOf)
  • Environment Control: NODE_NDEBUG environment variable disables all assertions for production performance
  • Error Reporting: Descriptive error messages with parameter names for debugging

Capabilities

Main Assertion Function

Primary assertion function that validates truthiness.

/**
 * Main assertion function - validates truthiness
 * @param {any} arg - Value to test for truthiness
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is falsy
 */
assert(arg, msg);

Core Type Assertions

Basic type validation functions for JavaScript primitives and built-in objects.

/**
 * Validates boolean type
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a boolean
 */
assert.bool(arg, msg);

/**
 * Validates function type
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a function
 */
assert.func(arg, msg);

/**
 * Validates string type
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a string
 */
assert.string(arg, msg);

/**
 * Validates number type (excludes NaN)
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a number or is NaN
 */
assert.number(arg, msg);

/**
 * Validates object type (excludes null)
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an object or is null
 */
assert.object(arg, msg);

Extended Type Assertions

Advanced type validation for specialized JavaScript objects and values.

/**
 * Validates finite number (excludes NaN and Infinity)
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a finite number
 */
assert.finite(arg, msg);

/**
 * Validates Buffer instance
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a Buffer
 */
assert.buffer(arg, msg);

/**
 * Validates array type
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array
 */
assert.array(arg, msg);

/**
 * Validates Stream instance
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a Stream
 */
assert.stream(arg, msg);

/**
 * Validates Date instance
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a Date
 */
assert.date(arg, msg);

/**
 * Validates RegExp instance
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a RegExp
 */
assert.regexp(arg, msg);

/**
 * Validates UUID string format
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not a valid UUID string
 */
assert.uuid(arg, msg);

Optional Type Assertions

Validation functions that allow undefined or null values but validate type when present.

/**
 * Optional boolean validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a boolean
 */
assert.optionalBool(arg, msg);

/**
 * Optional function validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a function
 */
assert.optionalFunc(arg, msg);

/**
 * Optional string validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a string
 */
assert.optionalString(arg, msg);

/**
 * Optional number validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a number
 */
assert.optionalNumber(arg, msg);

/**
 * Optional object validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not an object
 */
assert.optionalObject(arg, msg);

/**
 * Optional finite number validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a finite number
 */
assert.optionalFinite(arg, msg);

/**
 * Optional Buffer validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a Buffer
 */
assert.optionalBuffer(arg, msg);

/**
 * Optional array validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not an array
 */
assert.optionalArray(arg, msg);

/**
 * Optional Stream validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a Stream
 */
assert.optionalStream(arg, msg);

/**
 * Optional Date validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a Date
 */
assert.optionalDate(arg, msg);

/**
 * Optional RegExp validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a RegExp
 */
assert.optionalRegexp(arg, msg);

/**
 * Optional UUID validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid UUID
 */
assert.optionalUuid(arg, msg);

Array Type Assertions

Validation functions for arrays containing homogeneous types.

/**
 * Validates array of booleans
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-boolean elements
 */
assert.arrayOfBool(arg, msg);

/**
 * Validates array of functions
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-function elements
 */
assert.arrayOfFunc(arg, msg);

/**
 * Validates array of strings
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-string elements
 */
assert.arrayOfString(arg, msg);

/**
 * Validates array of numbers
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-number elements
 */
assert.arrayOfNumber(arg, msg);

/**
 * Validates array of objects
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-object elements
 */
assert.arrayOfObject(arg, msg);

/**
 * Validates array of finite numbers
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-finite elements
 */
assert.arrayOfFinite(arg, msg);

/**
 * Validates array of Buffers
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-Buffer elements
 */
assert.arrayOfBuffer(arg, msg);

/**
 * Validates array of arrays
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-array elements
 */
assert.arrayOfArray(arg, msg);

/**
 * Validates array of Streams
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-Stream elements
 */
assert.arrayOfStream(arg, msg);

/**
 * Validates array of Dates
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-Date elements
 */
assert.arrayOfDate(arg, msg);

/**
 * Validates array of RegExps
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains non-RegExp elements
 */
assert.arrayOfRegexp(arg, msg);

/**
 * Validates array of UUIDs
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is not an array or contains invalid UUID strings
 */
assert.arrayOfUuid(arg, msg);

Optional Array Type Assertions

Validation functions for optional arrays containing homogeneous types.

/**
 * Optional array of booleans validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of booleans
 */
assert.optionalArrayOfBool(arg, msg);

/**
 * Optional array of functions validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of functions
 */
assert.optionalArrayOfFunc(arg, msg);

/**
 * Optional array of strings validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of strings
 */
assert.optionalArrayOfString(arg, msg);

/**
 * Optional array of numbers validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of numbers
 */
assert.optionalArrayOfNumber(arg, msg);

/**
 * Optional array of objects validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of objects
 */
assert.optionalArrayOfObject(arg, msg);

/**
 * Optional array of finite numbers validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of finite numbers
 */
assert.optionalArrayOfFinite(arg, msg);

/**
 * Optional array of Buffers validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of Buffers
 */
assert.optionalArrayOfBuffer(arg, msg);

/**
 * Optional array of arrays validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of arrays
 */
assert.optionalArrayOfArray(arg, msg);

/**
 * Optional array of Streams validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of Streams
 */
assert.optionalArrayOfStream(arg, msg);

/**
 * Optional array of Dates validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of Dates
 */
assert.optionalArrayOfDate(arg, msg);

/**
 * Optional array of RegExps validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of RegExps
 */
assert.optionalArrayOfRegexp(arg, msg);

/**
 * Optional array of UUIDs validation - allows undefined/null
 * @param {any} arg - Value to validate
 * @param {string} msg - Parameter name for error messages
 * @throws {AssertionError} When arg is defined but not a valid array of UUIDs
 */
assert.optionalArrayOfUuid(arg, msg);

Node.js Assert Re-exports

All standard Node.js assert module functions are re-exported and subject to the same NODE_NDEBUG behavior.

/**
 * AssertionError constructor from Node.js assert module
 */
class assert.AssertionError extends Error {
    constructor(options: {
        message?: string;
        actual?: any;
        expected?: any;
        operator?: string;
        stackStartFn?: Function;
    });
    actual: any;
    expected: any;
    operator: string;
    generatedMessage: boolean;
}

/**
 * Node.js assert.fail function
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 * @param {string} operator - Comparison operator
 * @param {Function} stackStartFn - Function to omit from stack trace
 */
assert.fail(actual, expected, message, operator, stackStartFn);

/**
 * Node.js assert.ok function - tests for truthiness
 * @param {any} value - Value to test
 * @param {string} message - Error message
 */
assert.ok(value, message);

/**
 * Node.js assert.equal function - shallow equality (==)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.equal(actual, expected, message);

/**
 * Node.js assert.notEqual function - shallow inequality (!=)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.notEqual(actual, expected, message);

/**
 * Node.js assert.deepEqual function - deep equality
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.deepEqual(actual, expected, message);

/**
 * Node.js assert.notDeepEqual function - deep inequality
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.notDeepEqual(actual, expected, message);

/**
 * Node.js assert.strictEqual function - strict equality (===)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.strictEqual(actual, expected, message);

/**
 * Node.js assert.notStrictEqual function - strict inequality (!==)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.notStrictEqual(actual, expected, message);

/**
 * Node.js assert.throws function - expects function to throw
 * @param {Function} fn - Function expected to throw
 * @param {Function|RegExp|string} expected - Expected error type/pattern
 * @param {string} message - Error message
 */
assert.throws(fn, expected, message);

/**
 * Node.js assert.doesNotThrow function - expects function not to throw
 * @param {Function} fn - Function expected not to throw
 * @param {Function|RegExp|string} expected - Error type/pattern to check against
 * @param {string} message - Error message
 */
assert.doesNotThrow(fn, expected, message);

/**
 * Node.js assert.ifError function - throws if value is truthy
 * @param {any} value - Value to test
 */
assert.ifError(value);

/**
 * Node.js assert.deepStrictEqual function - deep strict equality
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.deepStrictEqual(actual, expected, message);

/**
 * Node.js assert.notDeepStrictEqual function - deep strict inequality
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Error message
 */
assert.notDeepStrictEqual(actual, expected, message);

/**
 * Node.js assert.match function - tests string against regexp
 * @param {string} string - String to test
 * @param {RegExp} regexp - Regular expression to match
 * @param {string} message - Error message
 */
assert.match(string, regexp, message);

/**
 * Node.js assert.doesNotMatch function - tests string does not match regexp
 * @param {string} string - String to test
 * @param {RegExp} regexp - Regular expression that should not match
 * @param {string} message - Error message
 */
assert.doesNotMatch(string, regexp, message);

/**
 * Node.js assert.rejects function - expects promise to reject
 * @param {Promise} asyncFn - Promise or async function expected to reject
 * @param {Function|RegExp|string} expected - Expected error type/pattern
 * @param {string} message - Error message
 */
assert.rejects(asyncFn, expected, message);

/**
 * Node.js assert.doesNotReject function - expects promise not to reject
 * @param {Promise} asyncFn - Promise or async function expected not to reject
 * @param {Function|RegExp|string} expected - Error type/pattern to check against
 * @param {string} message - Error message
 */
assert.doesNotReject(asyncFn, expected, message);

Internal Functions

/**
 * Internal function for testing - sets export behavior based on debug mode
 * @param {boolean} ndebug - Whether to enable debug mode
 * @returns {Object} Module exports
 */
assert._setExports(ndebug);

Environment Configuration

Production Performance Mode

Set the NODE_NDEBUG environment variable to disable all assertions for production performance:

NODE_NDEBUG=1 node app.js

When NODE_NDEBUG is set:

  • All assert-plus functions become no-op functions
  • All re-exported Node.js assert functions are also disabled
  • Only AssertionError constructor remains functional

Error Handling

All assertion failures throw assert.AssertionError with the message format:

AssertionError: [parameter_name] ([expected_type]) is required

Example error messages:

  • AssertionError: options (object) is required
  • AssertionError: callback (function) is required
  • AssertionError: tags ([string]) is required

The errors include:

  • message: Descriptive error message with parameter name
  • actual: The actual type/value received
  • expected: The expected type
  • operator: The comparison operator used
  • stack: Stack trace starting from the calling function

Usage Examples

Function Parameter Validation

const assert = require('assert-plus');

function processUser(user, options, callback) {
    // Required parameters
    assert.object(user, 'user');
    assert.string(user.name, 'user.name');
    assert.number(user.age, 'user.age');
    
    // Optional parameters
    assert.optionalObject(options, 'options');
    assert.optionalString(options && options.format, 'options.format');
    
    // Callback validation
    assert.func(callback, 'callback');
    
    // Array validation
    if (user.roles) {
        assert.arrayOfString(user.roles, 'user.roles');
    }
    
    // Process user...
    callback(null, { processed: true });
}

API Input Validation

const assert = require('assert-plus');

function createProject(projectData) {
    // Validate main object
    assert.object(projectData, 'projectData');
    
    // Validate required fields
    assert.string(projectData.name, 'projectData.name');
    assert.string(projectData.description, 'projectData.description');
    assert.date(projectData.startDate, 'projectData.startDate');
    
    // Validate optional fields
    assert.optionalDate(projectData.endDate, 'projectData.endDate');
    assert.optionalArrayOfString(projectData.tags, 'projectData.tags');
    
    // Validate team members
    if (projectData.team) {
        assert.arrayOfObject(projectData.team, 'projectData.team');
        projectData.team.forEach((member, index) => {
            assert.string(member.name, `projectData.team[${index}].name`);
            assert.string(member.role, `projectData.team[${index}].role`);
        });
    }
    
    return { id: Date.now(), ...projectData };
}

UUID and Special Type Validation

const assert = require('assert-plus');

function connectToDatabase(config) {
    assert.object(config, 'config');
    assert.string(config.host, 'config.host');
    assert.number(config.port, 'config.port');
    
    // UUID validation for connection ID
    assert.uuid(config.connectionId, 'config.connectionId');
    
    // RegExp validation for table name pattern
    assert.optionalRegexp(config.tablePattern, 'config.tablePattern');
    
    // Buffer validation for encryption key
    assert.optionalBuffer(config.encryptionKey, 'config.encryptionKey');
    
    // Connect to database...
    return { connected: true };
}