@augment-vir/assert 30.0.0 → 30.0.2

package/dist/assertions/promise.js

@@ -1,6 +1,6 @@
 import { stringify } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard } from '../guard-types/guard-override.js';
+import { autoGuard, autoGuardSymbol } from '../guard-types/guard-override.js';
 import { createWaitUntil } from '../guard-types/wait-until-function.js';
 function isPromiseLike(actual, failureMessage) {
     if (!(actual instanceof Promise) &&
@@ -41,29 +41,550 @@ const assertions = {
     isNotPromise,
 };
 export const promiseGuards = {
-    assertions,
-    checkOverrides: {
-        isNotPromise: autoGuard(),
+    assert: assertions,
+    check: {
+        /**
+         * Checks that a value is a `PromiseLike`.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * check.isPromiseLike(Promise.resolve(5)); // returns `true`
+         * check.isPromiseLike(new CustomThenable(5)); // returns `true`
+         * check.isPromiseLike(5); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isNotPromiseLike} : the opposite check.
+         * - {@link check.isPromise} : the more precise check.
+         */
+        isPromiseLike: autoGuardSymbol,
+        /**
+         * Checks that a value is _not_ a `PromiseLike`.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * check.isNotPromiseLike(Promise.resolve(5)); // returns `false`
+         * check.isNotPromiseLike(new CustomThenable(5)); // returns `false`
+         * check.isNotPromiseLike(5); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link check.isPromiseLike} : the opposite check.
+         * - {@link check.isNotPromise} : the more precise check.
+         */
         isNotPromiseLike: autoGuard(),
-    },
-    assertWrapOverrides: {
-        isPromise: autoGuard(),
+        /**
+         * Checks that a value is a `Promise` instance.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * check.isPromise(Promise.resolve(5)); // returns `true`
+         * check.isPromise(new CustomThenable(5)); // returns `false`
+         * check.isPromise(5); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isNotPromise} : the opposite check.
+         * - {@link check.isPromiseLike} : the more lenient check.
+         */
+        isPromise: autoGuardSymbol,
+        /**
+         * Checks that a value is a _not_ `Promise` instance.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * check.isNotPromise(Promise.resolve(5)); // returns `false`
+         * check.isNotPromise(new CustomThenable(5)); // returns `true`
+         * check.isNotPromise(5); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link check.isPromise} : the opposite check.
+         * - {@link check.isNotPromiseLike} : the more lenient check.
+         */
         isNotPromise: autoGuard(),
+    },
+    assertWrap: {
+        /**
+         * Asserts that a value is a `PromiseLike`. Returns the value if the assertion passes.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * assertWrap.isPromiseLike(Promise.resolve(5)); // returns the `Promise` instance
+         * assertWrap.isPromiseLike(new CustomThenable(5)); // returns the `CustomThenable` instance
+         * assertWrap.isPromiseLike(5); // throws an error
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isNotPromiseLike} : the opposite assertion.
+         * - {@link assertWrap.isPromise} : the more precise assertion.
+         */
         isPromiseLike: autoGuard(),
+        /**
+         * Asserts that a value is _not_ a `PromiseLike`. Returns the value if the assertion passes.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * assertWrap.isNotPromiseLike(Promise.resolve(5)); // throws an error
+         * assertWrap.isNotPromiseLike(new CustomThenable(5)); // throws an error
+         * assertWrap.isNotPromiseLike(5); // returns `5`
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isPromiseLike} : the opposite assertion.
+         * - {@link assertWrap.isNotPromise} : the more precise assertion.
+         */
         isNotPromiseLike: autoGuard(),
+        /**
+         * Asserts that a value is a `Promise` instance. Returns the value if the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * assertWrap.isPromise(Promise.resolve(5)); // returns the `Promise` instance
+         * assertWrap.isPromise(new CustomThenable(5)); // throws an error
+         * assertWrap.isPromise(5); // throws an error
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isNotPromise} : the opposite assertion.
+         * - {@link assertWrap.isPromiseLike} : the more lenient assertion.
+         */
+        isPromise: autoGuard(),
+        /**
+         * Asserts that a value is a _not_ `Promise` instance. Returns the value if the assertion
+         * passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * assertWrap.isNotPromise(Promise.resolve(5)); // throws an error
+         * assertWrap.isNotPromise(new CustomThenable(5)); // returns the `CustomThenable` promise
+         * assertWrap.isNotPromise(5); // returns `5`
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isPromise} : the opposite assertion.
+         * - {@link assertWrap.isNotPromiseLike} : the more lenient assertion.
+         */
+        isNotPromise: autoGuard(),
     },
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that a value is a `PromiseLike`. Returns the value if the check passes, otherwise
+         * `undefined`.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * checkWrap.isPromiseLike(Promise.resolve(5)); // returns `true`
+         * checkWrap.isPromiseLike(new CustomThenable(5)); // returns `true`
+         * checkWrap.isPromiseLike(5); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isNotPromiseLike} : the opposite check.
+         * - {@link checkWrap.isPromise} : the more precise check.
+         */
         isNotPromise: autoGuard(),
+        /**
+         * Checks that a value is _not_ a `PromiseLike`. Returns the value if the check passes,
+         * otherwise `undefined`.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * checkWrap.isNotPromiseLike(Promise.resolve(5)); // returns `false`
+         * checkWrap.isNotPromiseLike(new CustomThenable(5)); // returns `false`
+         * checkWrap.isNotPromiseLike(5); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isPromiseLike} : the opposite check.
+         * - {@link checkWrap.isNotPromise} : the more precise check.
+         */
         isNotPromiseLike: autoGuard(),
+        /**
+         * Checks that a value is a `Promise` instance. Returns the value if the check passes,
+         * otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * checkWrap.isPromise(Promise.resolve(5)); // returns `true`
+         * checkWrap.isPromise(new CustomThenable(5)); // returns `false`
+         * checkWrap.isPromise(5); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isNotPromise} : the opposite check.
+         * - {@link checkWrap.isPromiseLike} : the more lenient check.
+         */
+        isPromise: autoGuardSymbol,
+        /**
+         * Checks that a value is a _not_ `Promise` instance. Returns the value if the check passes,
+         * otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * checkWrap.isNotPromise(Promise.resolve(5)); // returns `false`
+         * checkWrap.isNotPromise(new CustomThenable(5)); // returns `true`
+         * checkWrap.isNotPromise(5); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isPromise} : the opposite check.
+         * - {@link checkWrap.isNotPromiseLike} : the more lenient check.
+         */
+        isPromiseLike: autoGuardSymbol,
     },
-    /**
-     * These overrides must explicitly use `createWaitUntil` so they can pass in `true` for the
-     * second parameter, `requireSynchronousResult`.
-     */
-    waitUntilOverrides: {
-        isPromise: createWaitUntil(isPromise, true),
-        isNotPromise: createWaitUntil(isNotPromise, true),
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is a `PromiseLike`. Once the callback output
+         * passes, it is returned. If the attempts time out, an error is thrown.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * await waitUntil.isPromiseLike(() => Promise.resolve(5)); // returns the resolved `5`
+         * await waitUntil.isPromiseLike(() => new CustomThenable(5)); // returns the resolved `5`
+         * await waitUntil.isPromiseLike(() => 5); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link waitUntil.isNotPromiseLike} : the opposite assertion.
+         * - {@link waitUntil.isPromise} : the more precise assertion.
+         */
         isPromiseLike: createWaitUntil(isPromiseLike, true),
+        /**
+         * Repeatedly calls a callback until its output is _not_ a `PromiseLike`. Once the callback
+         * output passes, it is returned. If the attempts time out, an error is thrown.
+         *
+         * `PromiseLike` is TypeScript built-in type that has a `.then` method and thus behaves like
+         * a promise. This is also referred to as a "thenable". This enables the use of third-party
+         * promise implementations that aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * await waitUntil.isNotPromiseLike(() => Promise.resolve(5)); // throws an error
+         * await waitUntil.isNotPromiseLike(() => new CustomThenable(5)); // throws an error
+         * await waitUntil.isNotPromiseLike(() => 5); // returns `5`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link waitUntil.isPromiseLike} : the opposite assertion.
+         * - {@link waitUntil.isNotPromise} : the more precise assertion.
+         */
         isNotPromiseLike: createWaitUntil(isNotPromiseLike, true),
+        /**
+         * Repeatedly calls a callback until its output is a `Promise` instance. 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';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * await waitUntil.isPromise(() => Promise.resolve(5)); // returns the resolved `5`
+         * await waitUntil.isPromise(() => new CustomThenable(5)); // throws an error
+         * await waitUntil.isPromise(() => 5); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link waitUntil.isNotPromise} : the opposite assertion.
+         * - {@link waitUntil.isPromiseLike} : the more lenient assertion.
+         */
+        isPromise: createWaitUntil(isPromise, true),
+        /**
+         * Repeatedly calls a callback until its output is a _not_ `Promise` instance. 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';
+         *
+         * class CustomThenable {
+         *     constructor(public value: any) {}
+         *
+         *     then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
+         *         return new CustomThenable(
+         *             onFulfilled ? onFulfilled(this.value) : this.value,
+         *         );
+         *     }
+         * }
+         *
+         * await waitUntil.isNotPromise(() => Promise.resolve(5)); // throws an error
+         * await waitUntil.isNotPromise(() => new CustomThenable(5)); // returns the resolved `5`
+         * await waitUntil.isNotPromise(() => 5); // returns the resolved `5`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link waitUntil.isPromise} : the opposite assertion.
+         * - {@link waitUntil.isNotPromiseLike} : the more lenient assertion.
+         */
+        isNotPromise: createWaitUntil(isNotPromise, true),
     },
 };