@augment-vir/assert 31.0.0 → 31.0.1

package/dist/assertions/throws.d.ts

@@ -1,7 +1,6 @@
-import { type MaybePromise, type PartialWithNullable, type TypedFunction } from '@augment-vir/core';
-import { autoGuardSymbol } from '../guard-types/guard-override.js';
+import { type MaybePromise, type NarrowToExpected, type PartialWithNullable, type TypedFunction } from '@augment-vir/core';
 import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
-declare function isError(actual: unknown, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): asserts actual is Error;
+declare function isError(this: void, actual: unknown, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): asserts actual is Error;
 /**
  * A type that represents possible error matching patterns. This is used by the `.throws` and
  * `isError`, guards in `@augment-vir/assert` as well as `itCases` in `@augment-vir/test`. Each
@@ -50,24 +49,24 @@ export type ErrorMatchOptions = PartialWithNullable<{
      */
     matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
 }>;
-declare function throws(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
-declare function throws(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<void>;
-declare function throws(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
-declare function throws(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<void>;
-declare function throwsCheck(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined): boolean;
-declare function throwsCheck(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): Promise<boolean>;
-declare function throwsCheck(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined): boolean;
-declare function throwsCheck(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): MaybePromise<boolean>;
-declare function throwsAssertWrap(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
-declare function throwsAssertWrap(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
-declare function throwsAssertWrap(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
-declare function throwsAssertWrap(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error>;
-declare function throwsCheckWrap(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
-declare function throwsCheckWrap(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error | undefined>;
-declare function throwsCheckWrap(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
-declare function throwsCheckWrap(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error | undefined>;
-declare function throwsWaitUntil(callback: TypedFunction<void, any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
-declare function throwsWaitUntil(matchOptions: ErrorMatchOptions, callback: TypedFunction<void, any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+declare function throws(this: void, callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
+declare function throws(this: void, callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<void>;
+declare function throws(this: void, callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
+declare function throws(this: void, callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<void>;
+declare function throwsCheck(this: void, callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined): boolean;
+declare function throwsCheck(this: void, callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): Promise<boolean>;
+declare function throwsCheck(this: void, callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined): boolean;
+declare function throwsCheck(this: void, callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): MaybePromise<boolean>;
+declare function throwsAssertWrap(this: void, callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
+declare function throwsAssertWrap(this: void, callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+declare function throwsAssertWrap(this: void, callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
+declare function throwsAssertWrap(this: void, callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error>;
+declare function throwsCheckWrap(this: void, callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
+declare function throwsCheckWrap(this: void, callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error | undefined>;
+declare function throwsCheckWrap(this: void, callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
+declare function throwsCheckWrap(this: void, callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error | undefined>;
+declare function throwsWaitUntil(this: void, callback: TypedFunction<void, any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+declare function throwsWaitUntil(this: void, matchOptions: ErrorMatchOptions, callback: TypedFunction<void, any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
 export declare const throwGuards: {
     assert: {
         /**
@@ -179,7 +178,7 @@ export declare const throwGuards: {
          * check.isError({message: 'not an error'}); // returns `false`
          * ```
          */
-        isError: typeof autoGuardSymbol;
+        isError(this: void, actual: unknown, matchOptions?: ErrorMatchOptions | undefined): actual is Error;
     };
     assertWrap: {
         /**
@@ -241,7 +240,7 @@ export declare const throwGuards: {
          * @returns The value if the assertion passes.
          * @throws {@link AssertionError} If the assertion fails.
          */
-        isError: typeof autoGuardSymbol;
+        isError<Actual>(this: void, actual: Actual, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): NarrowToExpected<Actual, Error>;
     };
     checkWrap: {
         /**
@@ -296,7 +295,7 @@ export declare const throwGuards: {
          *
          * @returns The Error if the check passes, otherwise `undefined`.
          */
-        isError: typeof autoGuardSymbol;
+        isError<Actual>(this: void, actual: Actual, matchOptions?: ErrorMatchOptions | undefined): NarrowToExpected<Actual, Error> | undefined;
     };
     waitUntil: {
         /**
@@ -351,7 +350,7 @@ export declare const throwGuards: {
          * @returns The callback output once it passes.
          * @throws {@link AssertionError} On timeout.
          */
-        isError: typeof autoGuardSymbol;
+        isError: <Actual>(this: void, matchOptions: ErrorMatchOptions | undefined, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Error>>;
     };
 };
 export {};

package/dist/assertions/throws.js

@@ -1,6 +1,5 @@
 import { ensureError, extractErrorMessage, stringify, } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuardSymbol } from '../guard-types/guard-override.js';
 import { createWaitUntil } from '../guard-types/wait-until-function.js';
 var ThrowsCheckType;
 (function (ThrowsCheckType) {
@@ -45,6 +44,30 @@ function internalAssertError(actual, errorMessages, matchOptions, failureMessage
         }
     }
 }
+function internalCheckError(actual, matchOptions) {
+    if (!actual) {
+        return false;
+    }
+    else if (!(actual instanceof Error)) {
+        return false;
+    }
+    else if (matchOptions?.matchConstructor &&
+        !(actual instanceof matchOptions.matchConstructor)) {
+        return false;
+    }
+    else if (matchOptions?.matchMessage) {
+        const message = extractErrorMessage(actual);
+        if (typeof matchOptions.matchMessage === 'string') {
+            if (!message.includes(matchOptions.matchMessage)) {
+                return false;
+            }
+        }
+        else if (!message.match(matchOptions.matchMessage)) {
+            return false;
+        }
+    }
+    return true;
+}
 function internalThrowsCheck(checkType, callbackOrPromise, matchOptions, failureMessage) {
     let caughtError = undefined;
     try {
@@ -201,7 +224,9 @@ export const throwGuards = {
          * check.isError({message: 'not an error'}); // returns `false`
          * ```
          */
-        isError: autoGuardSymbol,
+        isError(actual, matchOptions) {
+            return internalCheckError(actual, matchOptions);
+        },
     },
     assertWrap: {
         /**
@@ -263,7 +288,13 @@ export const throwGuards = {
          * @returns The value if the assertion passes.
          * @throws {@link AssertionError} If the assertion fails.
          */
-        isError: autoGuardSymbol,
+        isError(actual, matchOptions, failureMessage) {
+            internalAssertError(actual, {
+                noError: 'No error.',
+                notInstance: `'${stringify(actual)}' is not an error instance.`,
+            }, matchOptions, failureMessage);
+            return actual;
+        },
     },
     checkWrap: {
         /**
@@ -318,7 +349,14 @@ export const throwGuards = {
          *
          * @returns The Error if the check passes, otherwise `undefined`.
          */
-        isError: autoGuardSymbol,
+        isError(actual, matchOptions) {
+            if (internalCheckError(actual, matchOptions)) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        },
     },
     waitUntil: {
         /**
@@ -373,6 +411,6 @@ export const throwGuards = {
          * @returns The callback output once it passes.
          * @throws {@link AssertionError} On timeout.
          */
-        isError: autoGuardSymbol,
+        isError: createWaitUntil(isError),
     },
 };

package/dist/assertions/uuid.d.ts

@@ -1,9 +1,5 @@
-import { type MaybePromise, type Uuid } from '@augment-vir/core';
-import { autoGuardSymbol } from '../guard-types/guard-override.js';
+import { type MaybePromise, type NarrowToExpected, type Uuid } from '@augment-vir/core';
 import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
-/** Checks if the input string is a valid v4 UUID. */
-declare function isUuid(actual: unknown, failureMessage?: string | undefined): asserts actual is Uuid;
-declare function isNotUuid<const Actual>(actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Uuid>;
 export declare const uuidGuards: {
     assert: {
         /**
@@ -28,7 +24,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link assert.isNotUuid} : the opposite assertion.
          */
-        isUuid: typeof isUuid;
+        isUuid(this: void, actual: unknown, failureMessage?: string | undefined): asserts actual is Uuid;
         /**
          * Asserts that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_ valid.
          *
@@ -51,7 +47,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link assert.isUuid} : the opposite assertion.
          */
-        isNotUuid: typeof isNotUuid;
+        isNotUuid<const Actual>(this: void, actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Uuid>;
     };
     check: {
         /**
@@ -75,7 +71,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link check.isNotUuid} : the opposite check.
          */
-        isUuid: typeof autoGuardSymbol;
+        isUuid(this: void, actual: unknown): actual is Uuid;
         /**
          * Checks that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid.
@@ -98,7 +94,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link check.isUuid} : the opposite check.
          */
-        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => actual is Exclude<Actual, Uuid>;
+        isNotUuid<Actual>(this: void, actual: Actual): actual is Exclude<Actual, Uuid>;
     };
     assertWrap: {
         /**
@@ -124,7 +120,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link assertWrap.isNotUuid} : the opposite assertion.
          */
-        isUuid: typeof autoGuardSymbol;
+        isUuid<Actual>(this: void, actual: unknown, failureMessage?: string | undefined): NarrowToExpected<Actual, Uuid>;
         /**
          * Asserts that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid. Returns the value if the assertion passes.
@@ -148,7 +144,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link assertWrap.isUuid} : the opposite assertion.
          */
-        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Uuid>;
+        isNotUuid<const Actual>(this: void, actual: Actual, failureMessage?: string | undefined): Exclude<Actual, Uuid>;
     };
     checkWrap: {
         /**
@@ -174,7 +170,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link checkWrap.isNotUuid} : the opposite check.
          */
-        isUuid: typeof autoGuardSymbol;
+        isUuid<Actual>(this: void, actual: Actual): NarrowToExpected<Actual, Uuid> | undefined;
         /**
          * Checks that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid. Returns the value if the check passes, otherwise `undefined`.
@@ -198,7 +194,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link checkWrap.isUuid} : the opposite check.
          */
-        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Uuid> | undefined;
+        isNotUuid<Actual>(this: void, actual: Actual): Exclude<Actual, Uuid> | undefined;
     };
     waitUntil: {
         /**
@@ -226,7 +222,7 @@ export declare const uuidGuards: {
          * @see
          * - {@link waitUntil.isNotUuid} : the opposite assertion.
          */
-        isUuid: typeof autoGuardSymbol;
+        isUuid: <const Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Uuid>>;
         /**
          * Repeatedly calls a callback until its output is _not_ a valid UUID. The nil or max UUIDs
          * are included as _not_ valid. Returns the value if the assertion passes. Once the callback
@@ -252,7 +248,6 @@ export declare const uuidGuards: {
          * @see
          * - {@link waitUntil.isUuid} : the opposite assertion.
          */
-        isNotUuid: <const Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Uuid>>;
+        isNotUuid: <const Actual>(this: void, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Uuid>>;
     };
 };
-export {};

package/dist/assertions/uuid.js

@@ -1,20 +1,61 @@
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard, autoGuardSymbol } from '../guard-types/guard-override.js';
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
 const uuidRegExp = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-/** Checks if the input string is a valid v4 UUID. */
-function isUuid(actual, failureMessage) {
-    if (!String(actual).match(uuidRegExp)) {
-        throw new AssertionError(`'${String(actual)}' is not a UUID.`, failureMessage);
-    }
-}
-function isNotUuid(actual, failureMessage) {
-    if (String(actual).match(uuidRegExp)) {
-        throw new AssertionError(`'${String(actual)}' is a UUID.`, failureMessage);
-    }
-}
 const assertions = {
-    isUuid,
-    isNotUuid,
+    /**
+     * Asserts that a value is a valid UUID. Does not accept the nil or max UUIDs.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     * import {createUuidV4} from '@augment-vir/common';
+     *
+     * assert.isUuid(createUuidV4()); // passes
+     * assert.isUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // passes
+     * assert.isUuid('00000000-0000-0000-0000-000000000000'); // fails
+     * assert.isUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // fails
+     * assert.isUuid('not-a-uuid'); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the assertion fails.
+     * @see
+     * - {@link assert.isNotUuid} : the opposite assertion.
+     */
+    isUuid(actual, failureMessage) {
+        if (!String(actual).match(uuidRegExp)) {
+            throw new AssertionError(`'${String(actual)}' is not a UUID.`, failureMessage);
+        }
+    },
+    /**
+     * Asserts that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_ valid.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     * import {createUuidV4} from '@augment-vir/common';
+     *
+     * assert.isNotUuid(createUuidV4()); // fails
+     * assert.isNotUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // fails
+     * assert.isNotUuid('00000000-0000-0000-0000-000000000000'); // passes
+     * assert.isNotUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // passes
+     * assert.isNotUuid('not-a-uuid'); // passes
+     * ```
+     *
+     * @throws {@link AssertionError} If the assertion fails.
+     * @see
+     * - {@link assert.isUuid} : the opposite assertion.
+     */
+    isNotUuid(actual, failureMessage) {
+        if (String(actual).match(uuidRegExp)) {
+            throw new AssertionError(`'${String(actual)}' is a UUID.`, failureMessage);
+        }
+    },
 };
 export const uuidGuards = {
     assert: assertions,
@@ -40,7 +81,9 @@ export const uuidGuards = {
          * @see
          * - {@link check.isNotUuid} : the opposite check.
          */
-        isUuid: autoGuardSymbol,
+        isUuid(actual) {
+            return !!String(actual).match(uuidRegExp);
+        },
         /**
          * Checks that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid.
@@ -63,7 +106,9 @@ export const uuidGuards = {
          * @see
          * - {@link check.isUuid} : the opposite check.
          */
-        isNotUuid: autoGuard(),
+        isNotUuid(actual) {
+            return !String(actual).match(uuidRegExp);
+        },
     },
     assertWrap: {
         /**
@@ -89,7 +134,12 @@ export const uuidGuards = {
          * @see
          * - {@link assertWrap.isNotUuid} : the opposite assertion.
          */
-        isUuid: autoGuardSymbol,
+        isUuid(actual, failureMessage) {
+            if (!String(actual).match(uuidRegExp)) {
+                throw new AssertionError(`'${String(actual)}' is not a UUID.`, failureMessage);
+            }
+            return actual;
+        },
         /**
          * Asserts that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid. Returns the value if the assertion passes.
@@ -113,7 +163,12 @@ export const uuidGuards = {
          * @see
          * - {@link assertWrap.isUuid} : the opposite assertion.
          */
-        isNotUuid: autoGuard(),
+        isNotUuid(actual, failureMessage) {
+            if (String(actual).match(uuidRegExp)) {
+                throw new AssertionError(`'${String(actual)}' is a UUID.`, failureMessage);
+            }
+            return actual;
+        },
     },
     checkWrap: {
         /**
@@ -139,7 +194,14 @@ export const uuidGuards = {
          * @see
          * - {@link checkWrap.isNotUuid} : the opposite check.
          */
-        isUuid: autoGuardSymbol,
+        isUuid(actual) {
+            if (String(actual).match(uuidRegExp)) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        },
         /**
          * Checks that a value is _not_ a valid UUID. The nil or max UUIDs are included as _not_
          * valid. Returns the value if the check passes, otherwise `undefined`.
@@ -163,7 +225,14 @@ export const uuidGuards = {
          * @see
          * - {@link checkWrap.isUuid} : the opposite check.
          */
-        isNotUuid: autoGuard(),
+        isNotUuid(actual) {
+            if (String(actual).match(uuidRegExp)) {
+                return undefined;
+            }
+            else {
+                return actual;
+            }
+        },
     },
     waitUntil: {
         /**
@@ -191,7 +260,7 @@ export const uuidGuards = {
          * @see
          * - {@link waitUntil.isNotUuid} : the opposite assertion.
          */
-        isUuid: autoGuardSymbol,
+        isUuid: createWaitUntil(assertions.isUuid),
         /**
          * Repeatedly calls a callback until its output is _not_ a valid UUID. The nil or max UUIDs
          * are included as _not_ valid. Returns the value if the assertion passes. Once the callback
@@ -217,6 +286,6 @@ export const uuidGuards = {
          * @see
          * - {@link waitUntil.isUuid} : the opposite assertion.
          */
-        isNotUuid: autoGuard(),
+        isNotUuid: createWaitUntil(assertions.isNotUuid),
     },
 };