@valu/assert v1.3.3

@valu/assert

Small collection of type predicates and assertion functions.

Helps working with possibly undefined types generated from GraphQL queries.

This library has its own concept called "nil" which means null or undefined.

CS 101: Asserting means throwing and crashing if the assertion condition is not met

notNil()

Type predicate for checking nil values

import { notNil } from "@valu/assert";

function fn(text: string | null | undefined) {
    if (notNil(text)) {
        text.toUpperCase(); // ok!
    }
}

which is almost the same as

function fn(text: string | null | undefined) {
    if (text) {
        text.toUpperCase(); // ok!
    }
}

but it will allow an empty string "" since it is not nil.

But its most powerful use case is when used as a type predicate in .filter():

type Node = { value: number } | null | undefined;

const nodes: Nodes[] = [null, undefined, { value: 1 }];

nodes.filter(notNil).map((node) => {
    node.value; // ok!
});

Use when mapping GraphQL node lists!

assertNotNil(value: any, customErrorMessage?: string)

Assertion function for removing nil values.

import { assertNotNil } from "@valu/assert";

function fn(item: { value: number } | null | undefined) {
    assertNotNil(item);

    item.value; // ok!
}

Use when you know the value cannot be nil

assertIs(target: any, value: any customErrorMessage?: string)

Assert that the target is explicitly of the given type

import { assertIs } from "@valu/assert";

function fn(item: { value: number } | boolean | null) {
    assertIs(item, false as const);

    item; // item === false
}

Can be used to assert discriminated unions

type Item =
    | {
          type: "post";
          postTitle: string;
      }
    | {
          type: "page";
          pageTitle: string;
      };

function fn(item: Item) {
    item.postTitle; // Error!
    assertIs(item.type, "post" as const);
    item.postTitle; // ok!
}

function fn2(item: Item) {
    item.pageTitle; // Error!
    assertIs(item.type, "page" as const);
    item.pageTitle; // ok!
}

GraphQL node connections have often types like this.

assertNotBrowser()

Throw if the environment is a web browser. Used assert that server-side code is not accidentally loaded into the browser bundles.

assert(cond: boolean, message: string, offsetStack?: number)

Plain assert function with offsettable stack for better error messages like in:

https://kentcdodds.com/blog/improve-test-error-messages-of-your-abstractions

import { assert } from "@valu/assert";

function assertCustom() {
    assert(true === false, "Fail", 2);
}

assertNotAny()

Assert that the given value is not type of any

import { assertNotAny } from "@valu/assert";

const value: any = "wat";
// Produces type error
assertNotAny(value);

const value = "wat";
// ok because is string
assertNotAny(value);

assertType()

Assert that the given value is not type of any

import { assertType } from "@valu/assert";

const value: string = "wat";
// Produces type error because string is not assignable to number
assertType<number>(value);

const value = "wat";
// ok
assertType<string>(value);