@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
518 lines (517 loc) • 18.6 kB
TypeScript
import { type MaybePromise, type NarrowToExpected } from '@augment-vir/core';
import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
/**
* All falsy values in JavaScript. This does not include `NaN` because there is no dedicated type
* for it in TypeScript.
*
* @category Assert : Util
* @category Package : @augment-vir/assert
* @example
*
* ```ts
* import {type FalsyValue} from '@augment-vir/assert';
*
* const falsy: FalsyValue = 0;
* ```
*
* @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
*/
export type FalsyValue = undefined | null | false | 0 | '' | -0 | 0n;
/**
* Narrows the given type parameter `T` to all its falsy sub-types.
*
* @category Assert : Util
* @category Package : @augment-vir/assert
* @example
*
* ```ts
* import {type Falsy} from '@augment-vir/assert';
*
* type MyFalsy = Falsy<string | number>; // "" | 0
* ```
*
* @param T The original type to narrow.
* @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
*/
export type Falsy<T> = NarrowToExpected<T, FalsyValue>;
/**
* Narrows the given type parameter `T` to all its truthy sub-types.
*
* @category Assert : Util
* @category Package : @augment-vir/assert
* @example
*
* ```ts
* import {type Truthy} from '@augment-vir/assert';
*
* type MyTruthy = Truthy<0 | undefined | string>; // string
* ```
*
* @param T The original type to narrow.
* @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
*/
export type Truthy<T> = Exclude<T, FalsyValue>;
export declare const booleanGuards: {
assert: {
/**
* Asserts that a value is exactly `false`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isFalse(true); // fails
* assert.isFalse(false); // passes
* assert.isFalse(1); // fails
* assert.isFalse(0); // fails
* ```
*
* @throws {@link AssertionError} If the value is not `false`.
* @see
* - {@link assert.isTrue} : the opposite assertion.
* - {@link assert.isFalsy} : a less exact assertion.
*/
isFalse(this: void, input: unknown, failureMessage?: string | undefined): asserts input is false;
/**
* Asserts that a value is falsy.
*
* Type guards the value when possible.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isFalsy(true); // fails
* assert.isFalsy(false); // passes
* assert.isFalsy(1); // fails
* assert.isFalsy(0); // passes
* ```
*
* @throws {@link AssertionError} If the value is not falsy.
* @see
* - {@link assert.isTruthy} : the opposite assertion.
* - {@link assert.isFalse} : a more exact assertion.
*/
isFalsy(this: void, input: unknown, failureMessage?: string | undefined): asserts input is FalsyValue;
/**
* Asserts that a value is exactly `true`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isTrue(true); // passes
* assert.isTrue(false); // fails
* assert.isTrue(1); // fails
* assert.isTrue(0); // fails
* ```
*
* @throws {@link AssertionError} If the value is not `true`.
* @see
* - {@link assert.isFalse} : the opposite assertion.
* - {@link assert.isTruthy} : a less exact assertion.
*/
isTrue(this: void, input: unknown, failureMessage?: string | undefined): asserts input is true;
/**
* Asserts that a value is truthy.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isTruthy(true); // passes
* assert.isTruthy(false); // fails
* assert.isTruthy(1); // passes
* assert.isTruthy(0); // fails
* ```
*
* @throws {@link AssertionError} If the value is not truthy.
* @see
* - {@link assert.isFalsy} : the opposite assertion.
* - {@link assert.isTrue} : a more exact assertion.
*/
isTruthy<const Actual>(this: void, input: Actual, failureMessage?: string | undefined): asserts input is Truthy<Actual>;
};
check: {
/**
* Checks that a value is exactly `false`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isFalse(true); // returns `false`
* check.isFalse(false); // returns `true`
* check.isFalse(1); // returns `false`
* check.isFalse(0); // returns `false`
* ```
*
* @see
* - {@link check.isTrue} : the opposite check.
* - {@link check.isFalsy} : a less exact check.
*/
isFalse(this: void, input: unknown): input is false;
/**
* Checks that a value is falsy.
*
* Type guards the value when possible.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isFalsy(true); // returns `false`
* check.isFalsy(false); // returns `true`
* check.isFalsy(1); // returns `false`
* check.isFalsy(0); // returns `true`
* ```
*
* @see
* - {@link check.isTruthy} : the opposite check.
* - {@link check.isFalse} : a more exact check.
*/
isFalsy(this: void, input: unknown): input is FalsyValue;
/**
* Checks that a value is exactly `true`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isTrue(true); // returns `true`
* check.isTrue(false); // returns `false`
* check.isTrue(1); // returns `false`
* check.isTrue(0); // returns `false`
* ```
*
* @see
* - {@link check.isFalse} : the opposite check.
* - {@link check.isTruthy} : a less exact check.
*/
isTrue(this: void, input: unknown): input is true;
/**
* Checks that a value is truthy.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isTruthy(true); // passes
* check.isTruthy(false); // fails
* check.isTruthy(1); // passes
* check.isTruthy(0); // fails
* ```
*
* @see
* - {@link check.isFalsy} : the opposite check.
* - {@link check.isTrue} : a more exact check.
*/
isTruthy<T>(this: void, input: T): input is Truthy<T>;
};
assertWrap: {
/**
* Asserts that a value is exactly `false`. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isFalse(true); // throws an error
* assertWrap.isFalse(false); // returns `false`
* assertWrap.isFalse(1); // throws an error
* assertWrap.isFalse(0); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the value is not `false`.
* @see
* - {@link assertWrap.isTrue} : the opposite assertion.
* - {@link assertWrap.isFalsy} : a less exact assertion.
*/
isFalse(this: void, input: unknown, failureMessage?: undefined | string): false;
/**
* Asserts that a value is falsy. Returns the value if the assertion passes.
*
* Type guards the value when possible.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isFalsy(true); // throws an error
* assertWrap.isFalsy(false); // returns `false`
* assertWrap.isFalsy(1); // throws an error
* assertWrap.isFalsy(0); // returns `0`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the value is not falsy.
* @see
* - {@link assertWrap.isTruthy} : the opposite assertion.
* - {@link assertWrap.isFalse} : a more exact assertion.
*/
isFalsy<T>(this: void, input: T, failureMessage?: undefined | string): Falsy<T>;
/**
* Asserts that a value is exactly `true`. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isTrue(true); // returns `true`
* assertWrap.isTrue(false); // throws an error
* assertWrap.isTrue(1); // throws an error
* assertWrap.isTrue(0); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the value is not `true`.
* @see
* - {@link assertWrap.isFalse} : the opposite assertion.
* - {@link assertWrap.isTruthy} : a less exact assertion.
*/
isTrue(this: void, input: unknown, failureMessage?: undefined | string): true;
/**
* Asserts that a value is truthy. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isTruthy(true); // returns `true`
* assertWrap.isTruthy(false); // throws an error
* assertWrap.isTruthy(1); // returns `1`
* assertWrap.isTruthy(0); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the value is not truthy.
* @see
* - {@link assertWrap.isFalsy} : the opposite assertion.
* - {@link assertWrap.isTrue} : a more exact assertion.
*/
isTruthy<T>(this: void, input: T, failureMessage?: undefined | string): Truthy<T>;
};
checkWrap: {
/**
* Checks that a value is exactly `false`. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isFalse(true); // returns `false`
* checkWrap.isFalse(false); // returns `true`
* checkWrap.isFalse(1); // returns `false`
* checkWrap.isFalse(0); // returns `false`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isTrue} : the opposite check.
* - {@link checkWrap.isFalsy} : a less exact check.
*/
isFalse(this: void, input: unknown): false | undefined;
/**
* Checks that a value is falsy. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value when possible.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isFalsy(true); // returns `false`
* checkWrap.isFalsy(false); // returns `true`
* checkWrap.isFalsy(1); // returns `false`
* checkWrap.isFalsy(0); // returns `true`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isTruthy} : the opposite check.
* - {@link checkWrap.isFalse} : a more exact check.
*/
isFalsy<T>(this: void, input: T): Falsy<T> | undefined;
/**
* Checks that a value is exactly `true`. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isTrue(true); // returns `true`
* checkWrap.isTrue(false); // returns `false`
* checkWrap.isTrue(1); // returns `false`
* checkWrap.isTrue(0); // returns `false`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isFalse} : the opposite check.
* - {@link checkWrap.isTruthy} : a less exact check.
*/
isTrue(this: void, input: unknown): true | undefined;
/**
* Checks that a value is truthy. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isTruthy(true); // passes
* checkWrap.isTruthy(false); // fails
* checkWrap.isTruthy(1); // passes
* checkWrap.isTruthy(0); // fails
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isFalsy} : the opposite check.
* - {@link checkWrap.isTrue} : a more exact check.
*/
isTruthy<T>(this: void, input: T): Truthy<T> | undefined;
};
waitUntil: {
/**
* Repeatedly calls a callback until its output is exactly `false`. Once the callback output
* passes, it is returned. If the attempts time out, an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.isFalse(() => true); // throws an error
* await waitUntil.isFalse(() => false); // returns `false`
* await waitUntil.isFalse(() => 1); // throws an error
* await waitUntil.isFalse(() => 0); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.isTrue} : the opposite assertion.
* - {@link waitUntil.isFalsy} : a less exact assertion.
*/
isFalse: (this: void, callback: () => MaybePromise<unknown>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<false>;
/**
* Repeatedly calls a callback until its output is falsy. Once the callback output passes,
* it is returned. If the attempts time out, an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.isFalsy(() => true); // throws an error
* await waitUntil.isFalsy(() => false); // returns `false`
* await waitUntil.isFalsy(() => 1); // throws an error
* await waitUntil.isFalsy(() => 0); // returns `0`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.isTruthy} : the opposite assertion.
* - {@link waitUntil.isFalse} : a more exact assertion.
*/
isFalsy: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Falsy<Actual>>;
/**
* Repeatedly calls a callback until its output is exactly `true`. Once the callback output
* passes, it is returned. If the attempts time out, an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.isTrue(() => true); // returns `true`
* await waitUntil.isTrue(() => false); // throws an error
* await waitUntil.isTrue(() => 1); // throws an error
* await waitUntil.isTrue(() => 0); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.isFalse} : the opposite assertion.
* - {@link waitUntil.isTruthy} : a less exact assertion.
*/
isTrue: (this: void, callback: () => MaybePromise<unknown>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<true>;
/**
* Repeatedly calls a callback until its output is truthy. Once the callback output passes,
* it is returned. If the attempts time out, an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.isTruthy(() => true); // returns `true`
* await waitUntil.isTruthy(() => false); // throws an error
* await waitUntil.isTruthy(() => 1); // returns `1`
* await waitUntil.isTruthy(() => 0); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.isFalsy} : the opposite assertion.
* - {@link waitUntil.isTrue} : a more exact assertion.
*/
isTruthy: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Truthy<Actual>>;
};
};