@augment-vir/assert 30.0.0 → 30.0.2

package/dist/assertions/boolean.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';
 function isFalsy(input, failureMessage) {
     if (input) {
         throw new AssertionError(`'${stringify(input)}' is not truthy.`, failureMessage);
@@ -22,26 +22,383 @@ function isFalse(input, failureMessage) {
     }
 }
 const assertions = {
+    isFalse,
     isFalsy,
-    isTruthy,
     isTrue,
-    isFalse,
+    isTruthy,
 };
 export const booleanGuards = {
-    assertions,
-    checkOverrides: {
+    assert: assertions,
+    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: 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: 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: 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: autoGuard(),
     },
-    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: 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: autoGuard(),
+        /**
+         * 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: 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: autoGuard(),
     },
-    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: 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: autoGuard(),
+        /**
+         * 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: 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: autoGuard(),
     },
-    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: 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: autoGuard(),
+        /**
+         * 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: 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: autoGuard(),
     },
 };