@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
455 lines (454 loc) • 18.3 kB
TypeScript
import { type MaybePromise } from '@augment-vir/core';
import { type Primitive } from 'type-fest';
import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
export { type Primitive } from 'type-fest';
export declare const primitiveGuards: {
assert: {
/**
* Asserts that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPropertyKey('key'); // passes
* assert.isPropertyKey(true); // fails
* assert.isPropertyKey({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isNotPropertyKey} : the opposite assertion.
*/
isPropertyKey(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is PropertyKey;
/**
* Asserts that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript
* type which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotPropertyKey('key'); // fails
* assert.isNotPropertyKey(true); // passes
* assert.isNotPropertyKey({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, PropertyKey>;
/**
* Asserts that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPrimitive('key'); // passes
* assert.isPrimitive(true); // passes
* assert.isPrimitive({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isNotPrimitive} : the opposite assertion.
*/
isPrimitive(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is Primitive;
/**
* Asserts that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPrimitive('key'); // fails
* assert.isPrimitive(true); // fails
* assert.isPrimitive({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isPrimitive} : the opposite assertion.
*/
isNotPrimitive<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Primitive>;
};
check: {
/**
* Checks that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotPrimitive('key'); // returns `false`
* check.isNotPrimitive(true); // returns `false`
* check.isNotPrimitive({}); // returns `true`
* ```
*
* @see
* - {@link check.isPrimitive} : the opposite check.
*/
isNotPrimitive<Actual>(this: void, actual: Actual): actual is Exclude<Actual, Primitive>;
/**
* Checks that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotPropertyKey('key'); // returns `false`
* check.isNotPropertyKey(true); // returns `true`
* check.isNotPropertyKey({}); // returns `true`
* ```
*
* @see
* - {@link check.isPropertyKey} : the opposite check.
*/
isNotPropertyKey<Actual>(this: void, actual: Actual): actual is Exclude<Actual, PropertyKey>;
/**
* Checks that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPrimitive('key'); // returns `true`
* check.isPrimitive(true); // returns `true`
* check.isPrimitive({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotPrimitive} : the opposite check.
*/
isPrimitive(this: void, actual: unknown): actual is Primitive;
/**
* Checks that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPropertyKey('key'); // returns `true`
* check.isPropertyKey(true); // returns `false`
* check.isPropertyKey({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotPropertyKey} : the opposite check.
*/
isPropertyKey<Actual>(this: void, actual: Actual): actual is Extract<PropertyKey, Actual>;
};
assertWrap: {
/**
* Asserts that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript
* type which refers to all possible key types for a JavaScript object. Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPropertyKey('key'); // returns `'key'`
* assertWrap.isPropertyKey(true); // throws an error
* assertWrap.isPropertyKey({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isNotPropertyKey} : the opposite assertion.
*/
isNotPrimitive<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, Primitive>;
/**
* Asserts that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object. Returns
* the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotPropertyKey('key'); // throws an error
* assertWrap.isNotPropertyKey(true); // returns `true`
* assertWrap.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, PropertyKey>;
/**
* Asserts that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPrimitive('key'); // returns `'key'`
* assertWrap.isPrimitive(true); // returns `true`
* assertWrap.isPrimitive({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isNotPrimitive} : the opposite assertion.
*/
isPrimitive<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Extract<Actual, Primitive>;
/**
* Asserts that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPrimitive('key'); // throws an error
* assertWrap.isPrimitive(true); // throws an error
* assertWrap.isPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isPrimitive} : the opposite assertion.
*/
isPropertyKey<Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Extract<Actual, PropertyKey>;
};
checkWrap: {
/**
* Checks that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object. Returns the value if the
* check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isNotPrimitive('key'); // returns `undefined`
* checkWrap.isNotPrimitive(true); // returns `undefined`
* checkWrap.isNotPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPrimitive} : the opposite check.
*/
isNotPrimitive<Actual>(this: void, actual: Actual): Exclude<Actual, Primitive> | undefined;
/**
* Checks that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object. Returns
* the value if the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isNotPropertyKey('key'); // returns `undefined`
* checkWrap.isNotPropertyKey(true); // returns `true`
* checkWrap.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPropertyKey} : the opposite check.
*/
isNotPropertyKey<Actual>(this: void, actual: Actual): Exclude<Actual, PropertyKey> | undefined;
/**
* Checks that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isPrimitive('key'); // returns `'key'`
* checkWrap.isPrimitive(true); // returns `true`
* checkWrap.isPrimitive({}); // returns `undefined`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isNotPrimitive} : the opposite check.
*/
isPrimitive<Actual>(this: void, actual: Actual): Extract<Actual, Primitive> | undefined;
/**
* Checks that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isPrimitive('key'); // returns `undefined`
* checkWrap.isPrimitive(true); // returns `undefined`
* checkWrap.isPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPrimitive} : the opposite check.
*/
isPropertyKey<Actual>(this: void, actual: Actual): Extract<PropertyKey, Actual> | undefined;
};
waitUntil: {
/**
* Repeatedly calls a callback until its output is a valid `PropertyKey`. `PropertyKey` is a
* built-in TypeScript type which refers to all possible key types for a JavaScript object.
* 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.isPropertyKey('key'); // returns `'key'`
* await waitUntil.isPropertyKey(true); // throws an error
* await waitUntil.isPropertyKey({}); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isNotPropertyKey} : the opposite assertion.
*/
isNotPrimitive: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Primitive>>;
/**
* Repeatedly calls a callback until its output is _not_ a valid `PropertyKey`.
* `PropertyKey` is a built-in TypeScript type which refers to all possible key types for a
* JavaScript object. 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.isNotPropertyKey('key'); // throws an error
* await waitUntil.isNotPropertyKey(true); // returns `true`
* await waitUntil.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, PropertyKey>>;
/**
* Repeatedly calls a callback until its output is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). 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.isPrimitive('key'); // returns `'key'`
* await waitUntil.isPrimitive(true); // returns `true`
* await waitUntil.isPrimitive({}); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isNotPrimitive} : the opposite assertion.
*/
isPrimitive: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Extract<Actual, Primitive>>;
/**
* Repeatedly calls a callback until its output is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). 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.isPrimitive('key'); // throws an error
* await waitUntil.isPrimitive(true); // throws an error
* await waitUntil.isPrimitive({}); // returns `{}`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isPrimitive} : the opposite assertion.
*/
isPropertyKey: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Extract<Actual, PropertyKey>>;
};
};