Fluent API for Design Contracts

A fluent API for enforcing design contracts with automatic message generation.

✔️ Easy to use
✔️ Fast
✔️ Production-ready

To get started, add this dependency:

npm install --save @cowwoc/requirements@3.3.3
Copy

or pnpm:

pnpm add @cowwoc/requirements@3.3.3
Copy

The contents of the API classes depend on which modules are enabled.

Sample Code

import {requireThat} from "@cowwoc/requirements";


class Address
{
}

class PublicAPI
{
    constructor(name: string | null, age: number, address: Address | undefined)
    {
        // To validate user input, cast them to "unknown" prior to type-checks.
        requireThat(name as unknown, "name").isString().length().isBetween(1, 30);
        requireThat(age as unknown, "age").isNumber().isBetween(18, 30);

        // Methods that conduct runtime type-checks, such as isString() or isNotNull(), update the
        // compile-time type returned by getActual().
        const nameIsString: string = requireThat(name as unknown, "name").isString().getActual();
        const address: Address = requireThat(address as unknown, "address").isInstance(Address).getActual();
    }
}

class PrivateAPI
{
    public static toCamelCase(text): string
    {
        // Trusted input does not need to be casted to "unknown". The input type will be inferred
        // and runtime checks will be skipped. Notice the lack of isString() or isNumber() invocations
        // in the following code.
        assertThat(r => r.requireThat(name, "name").length().isBetween(1, 30));
        assertThat(r => r.requireThat(age, "age").isBetween(18, 30));
    }
}
Copy

Failure messages will look like this:

TypeError: name may not be null

RangeError: name may not be empty

RangeError: age must be in range [18, 30).
Actual: 15
Copy

Features

• Automatic message generation
• Diffs provided whenever possible
• Assertion support
• Grouping nested requirements
• String diff

Getting Started

The best way to learn about the API is using your IDE's auto-complete engine. There are six entry points you can navigate from:

• requireThat(value, name)

• validateThat(value, name)

• assertThat(Function)

• assertThatAndReturn(Function)

• Requirements

• GlobalRequirements

Best practices

• Use requireThat() to verify pre-conditions of public APIs.
• Use assertThat() to verify object invariants and method post-conditions. This results in excellent performance when assertions are disabled. Have your cake and eat it too!

Related Projects

• http://chaijs.com/
• https://github.com/dsheiko/bycontract
• https://github.com/muroc/offensive.js

License

Code licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Icons made by Flat Icons from www.flaticon.com is licensed by CC 3.0 BY