Conditions for Node.js
Conditions is a library of pre-condition, post-condition and invariant helpers. It exists to support design by contract based approaches to domain models.
If you are unfamiliar with concepts such as conditions, invariants, design by contract, immutability or domain models we suggest reading the Secure by Design series of articles on the Martello Security website.
Getting Started
Execute the install command for your chosen package manager.
npm install --save @martellosecurity/conditions
yarn add @martellosecurity/conditions
Then import the conditions you want to use in your classes and functions.
import { notNull, maxLength } from '@martellosecurity/conditions';TypeScript Support
The project comes complete with definition files that support the type system and enables intellisense in TypeScript editors.
Although vanilla JavaScript is obviously supported, TypeScript is recommended for most projects to avail of the additional safety net of compile time type checking.
Versioning Policy
The project follows semantic versioning. See semver.org for more details.
Usage
The basic operation of all conditions is to make a specific assertion returning the input value if the condition passes or throwing an appropriate error if it fails.
The general function signature is that the input check value comes first, followed by any required configuration and an optional final message parameter.
Providing an invalid configuration parameter (e.g. null instead of a number) will throw a TypeError.
By default, any error thrown includes a default message. This can be overridden with the optional final message parameter.
Null Prevention
notNull<T>(input: T, message?: string): T
Perhaps the most fundamental condition all functions should enforce is that mandatory parameters are not null.
Javascript includes both a null and an undefined value. The notNull condition protects against both of these, throwing a NullValueError on failure.
import { notNull } from '@martellosecurity/conditions';
class MyDomainPrimitive {
constructor(value) {
this.value = notNull(value);
}
}Length Checks
Verifying the length of input parameters (e.g. name or email) is a fundamental condition all code should enforce. These checks are simple, efficient and should be done before any attempt to parse or process the data futher (e.g. before syntactic format checks, etc).
Many different types can have length in Javascript such as a string, array, buffer or even one of your own domain objects. This small family of conditions can be used with any object with a length property.
minLength
minLength<T>(input: T, minimum: number, message?: string): T
The minLength condition verifies that the input has a length greater than or equal to the specified minimum value. On failure a MinimumLengthError will be thrown.
maxLength
maxLength<T>(input: T, maximum: number, message?: string): T
The maxLength condition verifies that the input value has a length less than or equal to the specified maximum value. On failure a MaximumLengthError will be thrown.
exactLength
exactLength<T>(input: T, expected: number, message?: string): T
The exactLength condition verifies that the input value has a length equal to the specified expected value. On failure a ExpectedLengthError will be thrown.
lengthBetween
lengthBetween<T>(input: T, minimum: number, maximum: number, message?: string): T
A combined lengthBetween condition verifies that the input has a length between both specified minimum and maximum values (inclusive).
The minimum length check is performed first and the maximum length check second. On failure a MinimumLengthError or MaximumLengthError will be thrown depending on which condition fails.
import { notNull, lengthBetween } from '@martellosecurity/conditions';
class MyDomainPrimitive {
constructor(value) {
notNull(value);
this.value = lengthBetween(value, 5, 20);
}
}Format Matching
After basic conditions such as notNull and maxLength have been verified, syntactic checks such as the format of parameters can be performed.
matchesRegExp
matchesRegExp(input: string, format: RegExp, message?: string): string
The matchesRegExp condition verifies that the input value matches the specified regexp format. Only primitive string input values will be accepted. On failure a RegExpMismatchError will be thrown.
import * as c from '@martellosecurity/conditions';
class MyDomainPrimitive {
constructor(value) {
c.notNull(value);
c.lengthBetween(value, 5, 20);
this.value = c.matchesRegExp(value, /^ABC[a-z]+$/);
}
}