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]+$/);
  }

}