@augment-vir/assert 30.8.4 → 31.0.1

package/dist/assertions/length.js

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { getObjectTypedKeys, } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard } from '../guard-types/guard-override.js';
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
 function isLengthAtLeast(actual, length, failureMessage) {
     const actualLength = Array.isArray(actual) || typeof actual === 'string'
         ? actual.length
@@ -44,7 +44,45 @@ function waitUntilIsLengthExactly(length, callback, options, failureMessage) {
 }
 /* node:coverage enable */
 const assertions = {
+    /**
+     * Asserts 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 {assert} from '@augment-vir/assert';
+     *
+     * assert.isLengthAtLeast(['a', 'b', 'c'], 2); // passes
+     * assert.isLengthAtLeast(['a', 'b', 'c'], 3); // passes
+     * assert.isLengthAtLeast(['a', 'b'], 3); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is less than the given length.
+     * @see
+     * - {@link assert.isLengthExactly} : the more exact assertion.
+     */
     isLengthAtLeast,
+    /**
+     * Asserts 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 {assert} from '@augment-vir/assert';
+     *
+     * assert.isLengthExactly(['a', 'b', 'c'], 2); // fails
+     * assert.isLengthExactly(['a', 'b', 'c'], 3); // passes
+     * assert.isLengthExactly(['a', 'b'], 3); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is not exactly the given length.
+     * @see
+     * - {@link assert.isLengthAtLeast} : the more flexible assertion.
+     */
     isLengthExactly,
 };
 export const lengthGuards = {
@@ -60,35 +98,20 @@ export const lengthGuards = {
          * ```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`
+         * 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(),
+        isLengthAtLeast: ((actual, length) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            return actualLength >= length;
+        }),
         /**
          * Checks that an array or string has exactly the given length.
          *
@@ -99,35 +122,20 @@ export const lengthGuards = {
          * ```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
+         * 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(),
+        isLengthExactly: ((actual, length) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            return actualLength === length;
+        }),
     },
     assertWrap: {
         /**
@@ -141,29 +149,9 @@ export const lengthGuards = {
          * ```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
+         * 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.
@@ -171,7 +159,15 @@ export const lengthGuards = {
          * @see
          * - {@link assertWrap.isLengthExactly} : the more exact assertion.
          */
-        isLengthAtLeast: autoGuard(),
+        isLengthAtLeast: ((actual, length, failureMessage) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            if (actualLength < length) {
+                throw new AssertionError(`Length '${actual.length}' is not at least '${length}'.`, failureMessage);
+            }
+            return actual;
+        }),
         /**
          * Asserts that an array or string has exactly the given length. Returns the value if the
          * assertion passes.
@@ -183,29 +179,9 @@ export const lengthGuards = {
          * ```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
+         * 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.
@@ -213,7 +189,15 @@ export const lengthGuards = {
          * @see
          * - {@link assertWrap.isLengthAtLeast} : the more flexible assertion.
          */
-        isLengthExactly: autoGuard(),
+        isLengthExactly: ((actual, length, failureMessage) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            if (actualLength !== length) {
+                throw new AssertionError(`Length '${actual.length}' is not exactly '${length}'.`, failureMessage);
+            }
+            return actual;
+        }),
     },
     checkWrap: {
         /**
@@ -227,36 +211,26 @@ export const lengthGuards = {
          * ```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`
+         * 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(),
+        isLengthAtLeast: ((actual, length) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            if (actualLength >= length) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        }),
         /**
          * Checks that an array or string has exactly the given length. Returns the value if the
          * check passes, otherwise `undefined`.
@@ -268,36 +242,26 @@ export const lengthGuards = {
          * ```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`
+         * 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(),
+        isLengthExactly: ((actual, length) => {
+            const actualLength = Array.isArray(actual) || typeof actual === 'string'
+                ? actual.length
+                : getObjectTypedKeys(actual).length;
+            if (actualLength === length) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        }),
     },
     waitUntil: {
         /**
@@ -312,20 +276,9 @@ export const lengthGuards = {
          * ```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
+         * 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.
@@ -333,7 +286,7 @@ export const lengthGuards = {
          * @see
          * - {@link waitUntil.isLengthExactly} : the more exact assertion.
          */
-        isLengthAtLeast: autoGuard(),
+        isLengthAtLeast: createWaitUntil(assertions.isLengthAtLeast),
         /**
          * 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,
@@ -346,20 +299,9 @@ export const lengthGuards = {
          * ```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
+         * 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.
@@ -367,6 +309,6 @@ export const lengthGuards = {
          * @see
          * - {@link waitUntil.isLengthAtLeast} : the more flexible assertion.
          */
-        isLengthExactly: autoGuard(),
+        isLengthExactly: createWaitUntil(assertions.isLengthExactly),
     },
 };

package/dist/assertions/nullish.d.ts

@@ -1,16 +1,5 @@
 import { type MaybePromise } from '@augment-vir/core';
-import { autoGuardSymbol } from '../guard-types/guard-override.js';
 import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
-declare function isDefined<const Actual>(
-/** The value to check. */
-input: Actual, 
-/** Message to include in error message if this assertion fails. */
-failureMessage?: string | undefined): asserts input is Exclude<Actual, undefined | null>;
-declare function isNullish(
-/** The value to check. */
-input: unknown, 
-/** Message to include in error message if this assertion fails. */
-failureMessage?: string | undefined): asserts input is null | undefined;
 export declare const nullishGuards: {
     assert: {
         /**
@@ -33,7 +22,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link assert.isNullish} : the opposite assertion.
          */
-        isDefined: typeof isDefined;
+        isDefined<const Actual>(this: void, input: Actual, failureMessage?: string | undefined): asserts input is Exclude<Actual, undefined | null>;
         /**
          * Asserts that a value is nullish (`null` or `undefined`).
          *
@@ -54,7 +43,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link assert.isDefined} : the opposite assertion.
          */
-        isNullish: typeof isNullish;
+        isNullish(this: void, input: unknown, failureMessage?: string | undefined): asserts input is null | undefined;
     };
     check: {
         /**
@@ -76,7 +65,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link check.isNullish} : the opposite check.
          */
-        isDefined: <Actual>(input: Actual) => input is Exclude<Actual, undefined | null>;
+        isDefined<Actual>(this: void, input: Actual): input is Exclude<Actual, undefined | null>;
         /**
          * Checks that a value is nullish (`null` or `undefined`).
          *
@@ -96,7 +85,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link check.isDefined} : the opposite check.
          */
-        isNullish: typeof autoGuardSymbol;
+        isNullish(this: void, input: unknown): input is null | undefined;
     };
     assertWrap: {
         /**
@@ -121,7 +110,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link assertWrap.isNullish} : the opposite assertion.
          */
-        isDefined: <Actual>(input: Actual, failureMessage?: string | undefined) => Exclude<Actual, undefined | null>;
+        isDefined<Actual>(this: void, 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.
@@ -144,7 +133,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link assertWrap.isDefined} : the opposite assertion.
          */
-        isNullish: typeof autoGuardSymbol;
+        isNullish<Actual>(this: void, input: Actual, failureMessage?: string | undefined): Extract<Actual, undefined | null>;
     };
     /** Nullish checks don't make any sense on `checkWrap`. */
     checkWrap: {
@@ -175,7 +164,7 @@ export declare const nullishGuards: {
          * @see
          * - {@link waitUntil.isNullish} : the opposite assertion.
          */
-        isDefined: <Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, undefined | null>>;
+        isDefined: <Actual>(this: void, 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,
@@ -199,7 +188,6 @@ export declare const nullishGuards: {
          * @see
          * - {@link waitUntil.isDefined} : the opposite assertion.
          */
-        isNullish: typeof autoGuardSymbol;
+        isNullish: <Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Extract<Actual, undefined | null>>;
     };
 };
-export {};

package/dist/assertions/nullish.js

@@ -1,27 +1,65 @@
 import { stringify } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard, autoGuardSymbol } from '../guard-types/guard-override.js';
-function isDefined(
-/** The value to check. */
-input, 
-/** Message to include in error message if this assertion fails. */
-failureMessage) {
-    if (input == undefined) {
-        throw new AssertionError(`'${stringify(input)}' is not defined.`, failureMessage);
-    }
-}
-function isNullish(
-/** The value to check. */
-input, 
-/** Message to include in error message if this assertion fails. */
-failureMessage) {
-    if (input != undefined) {
-        throw new AssertionError(`'${stringify(input)}' is not a nullish.`, failureMessage);
-    }
-}
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
 const assertions = {
-    isDefined,
-    isNullish,
+    /**
+     * 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(
+    /** The value to check. */
+    input, 
+    /** Message to include in error message if this assertion fails. */
+    failureMessage) {
+        if (input == undefined) {
+            throw new AssertionError(`'${stringify(input)}' is not defined.`, failureMessage);
+        }
+    },
+    /**
+     * 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(
+    /** The value to check. */
+    input, 
+    /** Message to include in error message if this assertion fails. */
+    failureMessage) {
+        if (input != undefined) {
+            throw new AssertionError(`'${stringify(input)}' is not a nullish.`, failureMessage);
+        }
+    },
 };
 export const nullishGuards = {
     assert: assertions,
@@ -45,7 +83,9 @@ export const nullishGuards = {
          * @see
          * - {@link check.isNullish} : the opposite check.
          */
-        isDefined: autoGuard(),
+        isDefined(input) {
+            return input != undefined;
+        },
         /**
          * Checks that a value is nullish (`null` or `undefined`).
          *
@@ -65,7 +105,11 @@ export const nullishGuards = {
          * @see
          * - {@link check.isDefined} : the opposite check.
          */
-        isNullish: autoGuardSymbol,
+        isNullish(
+        /** The value to check. */
+        input) {
+            return input == undefined;
+        },
     },
     assertWrap: {
         /**
@@ -90,7 +134,14 @@ export const nullishGuards = {
          * @see
          * - {@link assertWrap.isNullish} : the opposite assertion.
          */
-        isDefined: autoGuard(),
+        isDefined(input, failureMessage) {
+            if (input == undefined) {
+                throw new AssertionError(`'${stringify(input)}' is not defined.`, failureMessage);
+            }
+            else {
+                return input;
+            }
+        },
         /**
          * Asserts that a value is nullish (`null` or `undefined`). Returns the value if the
          * assertion passes.
@@ -113,7 +164,14 @@ export const nullishGuards = {
          * @see
          * - {@link assertWrap.isDefined} : the opposite assertion.
          */
-        isNullish: autoGuardSymbol,
+        isNullish(input, failureMessage) {
+            if (input == undefined) {
+                return input;
+            }
+            else {
+                throw new AssertionError(`'${stringify(input)}' is not nullish.`, failureMessage);
+            }
+        },
     },
     /** Nullish checks don't make any sense on `checkWrap`. */
     checkWrap: {
@@ -144,7 +202,7 @@ export const nullishGuards = {
          * @see
          * - {@link waitUntil.isNullish} : the opposite assertion.
          */
-        isDefined: autoGuard(),
+        isDefined: createWaitUntil(assertions.isDefined),
         /**
          * 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,
@@ -168,6 +226,6 @@ export const nullishGuards = {
          * @see
          * - {@link waitUntil.isDefined} : the opposite assertion.
          */
-        isNullish: autoGuardSymbol,
+        isNullish: createWaitUntil(assertions.isNullish),
     },
 };