@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
1,401 lines • 83 kB
TypeScript
import { type AnyFunction, type MaybePromise, type NarrowToActual, type NarrowToExpected, type UnknownObject } from '@augment-vir/core';
import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
type ArrayNarrow<Actual> = NarrowToExpected<Actual, unknown[]> extends never ? NarrowToExpected<Actual, ReadonlyArray<unknown>> extends never ? unknown[] extends Actual ? unknown[] : never : NarrowToExpected<Actual, ReadonlyArray<unknown>> : NarrowToExpected<Actual, unknown[]>;
export declare const runtimeTypeGuards: {
assert: {
/**
* Asserts that a value is an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isArray([]); // passes
* assert.isArray({length: 4}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotArray} : the opposite assertion.
*/
isArray<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is ArrayNarrow<Actual>;
/**
* Asserts that a value is a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isBigInt(123n); // passes
* assert.isBigInt(123); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotBigInt} : the opposite assertion.
*/
isBigInt(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is bigint;
/**
* Asserts that a value is a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isBoolean(true); // passes
* assert.isBoolean('true'); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotBoolean} : the opposite assertion.
*/
isBoolean(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is boolean;
/**
* Asserts that a value is a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isFunction(() => {}); // passes
* assert.isFunction({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotFunction} : the opposite assertion.
*/
isFunction<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is NarrowToActual<Actual, AnyFunction>;
/**
* Asserts that a value is exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNull(null); // passes
* assert.isNull(undefined); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotNull} : the opposite assertion.
*/
isNull(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is null;
/**
* Asserts that a value is a number. This excludes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNumber(123); // passes
* assert.isNumber(123n); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotNumber} : the opposite assertion.
*/
isNumber(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is number;
/**
* Asserts that a value is an object. This excludes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isObject({}); // passes
* assert.isObject([]); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotObject} : the opposite assertion.
*/
isObject(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is UnknownObject;
/**
* Asserts that a value is a plain object. This excludes arrays and class instances.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPlainObject({}); // passes
* assert.isPlainObject({value: 'key'}); // passes
* assert.isPlainObject(null); // fails
* assert.isPlainObject(new RegExp()); // fails
* assert.isPlainObject(new Date()); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotPlainObject} : the opposite assertion.
* - {@link assert.isObject} : a more generic object assertion.
*/
isPlainObject(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is UnknownObject;
/**
* Asserts that a value is a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isString(''); // passes
* assert.isString(5); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotString} : the opposite assertion.
*/
isString(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is string;
/**
* Asserts that a value is a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isSymbol(Symbol('my-symbol')); // passes
* assert.isSymbol('my-symbol'); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotSymbol} : the opposite assertion.
*/
isSymbol(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is symbol;
/**
* Asserts that a value is exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isUndefined(undefined); // passes
* assert.isUndefined(null); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotUndefined} : the opposite assertion.
*/
isUndefined(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is undefined;
/**
* Asserts that a value is _not_ an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotArray([]); // fails
* assert.isNotArray({length: 4}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isArray} : the opposite assertion.
*/
isNotArray<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, ReadonlyArray<unknown>>;
/**
* Asserts that a value is _not_ a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotBigInt(123n); // fails
* assert.isNotBigInt(123); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isBigInt} : the opposite assertion.
*/
isNotBigInt<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, bigint>;
/**
* Asserts that a value is _not_ a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotBoolean(true); // fails
* assert.isNotBoolean('true'); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isBoolean} : the opposite assertion.
*/
isNotBoolean<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, boolean>;
/**
* Asserts that a value is _not_ a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotFunction(() => {}); // fails
* assert.isNotFunction({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotFunction<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, AnyFunction>;
/**
* Asserts that a value is _not_ exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotNull(null); // fails
* assert.isNotNull(undefined); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed. @see
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotNull<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, null>;
/**
* Asserts that a value is _not_ a number. This includes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotNumber(123); // fails
* assert.isNotNumber(123n); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNumber} : the opposite assertion.
*/
isNotNumber<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, number>;
/**
* Asserts that a value is _not_ an object. This includes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotObject({}); // fails
* assert.isNotObject([]); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotObject<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, UnknownObject>;
/**
* Asserts that a value is not a plain object. This includes arrays and class instances.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotPlainObject({}); // fails
* assert.isNotPlainObject({value: 'key'}); // fails
* assert.isNotPlainObject(null); // passes
* assert.isNotPlainObject(new RegExp()); // passes
* assert.isNotPlainObject(new Date()); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isPlainObject} : the opposite assertion.
* - {@link assert.isNotObject} : a more generic non-object assertion.
*/
isNotPlainObject(this: void, actual: unknown, failureMessage?: string | undefined): void;
/**
* Asserts that a value is _not_ a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotString(''); // fails
* assert.isNotString(5); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotString<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, string>;
/**
* Asserts that a value is _not_ a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotSymbol(Symbol('my-symbol')); // fails
* assert.isNotSymbol('my-symbol'); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotSymbol<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, symbol>;
/**
* Asserts that a value is _not_ exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotUndefined(undefined); // fails
* assert.isNotUndefined(null); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotUndefined<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, undefined>;
};
check: {
/**
* Checks that a value is an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isArray([]); // returns `true`
* check.isArray({length: 4}); // returns `false`
* ```
*
* @see
* - {@link check.isNotArray} : the opposite check.
*/
isArray<Actual>(this: void, actual: Actual): actual is ArrayNarrow<Actual>;
/**
* Checks that a value is a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isBigInt(123n); // returns `true`
* check.isBigInt(123); // returns `false`
* ```
*
* @see
* - {@link check.isNotBigInt} : the opposite check.
*/
isBigInt<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, bigint>;
/**
* Checks that a value is a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isBoolean(true); // returns `true`
* check.isBoolean('true'); // returns `false`
* ```
*
* @see
* - {@link check.isNotBoolean} : the opposite check.
*/
isBoolean<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, boolean>;
/**
* Checks that a value is a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isFunction(() => {}); // returns `true`
* check.isFunction({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotFunction} : the opposite check.
*/
isFunction<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, AnyFunction>;
/**
* Checks that a value is exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNull(null); // returns `true`
* check.isNull(undefined); // returns `false`
* ```
*
* @see
* - {@link check.isNotNull} : the opposite check.
*/
isNull<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, null>;
/**
* Checks that a value is a number. This excludes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNumber(123); // returns `true`
* check.isNumber(123n); // returns `false`
* ```
*
* @see
* - {@link check.isNotNumber} : the opposite check.
*/
isNumber<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, number>;
/**
* Checks that a value is an object. This excludes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isObject({}); // returns `true`
* check.isObject([]); // returns `false`
* ```
*
* @see
* - {@link check.isNotObject} : the opposite check.
*/
isObject<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, UnknownObject>;
/**
* Checks that a value is a plain object. This excludes arrays and class instances.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPlainObject({}); // returns `true`
* check.isPlainObject({value: 'key'}); // returns `true`
* check.isPlainObject(null); // returns `false`
* check.isPlainObject(new RegExp()); // returns `false`
* check.isPlainObject(new Date()); // returns `false`
* ```
*
* @see
* - {@link check.isNotPlainObject} : the opposite check.
* - {@link check.isObject} : a more generic object check.
*/
isPlainObject<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, UnknownObject>;
/**
* Checks that a value is a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isString(''); // returns `true`
* check.isString(5); // returns `false`
* ```
*
* @see
* - {@link check.isNotString} : the opposite check.
*/
isString<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, string>;
/**
* Checks that a value is a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isSymbol(Symbol('my-symbol')); // returns `true`
* check.isSymbol('my-symbol'); // returns `false`
* ```
*
* @see
* - {@link check.isNotSymbol} : the opposite check.
*/
isSymbol<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, symbol>;
/**
* Checks that a value is exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isUndefined(undefined); // returns `true`
* check.isUndefined(null); // returns `false`
* ```
*
* @see
* - {@link check.isNotUndefined} : the opposite check.
*/
isUndefined<Actual>(this: void, actual: Actual): actual is NarrowToActual<Actual, undefined>;
/**
* Checks that a value is _not_ an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotArray([]); // returns `false`
* check.isNotArray({length: 4}); // returns `true`
* ```
*
* @see
* - {@link check.isArray} : the opposite check.
*/
isNotArray<Actual>(this: void, actual: Actual): actual is Exclude<Actual, ReadonlyArray<unknown>>;
/**
* Checks that a value is _not_ a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotBigInt(123n); // returns `false`
* check.isNotBigInt(123); // returns `true`
* ```
*
* @see
* - {@link check.isBigInt} : the opposite check.
*/
isNotBigInt<Actual>(this: void, actual: Actual): actual is Exclude<Actual, bigint>;
/**
* Checks that a value is _not_ a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotBoolean(true); // returns `false`
* check.isNotBoolean('true'); // returns `true`
* ```
*
* @see
* - {@link check.isBoolean} : the opposite check.
*/
isNotBoolean<Actual>(this: void, actual: Actual): actual is Exclude<Actual, boolean>;
/**
* Checks that a value is _not_ a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotFunction(() => {}); // returns `false`
* check.isNotFunction({}); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotFunction<Actual>(this: void, actual: Actual): actual is Exclude<Actual, AnyFunction>;
/**
* Checks that a value is _not_ exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotNull(null); // returns `false`
* check.isNotNull(undefined); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotNull<Actual>(this: void, actual: Actual): actual is Exclude<Actual, null>;
/**
* Checks that a value is _not_ a number. This includes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotNumber(123); // returns `false`
* check.isNotNumber(123n); // returns `true`
* ```
*
* @see
* - {@link check.isNumber} : the opposite check.
*/
isNotNumber<Actual>(this: void, actual: Actual): actual is Exclude<Actual, number>;
/**
* Checks that a value is _not_ an object. This includes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotObject({}); // returns `false`
* check.isNotObject([]); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotObject<Actual>(this: void, actual: Actual): actual is Exclude<Actual, UnknownObject>;
/**
* Checks that a value is not a plain object. This includes arrays and class instances.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* check.isNotPlainObject({}); // returns `false`
* check.isNotPlainObject({value: 'key'}); // returns `false`
* check.isNotPlainObject(null); // returns `true`
* check.isNotPlainObject(new RegExp()); // returns `true`
* check.isNotPlainObject(new Date()); // returns `true`
* ```
*
* @see
* - {@link check.isPlainObject} : the opposite check.
* - {@link check.isNotObject} : a more generic non-object check.
*/
isNotPlainObject(this: void, actual: unknown): boolean;
/**
* Checks that a value is _not_ a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotString(''); // returns `false`
* check.isNotString(5); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotString<Actual>(this: void, actual: Actual): actual is Exclude<Actual, string>;
/**
* Checks that a value is _not_ a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotSymbol(Symbol('my-symbol')); // returns `false`
* check.isNotSymbol('my-symbol'); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotSymbol<Actual>(this: void, actual: Actual): actual is Exclude<Actual, symbol>;
/**
* Checks that a value is _not_ exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotUndefined(undefined); // returns `false`
* check.isNotUndefined(null); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotUndefined<Actual>(this: void, actual: Actual): actual is Exclude<Actual, undefined>;
};
assertWrap: {
/**
* Asserts that a value is an array. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isArray([]); // returns `[]`
* assertWrap.isArray({length: 4}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotArray} : the opposite assertion.
*/
isArray<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): ArrayNarrow<Actual>;
/**
* Asserts that a value is a BigInt. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isBigInt(123n); // returns `123n`
* assertWrap.isBigInt(123); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotBigInt} : the opposite assertion.
*/
isBigInt<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, bigint>;
/**
* Asserts that a value is a boolean. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isBoolean(true); // returns `true`
* assertWrap.isBoolean('true'); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotBoolean} : the opposite assertion.
*/
isBoolean<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, boolean>;
/**
* Asserts that a value is a function. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isFunction(() => {}); // returns `() => {}`
* assertWrap.isFunction({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotFunction} : the opposite assertion.
*/
isFunction<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToActual<Actual, AnyFunction>;
/**
* Asserts that a value is exactly `null. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNull(null); // returns `null`
* assertWrap.isNull(undefined); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotNull} : the opposite assertion.
*/
isNull<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, null>;
/**
* Asserts that a value is a number. This excludes `NaN. Returns the value if the assertion
* passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNumber(123); // returns `123`
* assertWrap.isNumber(123n); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotNumber} : the opposite assertion.
*/
isNumber<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, number>;
/**
* Asserts that a value is an object. This excludes arrays. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isObject({}); // returns `{}`
* assertWrap.isObject([]); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotObject} : the opposite assertion.
*/
isObject<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, UnknownObject>;
/**
* Asserts that a value is a plain object. This excludes arrays and class instances. Returns
* the value if the assertion passes.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPlainObject({}); // returns `{}`
* assertWrap.isPlainObject({value: 'key'}); // returns `{value: 'key'}`
* assertWrap.isPlainObject(null); // throws an error
* assertWrap.isPlainObject(new RegExp()); // throws an error
* assertWrap.isPlainObject(new Date()); // throws an error
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotPlainObject} : the opposite assertion.
* - {@link assertWrap.isObject} : a more generic object assertion.
*/
isPlainObject<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, UnknownObject>;
/**
* Asserts that a value is a string. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isString(''); // returns `''`
* assertWrap.isString(5); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotString} : the opposite assertion.
*/
isString<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, string>;
/**
* Trying to assign a unique symbol to another variable kills the `unique` part of the
* symbol. this seems to be a bug with TypeScript itself.
*
* For some reason `checkWrap` does not suffer from this issue though.
*
* @example Const mySymbol = Symbol('mine'); const mySymbol2 = mySymbol; // this is no
* longer `unique symbol`
*/
/**
* Asserts that a value is a symbol. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isSymbol(Symbol('my-symbol')); // returns the created symbol
* assertWrap.isSymbol('my-symbol'); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotSymbol} : the opposite assertion.
*/
isSymbol<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, symbol>;
/**
* Asserts that a value is exactly `undefined. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isUndefined(undefined); // returns `undefined`
* assertWrap.isUndefined(null); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotUndefined} : the opposite assertion.
*/
isUndefined<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): NarrowToExpected<Actual, undefined>;
/**
* Asserts that a value is _not_ an array. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotArray([]); // throws an error
* assertWrap.isNotArray({length: 4}); // returns `{length: 4}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isArray} : the opposite assertion.
*/
isNotArray<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, ReadonlyArray<unknown>>;
/**
* Asserts that a value is _not_ a BigInt. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotBigInt(123n); // throws an error
* assertWrap.isNotBigInt(123); // returns `123`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isBigInt} : the opposite assertion.
*/
isNotBigInt<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, bigint>;
/**
* Asserts that a value is _not_ a boolean. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotBoolean(true); // throws an error
* assertWrap.isNotBoolean('true'); // returns `'true'`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isBoolean} : the opposite assertion.
*/
isNotBoolean<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, boolean>;
/**
* Asserts that a value is _not_ a function. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotFunction(() => {}); // throws an error
* assertWrap.isNotFunction({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotFunction<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, AnyFunction>;
/**
* Asserts that a value is _not_ exactly `null. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotNull(null); // throws an error
* assertWrap.isNotNull(undefined); // returns `undefined`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed. @see
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotNull<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, null>;
/**
* Asserts that a value is _not_ a number. This includes `NaN. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotNumber(123); // throws an error
* assertWrap.isNotNumber(123n); // returns `123n`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNumber} : the opposite assertion.
*/
isNotNumber<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, number>;
/**
* Asserts that a value is _not_ an object. This includes arrays. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotObject({}); // throws an error
* assertWrap.isNotObject([]); // returns `[]`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotObject<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, UnknownObject>;
/**
* Asserts that a value is a not plain object. This includes arrays and class instances.
* Returns the value if the assertion passes.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotPlainObject({}); // throws an error
* assertWrap.isNotPlainObject({value: 'key'}); // throws an error
* assertWrap.isNotPlainObject(null); // returns `null`
* assertWrap.isNotPlainObject(new RegExp()); // returns the RegExp instance
* assertWrap.isNotPlainObject(new Date()); // returns the Date instance
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isPlainObject} : the opposite assertion.
* - {@link assertWrap.isObject} : a more generic non-object assertion.
*/
isNotPlainObject(this: void, actual: unknown, failureMessage?: string | undefined): unknown;
/**
* Asserts that a value is _not_ a string. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotString(''); // throws an error
* assertWrap.isNotString(5); // returns `5`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotString<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, string>;
/**
* Asserts that a value is _not_ a symbol. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotSymbol(Symbol('my-symbol')); // throws an error
* assertWrap.isNotSymbol('my-symbol'); // returns `'my-symbol'`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotSymbol<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, symbol>;
/**
* Asserts that a value is _not_ exactly `undefined. Returns the value if the assertion
* passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotUndefined(undefined); // throws an error
* assertWrap.isNotUndefined(null); // returns `null`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotUndefined<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, undefined>;
};
checkWrap: {
/**
* Checks that a value is an array. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isArray([]); // returns `[]`
* checkWrap.isArray({length: 4}); // returns `undefined`
* ```
*
* @returns The value if the check passes. Otherwise, `undefined`.
* @see
* - {@link checkWrap.isNotArray} : the opposite check.
*/
isArray<Actual>(this: void, actual: Actual): ArrayNarrow<Actual> | undefined;
/**
* Checks that a value is a BigInt. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isBigInt(123n); // returns `123n`
* checkWrap.isBigInt(123); // returns `undefined`
* ```
*
* @returns The value if the check passes. Otherwise, `undefined`.
* @see
* - {@link checkWrap.isNotBigInt} : the opposite check.
*/
isBigInt<Actual>(this: void, actual: Actual): NarrowToActual<Actual, bigint> | undefined;
/**
* Checks that a value is a boolean. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isBoolean(true); // returns `true`
* checkWrap.isBoolean('true'); // returns `undefined`
* ```
*
* @returns The value if the check passes. Otherwise, `undefined`.
* @see
* - {@link checkWrap.isNotBoolean} : the opposite check.
*/
isBoolean<Actual>(this: void, actual: Actual): NarrowToActual<Actual, boolean> | undefined;
/**
* Checks that a value is a function. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isFunction(() => {}); // returns `() => {}`
* checkWrap.isFunction({}); // returns `undefined`
* ```
*
* @returns The value if the check passes. Otherwise, `undefined`.
* @see
* - {@link checkWrap.isNotFunction} : the opposite check.
*/
isFunction<Actual>(this: void, actual: Actual): NarrowToActual<Actual, AnyFunction> | undefined;
/**
* Checks that a value is exactly `null. Returns the value if the check passes, otherwise
* `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isNull(null); // returns `null`
* checkWrap.isNull(undefined); // returns `undefined`
* ```
*
* @returns The value if the check passes. Otherwise, `undefined`.
* @see
* - {@link checkWrap.isNotNull