@augment-vir/assert 30.0.0 → 30.0.1

package/dist/assertions/length.js

@@ -48,21 +48,325 @@ const assertions = {
     isLengthExactly,
 };
 export const lengthGuards = {
-    assertions,
-    checkOverrides: {
+    assert: assertions,
+    check: {
+        /**
+         * Checks that an array or string has at least the given length.
+         *
+         * Type guards an array into an {@link AtLeastTuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // returns `true`
+         * check.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // returns `true`
+         * check.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isLengthExactly} : the more exact check.
+         */
         isLengthAtLeast: autoGuard(),
+        /**
+         * Checks that an array or string has exactly the given length.
+         *
+         * Type guards an array into a {@link Tuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // fails
+         * check.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // passes
+         * check.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // fails
+         * ```
+         *
+         * @see
+         * - {@link check.isLengthAtLeast} : the more flexible check.
+         */
         isLengthExactly: autoGuard(),
     },
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that an array or string has at least the given length. Returns the value if the
+         * assertion passes.
+         *
+         * Type guards an array into an {@link AtLeastTuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // returns `['a', 'b', 'c']`
+         * assertWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // returns `['a', 'b', 'c']`
+         * assertWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // throws an error
+         * ```
+         *
+         * @returns The value if it has at least the given length.
+         * @throws {@link AssertionError} If the value is less than the given length.
+         * @see
+         * - {@link assertWrap.isLengthExactly} : the more exact assertion.
+         */
         isLengthAtLeast: autoGuard(),
+        /**
+         * Asserts that an array or string has exactly the given length. Returns the value if the
+         * assertion passes.
+         *
+         * Type guards an array into a {@link Tuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // throws an error
+         * assertWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // returns `['a', 'b', 'c']`
+         * assertWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // throws an error
+         * ```
+         *
+         * @returns The value if it has exactly the given length.
+         * @throws {@link AssertionError} If the value is not exactly the given length.
+         * @see
+         * - {@link assertWrap.isLengthAtLeast} : the more flexible assertion.
+         */
         isLengthExactly: autoGuard(),
     },
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that an array or string has at least the given length. Returns the value if the
+         * check passes, otherwise `undefined`.
+         *
+         * Type guards an array into an {@link AtLeastTuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // returns `['a', 'b', 'c']`
+         * checkWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // returns `['a', 'b', 'c']`
+         * checkWrap.isLengthAtLeast(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the check passes, otherwise `undefined`.
+         * @see
+         * - {@link checkWrap.isLengthExactly} : the more exact check.
+         */
         isLengthAtLeast: autoGuard(),
+        /**
+         * Checks that an array or string has exactly the given length. Returns the value if the
+         * check passes, otherwise `undefined`.
+         *
+         * Type guards an array into a {@link Tuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     2,
+         * ); // returns `undefined`
+         * checkWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *         'c',
+         *     ],
+         *     3,
+         * ); // returns `['a', 'b', 'c']`
+         * checkWrap.isLengthExactly(
+         *     [
+         *         'a',
+         *         'b',
+         *     ],
+         *     3,
+         * ); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the check passes, otherwise `undefined`.
+         * @see
+         * - {@link checkWrap.isLengthAtLeast} : the more flexible check.
+         */
         isLengthExactly: autoGuard(),
     },
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is an array or string that has at least the
+         * given length. Once the callback output passes, it is returned. If the attempts time out,
+         * an error is thrown.
+         *
+         * Type guards an array into an {@link AtLeastTuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.isLengthAtLeast(2, () => [
+         *     'a',
+         *     'b',
+         *     'c',
+         * ]); // returns `['a', 'b', 'c']`
+         * await waitUntil.isLengthAtLeast(3, () => [
+         *     'a',
+         *     'b',
+         *     'c',
+         * ]); // returns `['a', 'b', 'c']`
+         * await waitUntil.isLengthAtLeast(3, () => [
+         *     'a',
+         *     'b',
+         * ]); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isLengthExactly} : the more exact assertion.
+         */
         isLengthAtLeast: autoGuard(),
+        /**
+         * Repeatedly calls a callback until its output is an array or string that has exactly the
+         * given length. Once the callback output passes, it is returned. If the attempts time out,
+         * an error is thrown.
+         *
+         * Type guards an array into a {@link Tuple}. Performs no type guarding on a string.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.isLengthAtLeast(2, () => [
+         *     'a',
+         *     'b',
+         *     'c',
+         * ]); // throws an error
+         * await waitUntil.isLengthAtLeast(3, () => [
+         *     'a',
+         *     'b',
+         *     'c',
+         * ]); // returns `['a', 'b', 'c']`
+         * await waitUntil.isLengthAtLeast(3, () => [
+         *     'a',
+         *     'b',
+         * ]); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isLengthAtLeast} : the more flexible assertion.
+         */
         isLengthExactly: autoGuard(),
     },
 };

package/dist/assertions/nullish.d.ts

@@ -1,4 +1,5 @@
 import { MaybePromise } from '@augment-vir/core';
+import { autoGuardSymbol } from '../guard-types/guard-override.js';
 import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
 declare function isDefined<const Actual>(
 /** The value to check. */
@@ -11,33 +12,194 @@ input: unknown,
 /** Message to include in error message if this assertion fails. */
 failureMessage?: string | undefined): asserts input is null | undefined;
 export declare const nullishGuards: {
-    assertions: {
+    assert: {
         /**
-         * Checks that a value is defined (not `null` and not `undefined`).
+         * Asserts that a value is defined (not `null` and not `undefined`).
          *
          * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.isDefined(0); // passes
+         * assert.isDefined(''); // passes
+         * assert.isDefined(null); // fails
+         * assert.isDefined(undefined); // fails
+         * ```
+         *
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assert.isNullish} : the opposite assertion.
          */
         isDefined: typeof isDefined;
         /**
-         * Checks that a value is nullish (`null` or `undefined`).
+         * Asserts that a value is nullish (`null` or `undefined`).
          *
          * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.isNullish(0); // fails
+         * assert.isNullish(''); // fails
+         * assert.isNullish(null); // passes
+         * assert.isNullish(undefined); // passes
+         * ```
+         *
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assert.isDefined} : the opposite assertion.
          */
         isNullish: typeof isNullish;
     };
-    checkOverrides: {
+    check: {
+        /**
+         * Checks that a value is defined (not `null` and not `undefined`).
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isDefined(0); // returns `true`
+         * check.isDefined(''); // returns `true`
+         * check.isDefined(null); // returns `false`
+         * check.isDefined(undefined); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isNullish} : the opposite check.
+         */
         isDefined: <Actual>(input: Actual) => input is Exclude<Actual, undefined | null>;
+        /**
+         * Checks that a value is nullish (`null` or `undefined`).
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isNullish(0); // returns `false`
+         * check.isNullish(''); // returns `false`
+         * check.isNullish(null); // returns `true`
+         * check.isNullish(undefined); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link check.isDefined} : the opposite check.
+         */
+        isNullish: typeof autoGuardSymbol;
     };
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that a value is defined (not `null` and not `undefined`). Returns the value if
+         * the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isDefined(0); // returns `0`
+         * assertWrap.isDefined(''); // returns `''`
+         * assertWrap.isDefined(null); // fails
+         * assertWrap.isDefined(undefined); // fails
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isNullish} : the opposite assertion.
+         */
         isDefined: <Actual>(input: Actual, failureMessage?: string | undefined) => Exclude<Actual, undefined | null>;
+        /**
+         * Asserts that a value is nullish (`null` or `undefined`). Returns the value if the
+         * assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isNullish(0); // fails
+         * assertWrap.isNullish(''); // fails
+         * assertWrap.isNullish(null); // returns `null`
+         * assertWrap.isNullish(undefined); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isDefined} : the opposite assertion.
+         */
+        isNullish: typeof autoGuardSymbol;
     };
     /** Nullish checks don't make any sense on `checkWrap`. */
-    checkWrapOverrides: {
+    checkWrap: {
         isDefined: undefined;
         isNullish: undefined;
     };
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is a value that is defined (not `null` and
+         * not `undefined`). 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.isDefined(() => 0); // returns `0`
+         * await waitUntil.isDefined(() => ''); // returns `''`
+         * await waitUntil.isDefined(() => null); // throws an error
+         * await waitUntil.isDefined(() => undefined); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isNullish} : the opposite assertion.
+         */
         isDefined: <Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, undefined | null>>;
+        /**
+         * Repeatedly calls a callback until its output is a value that is nullish (`null` or
+         * `undefined`). 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.isNullish(() => 0); // throws an error
+         * await waitUntil.isNullish(() => ''); // throws an error
+         * await waitUntil.isNullish(() => null); // returns `null`
+         * await waitUntil.isNullish(() => undefined); // returns `undefined`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isDefined} : the opposite assertion.
+         */
+        isNullish: typeof autoGuardSymbol;
     };
 };
 export {};

package/dist/assertions/nullish.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 isDefined(
 /** The value to check. */
 input, 
@@ -24,19 +24,150 @@ const assertions = {
     isNullish,
 };
 export const nullishGuards = {
-    assertions: assertions,
-    checkOverrides: {
+    assert: assertions,
+    check: {
+        /**
+         * Checks that a value is defined (not `null` and not `undefined`).
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isDefined(0); // returns `true`
+         * check.isDefined(''); // returns `true`
+         * check.isDefined(null); // returns `false`
+         * check.isDefined(undefined); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isNullish} : the opposite check.
+         */
         isDefined: autoGuard(),
+        /**
+         * Checks that a value is nullish (`null` or `undefined`).
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isNullish(0); // returns `false`
+         * check.isNullish(''); // returns `false`
+         * check.isNullish(null); // returns `true`
+         * check.isNullish(undefined); // returns `true`
+         * ```
+         *
+         * @see
+         * - {@link check.isDefined} : the opposite check.
+         */
+        isNullish: autoGuardSymbol,
     },
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that a value is defined (not `null` and not `undefined`). Returns the value if
+         * the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isDefined(0); // returns `0`
+         * assertWrap.isDefined(''); // returns `''`
+         * assertWrap.isDefined(null); // fails
+         * assertWrap.isDefined(undefined); // fails
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isNullish} : the opposite assertion.
+         */
         isDefined: autoGuard(),
+        /**
+         * Asserts that a value is nullish (`null` or `undefined`). Returns the value if the
+         * assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isNullish(0); // fails
+         * assertWrap.isNullish(''); // fails
+         * assertWrap.isNullish(null); // returns `null`
+         * assertWrap.isNullish(undefined); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         * @see
+         * - {@link assertWrap.isDefined} : the opposite assertion.
+         */
+        isNullish: autoGuardSymbol,
     },
     /** Nullish checks don't make any sense on `checkWrap`. */
-    checkWrapOverrides: {
+    checkWrap: {
         isDefined: undefined,
         isNullish: undefined,
     },
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is a value that is defined (not `null` and
+         * not `undefined`). 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.isDefined(() => 0); // returns `0`
+         * await waitUntil.isDefined(() => ''); // returns `''`
+         * await waitUntil.isDefined(() => null); // throws an error
+         * await waitUntil.isDefined(() => undefined); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isNullish} : the opposite assertion.
+         */
         isDefined: autoGuard(),
+        /**
+         * Repeatedly calls a callback until its output is a value that is nullish (`null` or
+         * `undefined`). 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.isNullish(() => 0); // throws an error
+         * await waitUntil.isNullish(() => ''); // throws an error
+         * await waitUntil.isNullish(() => null); // returns `null`
+         * await waitUntil.isNullish(() => undefined); // returns `undefined`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isDefined} : the opposite assertion.
+         */
+        isNullish: autoGuardSymbol,
     },
 };