stdlib-js / assert

Standard assertion utilities.

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

Assert

Assertion utilities.

Installation

npm install @stdlib/assert

Alternatively,

• To load the package in a website via a script tag without installation and bundlers, use the ES Module available on the esm branch (see README).
• If you are using Deno, visit the deno branch (see README for usage intructions).
• For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the umd branch (see README).

The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.

To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.

Usage

var assert = require( '@stdlib/assert' );

assert

Namespace providing utilities for data type testing and feature detection.

var o = assert;
// returns {...}

To validate the built-in JavaScript data types, the namespace includes the following assertion utilities:

• isArray( value ): test if a value is an array.
• isBoolean( value ): test if a value is a boolean.
• isDateObject( value ): test if a value is a Date object.
• isFunction( value ): test if a value is a function.
• isnan( value ): test if a value is NaN.
• isNull( value ): test if a value is null.
• isNumber( value ): test if a value is a number.
• isObject( value ): test if a value is an object.
• isRegExp( value ): test if a value is a regular expression.
• isString( value ): test if a value is a string.
• isSymbol( value ): test if a value is a symbol.
• isUndefined( value ): test if a value is undefined.

For primitive types having corresponding object wrappers, assertion utilities provide isObject and isPrimitive methods to test for either objects or primitives, respectively.

var Boolean = require( '@stdlib/boolean/ctor' );
var isBoolean = require( '@stdlib/assert/is-boolean' );

var bool = isBoolean.isObject( new Boolean( false ) );
// returns true

bool = isBoolean.isObject( false );
// returns false

bool = isBoolean.isPrimitive( false );
// returns true

Many of the assertion utilities have corresponding packages that test whether array elements are of the given data type:

• isArrayArray( value ): test if a value is an array of arrays.
• isBooleanArray( value ): test if a value is an array-like object of booleans.
• isDateObjectArray( value ): test if a value is an array-like object containing only Date objects.
• isFunctionArray( value ): test if a value is an array-like object containing only functions.
• isNaNArray( value ): test if a value is an array-like object containing only NaN values.
• isNullArray( value ): test if a value is an array-like object containing only null values.
• isNumberArray( value ): test if a value is an array-like object of numbers.
• isObjectArray( value ): test if a value is an array-like object containing only objects.
• isStringArray( value ): test if a value is an array of strings.
• isSymbolArray( value ): test if a value is an array-like object containing only symbols.

Where applicable, similar to the assertion utilities for built-in data types, array assertion utilities provides methods for testing for an array of primitives or objects.

var isStringArray = require( '@stdlib/assert/is-string-array' );

var bool = isStringArray( [ 'hello', 'world' ] );
// returns true

bool = isStringArray.primitives( [ 'hello', 'world' ] );
// returns true

bool = isStringArray.objects( [ 'hello', 'world' ] );
// returns false

bool = isStringArray.objects( [ new String( 'hello' ), new String( 'world' ) ] );
// returns true

The namespace also contains utilities to test for numbers within a certain range or for numbers satisfying a particular "type":

• isCubeNumber( value ): test if a value is a cube number.
• isIntegerArray( value ): test if a value is an array-like object containing only integers.
• isInteger( value ): test if a value is a number having an integer value.
• isNegativeIntegerArray( value ): test if a value is an array-like object containing only negative integers.
• isNegativeInteger( value ): test if a value is a number having a negative integer value.
• isNegativeNumberArray( value ): test if a value is an array-like object containing only negative numbers.
• isNegativeNumber( value ): test if a value is a number having a negative value.
• isNonNegativeIntegerArray( value ): test if a value is an array-like object containing only nonnegative integers.
• isNonNegativeInteger( value ): test if a value is a number having a nonnegative integer value.
• isNonNegativeNumberArray( value ): test if a value is an array-like object containing only nonnegative numbers.
• isNonNegativeNumber( value ): test if a value is a number having a nonnegative value.
• isNonPositiveIntegerArray( value ): test if a value is an array-like object containing only nonpositive integers.
• isNonPositiveInteger( value ): test if a value is a number having a nonpositive integer value.
• isNonPositiveNumberArray( value ): test if a value is an array-like object containing only nonpositive numbers.
• isNonPositiveNumber( value ): test if a value is a number having a nonpositive value.
• isPositiveIntegerArray( value ): test if a value is an array-like object containing only positive integers.
• isPositiveInteger( value ): test if a value is a number having a positive integer value.
• isPositiveNumberArray( value ): test if a value is an array-like object containing only positive numbers.
• isPositiveNumber( value ): test if a value is a number having a positive value.
• isSafeIntegerArray( value ): test if a value is an array-like object containing only safe integers.
• isSafeInteger( value ): test if a value is a number having a safe integer value.
• isSquareNumber( value ): test if a value is a square number.
• isSquareTriangularNumber( value ): test if a value is a square triangular number.
• isTriangularNumber( value ): test if a value is a triangular number.

The namespace provides utilities for validating typed arrays:

• isFloat32Array( value ): test if a value is a Float32Array.
• isFloat64Array( value ): test if a value is a Float64Array.
• isInt16Array( value ): test if a value is an Int16Array.
• isInt32Array( value ): test if a value is an Int32Array.
• isInt8Array( value ): test if a value is an Int8Array.
• isUint16Array( value ): test if a value is a Uint16Array.
• isUint32Array( value ): test if a value is a Uint32Array.
• isUint8Array( value ): test if a value is a Uint8Array.
• isUint8ClampedArray( value ): test if a value is a Uint8ClampedArray.

The namespace includes utilities for validating ndarrays (n-dimensional arrays).

• isCentrosymmetricMatrix( value ): test if a value is a centrosymmetric matrix.
• isComplex128MatrixLike( value ): test if a value is a 2-dimensional ndarray-like object containing double-precision complex floating-point numbers.
• isComplex128ndarrayLike( value ): test if a value is an ndarray-like object containing double-precision complex floating-point numbers.
• isComplex128VectorLike( value ): test if a value is a 1-dimensional ndarray-like object containing double-precision complex floating-point numbers.
• isComplex64MatrixLike( value ): test if a value is a 2-dimensional ndarray-like object containing single-precision complex floating-point numbers.
• isComplex64ndarrayLike( value ): test if a value is an ndarray-like object containing single-precision complex floating-point numbers.
• isComplex64VectorLike( value ): test if a value is a 1-dimensional ndarray-like object containing single-precision complex floating-point numbers.
• isFloat32MatrixLike( value ): test if a value is a 2-dimensional ndarray-like object containing single-precision floating-point numbers.
• isFloat32ndarrayLike( value ): test if a value is an ndarray-like object containing single-precision floating-point numbers.
• isFloat32VectorLike( value ): test if a value is a 1-dimensional ndarray-like object containing single-precision floating-point numbers.
• isFloat64MatrixLike( value ): test if a value is a 2-dimensional ndarray-like object containing double-precision floating-point numbers.
• isFloat64ndarrayLike( value ): test if a value is an ndarray-like object containing double-precision floating-point numbers.
• isFloat64VectorLike( value ): test if a value is a 1-dimensional ndarray-like object containing double-precision floating-point numbers.
• isMatrixLike( value ): test if a value is 2-dimensional ndarray-like object.
• isndarrayLike( value ): test if a value is ndarray-like.
• isNonSymmetricMatrix( value ): test if a value is a non-symmetric matrix.
• isPersymmetricMatrix( value ): test if a value is a persymmetric matrix.
• isSkewCentrosymmetricMatrix( value ): test if a value is a skew-centrosymmetric matrix.
• isSkewPersymmetricMatrix( value ): test if a value is a skew-persymmetric matrix.
• isSkewSymmetricMatrix( value ): test if a value is a skew-symmetric matrix.
• isSquareMatrix( value ): test if a value is a 2-dimensional ndarray-like object having equal dimensions.
• isSymmetricMatrix( value ): test if a value is a symmetric matrix.
• isVectorLike( value ): test if a value is a 1-dimensional ndarray-like object.

The namespace includes utilities for validating complex numbers and arrays of complex numbers:

• isComplexLike( value ): test if a value is a complex number-like object.
• isComplexTypedArrayLike( value ): test if a value is complex-typed-array-like.
• isComplexTypedArray( value ): test if a value is a complex typed array.
• isComplex( value ): test if a value is a 64-bit or 128-bit complex number.
• isComplex128( value ): test if a value is a 128-bit complex number.
• isComplex128Array( value ): test if a value is a Complex128Array.
• isComplex64( value ): test if a value is a 64-bit complex number.
• isComplex64Array( value ): test if a value is a Complex64Array.

The namespace includes utilities for validating other special arrays or buffers:

• isAccessorArray( value ): test if a value is an array-like object supporting the accessor (get/set) protocol.
• isArrayLength( value ): test if a value is a valid array length.
• isArrayLikeObject( value ): test if a value is an array-like object.
• isArrayLike( value ): test if a value is array-like.
• isArrayBufferView( value ): test if a value is an ArrayBuffer view.
• isArrayBuffer( value ): test if a value is an ArrayBuffer.
• isBetweenArray( value, a, b[, left, right] ): test if a value is an array-like object where every element is between two values.
• isBigInt64Array( value ): test if a value is a BigInt64Array.
• isBigUint64Array( value ): test if a value is a BigUint64Array.
• isCircularArray( value ): test if a value is an array containing a circular reference.
• isEmptyArrayLikeObject( value ): test if a value is an empty array-like object.
• isEmptyArray( value ): test if a value is an empty array.
• isFalsyArray( value ): test if a value is an array-like object containing only falsy values.
• isFiniteArray( value ): test if a value is an array-like object containing only finite numbers.
• isNumericArray( value ): test if a value is a numeric array.
• isPlainObjectArray( value ): test if a value is an array-like object containing only plain objects.
• isProbabilityArray( value ): test if a value is an array-like object containing only probabilities.
• isSameArray( v1, v2 ): test if two arguments are both generic arrays and have the same values.
• isSameComplex128Array( v1, v2 ): test if two arguments are both Complex128Arrays and have the same values.
• isSameComplex64Array( v1, v2 ): test if two arguments are both Complex64Arrays and have the same values.
• isSameFloat32Array( v1, v2 ): test if two arguments are both Float32Arrays and have the same values.
• isSameFloat64Array( v1, v2 ): test if two arguments are both Float64Arrays and have the same values.
• isSharedArrayBuffer( value ): test if a value is a SharedArrayBuffer.
• isTruthyArray( value ): test if a value is an array-like object containing only truthy values.
• isTypedArrayLength( value ): test if a value is a valid typed array length.
• isTypedArrayLike( value ): test if a value is typed-array-like.
• isTypedArray( value ): test if a value is a typed array.
• isUnityProbabilityArray( value ): test if a value is an array of probabilities that sum to one.

To test for error objects, the namespace includes the following utilities:

• isError( value ): test if a value is an Error object.
• isEvalError( value ): test if a value is an EvalError object.
• isRangeError( value ): test if a value is a RangeError object.
• isReferenceError( value ): test if a value is a ReferenceError object.
• isSyntaxError( value ): test if a value is a SyntaxError object.
• isTypeError( value ): test if a value is a TypeError object.
• isURIError( value ): test if a value is a URIError object.

The namespace exposes the following constants concerning the current running process:

• IS_BIG_ENDIAN: check if an environment is big endian.
• IS_BROWSER: check if the runtime is a web browser.
• IS_DARWIN: boolean indicating if the current process is running on Darwin.
• IS_DOCKER: check if the process is running in a Docker container.
• IS_ELECTRON_MAIN: check if the runtime is the main Electron process.
• IS_ELECTRON_RENDERER: check if the runtime is the Electron renderer process.
• IS_ELECTRON: check if the runtime is Electron.
• IS_LITTLE_ENDIAN: check if an environment is little endian.
• IS_MOBILE: check if the current environment is a mobile device.
• IS_NODE: check if the runtime is Node.js.
• IS_TOUCH_DEVICE: check if the current environment is a touch device.
• IS_WEB_WORKER: check if the runtime is a web worker.
• IS_WINDOWS: boolean indicating if the current process is running on Windows.

To test whether a runtime environment supports certain features, the namespace includes the following utilities:

• hasArrayBufferSupport(): detect native ArrayBuffer support.
• hasArrowFunctionSupport(): detect native arrow function support.
• hasAsyncAwaitSupport(): detect native async/await support.
• hasAsyncIteratorSymbolSupport(): detect native Symbol.asyncIterator support.
• hasBigIntSupport(): detect native BigInt support.
• hasBigInt64ArraySupport(): detect native BigInt64Array support.
• hasBigUint64ArraySupport(): detect native BigUint64Array support.
• hasClassSupport(): detect native class support.
• hasDataViewSupport(): detect native DataView support.
• hasDefinePropertiesSupport(): detect Object.defineProperties support.
• hasDefinePropertySupport(): detect Object.defineProperty support.
• hasFloat32ArraySupport(): detect native Float32Array support.
• hasFloat64ArraySupport(): detect native Float64Array support.
• hasFunctionNameSupport(): detect native function name support.
• hasGeneratorSupport(): detect native generator function support.
• hasGlobalThisSupport(): detect globalThis support.
• hasInt16ArraySupport(): detect native Int16Array support.
• hasInt32ArraySupport(): detect native Int32Array support.
• hasInt8ArraySupport(): detect native Int8Array support.
• hasIteratorSymbolSupport(): detect native Symbol.iterator support.
• hasMapSupport(): detect native Map support.
• hasNodeBufferSupport(): detect native Buffer support.
• hasProxySupport(): detect native Proxy support.
• hasSetSupport(): detect native Set support.
• hasSharedArrayBufferSupport(): detect native SharedArrayBuffer support.
• hasSymbolSupport(): detect native Symbol support.
• hasToStringTagSupport(): detect native Symbol.toStringTag support.
• hasUint16ArraySupport(): detect native Uint16Array support.
• hasUint32ArraySupport(): detect native Uint32Array support.
• hasUint8ArraySupport(): detect native Uint8Array support.
• hasUint8ClampedArraySupport(): detect native Uint8ClampedArray support.
• hasWebAssemblySupport(): detect native WebAssembly support.
• hasWeakMapSupport(): detect native WeakMap support.
• hasWeakSetSupport(): detect native WeakSet support.

The remaining namespace utilities are as follows:

• contains( val, searchValue[, position] ): test if an array-like value contains a search value.
• deepEqual( a, b ): test for deep equality between two values.
• deepHasOwnProp( value, path[, options] ): test whether an object contains a nested key path.
• deepHasProp( value, path[, options] ): test whether an object contains a nested key path, either own or inherited.
• hasOwnProp( value, property ): test if an object has a specified property.
• hasProp( value, property ): test if an object has a specified property, either own or inherited.
• hasUTF16SurrogatePairAt( string, position ): test if a position in a string marks the start of a UTF-16 surrogate pair.
• instanceOf( value, constructor ): test whether a value has in its prototype chain a specified constructor as a prototype property.
• isAbsoluteHttpURI( value ): test whether a value is an absolute HTTP(S) URI.
• isAbsolutePath( value ): test if a value is an absolute path.
• isAbsoluteURI( value ): test whether a value is an absolute URI.
• isAccessorPropertyIn( value, property ): test if an object's own or inherited property has an accessor descriptor.
• isAccessorProperty( value, property ): test if an object's own property has an accessor descriptor.
• isAlphagram( value ): test if a value is an alphagram.
• isAlphaNumeric( value ): test whether a string contains only alphanumeric characters.
• isAnagram( str, value ): test if a value is an anagram.
• isArguments( value ): test if a value is an arguments object.
• isArrowFunction( value ): test if a value is an arrow function.
• isASCII( value ): test whether a character belongs to the ASCII character set and whether this is true for all characters in a provided string.
• isBetween( value, a, b[, left, right] ): test if a value is between two values.
• isBigInt( value ): test if a value is a BigInt.
• isBinaryString( value ): test if a value is a binary string.
• isBlankString( value ): test if a value is a blank string.
• isBoxedPrimitive( value ): test if a value is a JavaScript boxed primitive.
• isBuffer( value ): test if a value is a Buffer object.
• isCamelcase( value ): test if a value is a camelcase string.
• isCapitalized( value ): test if a value is a string having an uppercase first character.
• isCircular( value ): test if a value is a plain object containing a circular reference.
• isCircular( value ): test if an object-like value contains a circular reference.
• isClass( value ): test if a value is a class.
• isCollection( value ): test if a value is a collection.
• isComposite( value ): test if a value is a composite number.
• isConfigurablePropertyIn( value, property ): test if an object's own or inherited property is configurable.
• isConfigurableProperty( value, property ): test if an object's own property is configurable.
• isConstantcase( value ): test if a value is a constantcase string.
• isCurrentYear( value ): test if a value is the current year.
• isDataPropertyIn( value, property ): test if an object's own or inherited property has a data descriptor.
• isDataProperty( value, property ): test if an object's own property has a data descriptor.
• isDataView( value ): test if a value is a DataView.
• isDigitString( value ): test whether a string contains only numeric digits.
• isDomainName( value ): test if a value is a domain name.
• isDurationString( value ): test if a value is a duration string.
• isEmailAddress( value ): test if a value is an email address.
• isEmptyCollection( value ): test if a value is an empty collection.
• isEmptyObject( value ): test if a value is an empty object.
• isEmptyString( value ): test if a value is an empty string.
• isEnumerablePropertyIn( value, property ): test if an object's own or inherited property is enumerable.
• isEnumerableProperty( value, property ): test if an object's own property is enumerable.
• isEven( value ): test if a value is an even number.
• isFalsy( value ): test if a value is falsy.
• isFinite( value ): test if a value is a finite number.
• isGeneratorObjectLike( value ): test if a value is generator object-like.
• isGeneratorObject( value ): test if a value is a generator object.
• isgzipBuffer( value ): test if a value is a gzip buffer.
• isHexString( value ): test whether a string contains only hexadecimal digits.
• isInfinite( value ): test if a value is an infinite number.
• isInheritedProperty( value, property ): test if an object has an inherited property.
• isIterableLike( value ): test if a value is iterable-like.
• isIteratorLike( value ): test if a value is iterator-like.
• isJSON( value ): test if a value is a parseable JSON string.
• isKebabcase( value ): test if a value is a string in kebab case.
• isLeapYear( [value] ): test if a value corresponds to a leap year in the Gregorian calendar.
• isLocalhost( value ): test whether a value is a localhost hostname.
• isLowercase( value ): test if a value is a lowercase string.
• isMethodIn( value, property ): test if an object has a specified method name, either own or inherited.
• isMethod( value, property ): test if an object has a specified method name.
• isMultiSlice( value ): test if a value is a MultiSlice.
• isNamedTypedTupleLike( value ): test if a value is named typed tuple-like.
• isNativeFunction( value ): test if a value is a native function.
• isNegativeZero( value ): test if a value is a number equal to negative zero.
• isNodeBuiltin( value ): test whether a string matches a Node.js built-in module name.
• isNodeDuplexStreamLike( value ): test if a value is Node duplex stream-like.
• isNodeReadableStreamLike( value ): test if a value is Node readable stream-like.
• isNodeREPL(): check if running in a Node.js REPL environment.
• isNodeStreamLike( value ): test if a value is Node stream-like.
• isNodeTransformStreamLike( value ): test if a value is Node transform stream-like.
• isNodeWritableStreamLike( value ): test if a value is Node writable stream-like.
• isNonConfigurablePropertyIn( value, property ): test if an object's own or inherited property is non-configurable.
• isNonConfigurableProperty( value, property ): test if an object's own property is non-configurable.
• isNonEnumerablePropertyIn( value, property ): test if an object's own or inherited property is non-enumerable.
• isNonEnumerableProperty( value, property ): test if an object's own property is non-enumerable.
• isNonNegativeFinite( value ): test if a value is a number having a nonnegative finite value.
• isObjectLike( value ): test if a value is object-like.
• isOdd( value ): test if a value is an odd number.
• isPascalcase( value ): test if a value is a string in Pascal case.
• isPlainObject( value ): test if a value is a plain object.
• isPositiveZero( value ): test if a value is a number equal to positive zero.
• isPrime( value ): test if a value is a prime number.
• isPrimitive( value ): test if a value is a JavaScript primitive.
• isPRNGLike( value ): test if a value is PRNG-like.
• isProbability( value ): test if a value is a probability.
• isPropertyKey( value ): test whether a value is a property key.
• isPrototypeOf( obj, prototype ): test if an object's prototype chain contains a provided prototype.
• isReadOnlyPropertyIn( value, property ): test if an object's own or inherited property is read-only.
• isReadOnlyProperty( value, property ): test if an object's own property is read-only.
• isReadWritePropertyIn( value, property ): test if an object's own or inherited property is readable and writable.
• isReadWriteProperty( value, property ): test if an object's own property is readable and writable.
• isReadablePropertyIn( value, property ): test if an object's own or inherited property is readable.
• isReadableProperty( value, property ): test if an object's own property is readable.
• isRegExpString( value ): test if a value is a regular expression string.
• isRelativePath( value ): test if a value is a relative path.
• isRelativeURI( value ): test whether a value is a relative URI.
• isSameComplex128( v1, v2 ): test if two arguments are both double-precision complex floating-point numbers and have the same value.
• isSameComplex64( v1, v2 ): test if two arguments are both single-precision complex floating-point numbers and have the same value.
• isSameNativeClass( a, b ): test if two arguments have the same native class.
• isSameType( a, b ): test if two arguments have the same type.
• isSameValueZero( a, b ): test if two arguments are the same value.
• isSameValue( a, b ): test if two arguments are the same value.
• isSemVer( value ): test if a value is a semantic version string.
• isSlice( value ): test if a value is a Slice.
• isSnakecase( value ): test if a value is a string in snake case.
• isStartcase( value ): test if a value is a startcase string.
• isStrictEqual( a, b ): test if two arguments are strictly equal.
• isTruthy( value ): test if a value is truthy.
• isUNCPath( value ): test if a value is a UNC path.
• isUndefinedOrNull( value ): test if a value is undefined or null.
• isUppercase( value ): test if a value is an uppercase string.
• isURI( value ): test if a value is a URI.
• isWhitespace( value ): test whether a string contains only white space characters.
• isWritablePropertyIn( value, property ): test if an object's own or inherited property is writable.
• isWritableProperty( value, property ): test if an object's own property is writable.
• isWriteOnlyPropertyIn( value, property ): test if an object's own or inherited property is write-only.
• isWriteOnlyProperty( value, property ): test if an object's own property is write-only.
• tools: assertion utility tools.

Examples

var objectKeys = require( '@stdlib/utils/keys' );
var assert = require( '@stdlib/assert' );

console.log( objectKeys( assert ) );

---

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

---

License

See LICENSE.

Copyright

Copyright © 2016-2024. The Stdlib Authors.