Bossy Boots

Bossy Boots is a helpful collection of type guards and assertions, written in TypeScript.

Contents

Overview

The benefits of using Bossy Boots include a more robust runtime and less repetitious logic in your code. With type definitions included out the box, TypeScript environments (especially those in strict mode) will benefit even further with accurate type inference and narrowing.

The bulk of Bossy Boots is made up of assertions and guards that take a value and check if it matches one or more predicates. The most important distinction between the two is that assertions will throw if the check fails, whereas guards will return a boolean instead, allowing you implement your own handling logic. Most assertions have (and use) guard counterparts.

Installation

npm i bossy-boots

Usage

Bossy Boots is completely modular and compatible with both ESM and CommonJS environments.

// ESM
import { ... } from 'bossy-boots';

// CommonJS
const { ... } = require('bossy-boots');

💡 Assertions will throw if the check fails. If not handled this will stop execution.

Assert that a value is an instance of one or more prototypes.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...prototypes | Array.<function()> | The prototype(s) to check |

Example:

function foo(input: Red | Yellow | Green | Blue) {
    try {
        assertIsInstanceOf(input, Yellow, Blue);
        input; // Yellow | Blue
    } catch (error) {}
}

Assert that a value is not an instance of one or more prototypes.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...prototypes | Array.<function()> | The prototype(s) to check |

Example:

function foo(input: Red | Yellow | Green | Blue) {
    try {
        assertIsNotInstanceOf(input, Yellow, Blue);
        input; // Red | Green
    } catch (error) {}
}

Assert that a value's type matches one or more types.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...types | Array.<Primitive> | The types(s) to check |

Example:

function foo(input: string | number | symbol | boolean) {
    try {
        assertIsTypeOf(input, 'number', 'boolean');
        input; // number | boolean
    } catch (error) {}
}

Assert that a value's type does not match one or more types.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...types | Array.<Primitive> | The types(s) to check |

Example:

function foo(input: string | number | symbol | boolean) {
    try {
        assertIsNotTypeOf(input, 'number', 'boolean');
        input; // string | symbol
    } catch (error) {}
}

💡 Guards return a boolean that is true if the check succeeds, and false otherwise.

Check that a value is an instance of one or more prototypes.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...prototypes | Array.<function()> | The prototype(s) to check |

Example:

function foo(input: Red | Yellow | Green | Blue) {
    if (isInstanceOf(input, Yellow, Blue)) {
        input; // Yellow | Blue
    }
}

Check that a value is not an instance of one or more prototypes.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...prototypes | Array.<function()> | The prototype(s) to check |

Example:

function foo(input: Red | Yellow | Green | Blue) {
    if (isNotInstanceOf(input, Yellow, Blue)) {
        input; // Red | Green
    }
}

Check that a value's type matches one or more types.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...types | Array.<Primitive> | The types(s) to check |

Example:

function foo(input: string | number | symbol | boolean) {
    if (isTypeOf(input, 'number', 'boolean')) {
        input; // number | boolean
    }
}

Check that a value's type does not match one or more types.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to assert | | ...types | Array.<Primitive> | The types(s) to check |

Example:

function foo(input: string | number | symbol | boolean) {
    if (isNotTypeOf(input, 'number', 'boolean')) {
        input; // string | symbol
    }
}

While the overarching ...InstanceOf() and ...TypeOf() methods are powerful and flexible, they too may become gratuitous for repetitive checks. To this end Bossy Boots also includes a collection of methods which abstract common checks. These methods only require a value.

Example:

assertIsBoolean(value);

// Is the equivalent of:

assertIsType(value, 'boolean');

Available methods:

* nullish is equivalent to null or undefined.

Assert that a condition is true.

| Param | Type | Description | | --- | --- | --- | | condition | unknown | The condition to assert | | [message] | string | An optional message to include if the assertion fails |

Example:

function foo(input: number) {
    assert(input === 1);
    input; // 1
}

Guarantee that a value is not nullish (null or undefined), with an optional fallback.

| Param | Type | Description | | --- | --- | --- | | value | unknown | The value to guarantee | | [fallback] | unknown | An optional fallback value |

Returns:

value or fallback if either are not nullish, otherwise will throw

Example:

// Value will be `null | Element`
const foo = document.querySelectorAll('.foo');

// Value will be `Element`.
const bar = guarantee(document.querySelectorAll('.bar'));