Noncollinear Perpendicular Microcrystalline

    @martellosecurity/conditions
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published

    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.

    Integration

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

    Install

    npm i @martellosecurity/conditions

    DownloadsWeekly Downloads

    6

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    17.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • garrettheaver