@augment-vir/assert 30.0.0 → 30.0.1

package/README.md

@@ -0,0 +1,11 @@
+# @augment-vir/assert
+
+A collection of assertions for test and production code alike. These main exports are the following:
+
+-   [`assert`](https://electrovir.github.io/augment-vir/functions/assert.html): a collection of assertion methods with type guards when possible. Example: [`assert.isDefined()`](https://electrovir.github.io/augment-vir/functions/assert.html#isDefined)
+-   [`check`](https://electrovir.github.io/augment-vir/functions/check.html): a collection of boolean check methods with type guards when possible. Example: [`check.isBoolean()`](https://electrovir.github.io/augment-vir/functions/check.html#isBoolean)
+-   [`assertWrap`](https://electrovir.github.io/augment-vir/functions/assertWrap.html): a collection of assertions that return the asserted value if the assertion passes. Examples [`assertWrap.isArray()`](https://electrovir.github.io/augment-vir/functions/assertWrap.html#isArray)
+-   [`checkWrap`](https://electrovir.github.io/augment-vir/functions/checkWrap.html): a collection of checks that return the checked value if it passes or `undefined`. Example: [`checkWrap.isInfinite()`](https://electrovir.github.io/augment-vir/functions/checkWrap.html#isInfinite)
+-   [`waitUntil`](https://electrovir.github.io/augment-vir/functions/waitUntil.html): a collection of assertion methods that try to wait until the assertion becomes true. Example: [`waitUntil.isTruthy()`](https://electrovir.github.io/augment-vir/functions/waitUntil.html#isTruthy)
+
+See the docs under `Assert`, or `Package: @augment-vir/assert` here: https://electrovir.github.io/augment-vir

package/dist/assertions/boolean.d.ts

@@ -1,10 +1,12 @@
 import { MaybePromise, NarrowToExpected } from '@augment-vir/core';
+import { autoGuardSymbol } from '../guard-types/guard-override.js';
 import { 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
@@ -13,13 +15,14 @@ import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
  * const falsy: FalsyValue = 0;
  * ```
  *
- * @package @augment-vir/assert
+ * @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
@@ -29,12 +32,14 @@ export type FalsyValue = undefined | null | false | 0 | '' | -0 | 0n;
  * ```
  *
  * @param T The original type to narrow.
- * @package @augment-vir/assert
+ * @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
  */
-export type Falsy<T> = NarrowToExpected<T, FalsyValue>; /**
+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
@@ -44,7 +49,7 @@ export type Falsy<T> = NarrowToExpected<T, FalsyValue>; /**
  * ```
  *
  * @param T The original type to narrow.
- * @package @augment-vir/assert
+ * @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
  */
 export type Truthy<T> = Exclude<T, FalsyValue>;
 declare function isFalsy(input: unknown, failureMessage?: string | undefined): asserts input is FalsyValue;
@@ -52,45 +57,466 @@ declare function isTruthy<const Actual>(input: Actual, failureMessage?: string |
 declare function isTrue(input: unknown, failureMessage?: string | undefined): asserts input is true;
 declare function isFalse(input: unknown, failureMessage?: string | undefined): asserts input is false;
 export declare const booleanGuards: {
-    assertions: {
+    assert: {
         /**
-         * Check if a value is falsy.
+         * Asserts that a value is exactly `false`.
          *
-         * Type guards the value when possible.
+         * 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.
          */
-        isFalsy: typeof isFalsy;
+        isFalse: typeof isFalse;
         /**
-         * Check if a value is truthy.
+         * 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.
          */
-        isTruthy: typeof isTruthy;
+        isFalsy: typeof isFalsy;
         /**
-         * Check if a value is `true`.
+         * 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: typeof isTrue;
         /**
-         * Check if a value is `false`.
+         * 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.
          */
-        isFalse: typeof isFalse;
+        isTruthy: typeof isTruthy;
     };
-    checkOverrides: {
+    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: typeof autoGuardSymbol;
+        /**
+         * 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: typeof autoGuardSymbol;
+        /**
+         * 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: typeof autoGuardSymbol;
+        /**
+         * 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>(input: T) => input is Truthy<T>;
     };
-    assertWrapOverrides: {
+    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: typeof autoGuardSymbol;
+        /**
+         * 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>(input: T, failureMessage?: string | undefined) => 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: typeof autoGuardSymbol;
+        /**
+         * 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>(input: T, failureMessage?: string | undefined) => Truthy<T>;
     };
-    checkWrapOverrides: {
+    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: typeof autoGuardSymbol;
+        /**
+         * 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>(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: typeof autoGuardSymbol;
+        /**
+         * 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>(input: T) => Truthy<T> | undefined;
     };
-    waitUntilOverrides: {
+    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: typeof autoGuardSymbol;
+        /**
+         * 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>(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: typeof autoGuardSymbol;
+        /**
+         * 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>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Truthy<Actual>>;
     };
 };