@augment-vir/assert 30.8.4 → 31.0.1

package/dist/assertions/enum.d.ts

@@ -1,8 +1,8 @@
 import type { NarrowToExpected } from '@augment-vir/core';
 import { type EnumBaseType, type MaybePromise } from '@augment-vir/core';
 import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
-export declare function isEnumValue<const Expected extends EnumBaseType>(child: unknown, checkEnum: Expected, failureMessage?: string | undefined): asserts child is Expected[keyof Expected];
-declare function isNotEnumValue<const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected, failureMessage?: string | undefined): asserts child is Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
+export declare function assertIsEnumValue<const Expected extends EnumBaseType>(this: void, child: unknown, checkEnum: Expected, failureMessage?: string | undefined): asserts child is Expected[keyof Expected];
+export declare function isEnumValue<const Expected extends EnumBaseType>(this: void, child: unknown, checkEnum: Expected): child is Expected[keyof Expected];
 export declare const enumGuards: {
     assert: {
         /**
@@ -28,7 +28,7 @@ export declare const enumGuards: {
          * @see
          * - {@link assert.isNotEnumValue} : the opposite assertion.
          */
-        isEnumValue: typeof isEnumValue;
+        isEnumValue<const Expected extends EnumBaseType>(this: void, child: unknown, checkEnum: Expected, failureMessage?: string | undefined): asserts child is Expected[keyof Expected];
         /**
          * Asserts that a child value is _not_ an enum member.
          *
@@ -52,7 +52,7 @@ export declare const enumGuards: {
          * @see
          * - {@link assert.isEnumValue} : the opposite assertion.
          */
-        isNotEnumValue: typeof isNotEnumValue;
+        isNotEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected, failureMessage?: string | undefined): asserts child is Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
     };
     check: {
         /**
@@ -77,7 +77,7 @@ export declare const enumGuards: {
          * @see
          * - {@link check.isNotEnumValue} : the opposite check.
          */
-        isEnumValue: <const Expected extends EnumBaseType>(child: unknown, checkEnum: Expected) => child is Expected[keyof Expected];
+        isEnumValue: typeof isEnumValue;
         /**
          * Checks that a child value is _not_ an enum member.
          *
@@ -100,7 +100,7 @@ export declare const enumGuards: {
          * @see
          * - {@link check.isEnumValue} : the opposite check.
          */
-        isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected) => child is Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
+        isNotEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected): child is Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
     };
     assertWrap: {
         /**
@@ -128,7 +128,7 @@ export declare const enumGuards: {
          * @see
          * - {@link assertWrap.isNotEnumValue} : the opposite assertion.
          */
-        isEnumValue: <const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected[keyof Expected]>;
+        isEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected, failureMessage?: string | undefined): NarrowToExpected<Actual, Expected[keyof Expected]>;
         /**
          * Asserts that a child value is _not_ an enum member. Returns the child value if the
          * assertion passes.
@@ -154,7 +154,7 @@ export declare const enumGuards: {
          * @see
          * - {@link assertWrap.isEnumValue} : the opposite assertion.
          */
-        isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected, failureMessage?: string | undefined) => Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
+        isNotEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected, failureMessage?: string | undefined): Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>;
     };
     checkWrap: {
         /**
@@ -181,7 +181,7 @@ export declare const enumGuards: {
          * @see
          * - {@link checkWrap.isNotEnumValue} : the opposite check.
          */
-        isEnumValue: <const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected) => NarrowToExpected<Actual, Expected[keyof Expected]> | undefined;
+        isEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected): NarrowToExpected<Actual, Expected[keyof Expected]> | undefined;
         /**
          * Checks that a child value is _not_ an enum member. Returns the child value if the check
          * passes, otherwise `undefined`.
@@ -206,7 +206,7 @@ export declare const enumGuards: {
          * @see
          * - {@link checkWrap.isEnumValue} : the opposite check.
          */
-        isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(child: Actual, checkEnum: Expected) => Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`> | undefined;
+        isNotEnumValue<const Actual, const Expected extends EnumBaseType>(this: void, child: Actual, checkEnum: Expected): Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`> | undefined;
     };
     waitUntil: {
         /**
@@ -234,7 +234,7 @@ export declare const enumGuards: {
          * @see
          * - {@link waitUntil.isNotEnumValue} : the opposite assertion.
          */
-        isEnumValue: <const Actual, const Expected extends EnumBaseType>(checkEnum: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected[keyof Expected]>>;
+        isEnumValue: <const Actual, const Expected extends EnumBaseType>(this: void, checkEnum: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected[keyof Expected]>>;
         /**
          * Repeatedly calls a callback until its output is _not_ an enum member. Once the callback
          * output passes, it is returned. If the attempts time out, an error is thrown.
@@ -260,7 +260,6 @@ export declare const enumGuards: {
          * @see
          * - {@link waitUntil.isEnumValue} : the opposite assertion.
          */
-        isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(checkEnum: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>>;
+        isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(this: void, checkEnum: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>>;
     };
 };
-export {};

package/dist/assertions/enum.js

@@ -1,25 +1,72 @@
 import { getEnumValues } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard } from '../guard-types/guard-override.js';
-export function isEnumValue(child, checkEnum, failureMessage) {
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
+export function assertIsEnumValue(child, checkEnum, failureMessage) {
     const values = getEnumValues(checkEnum);
     if (!values.includes(child)) {
         throw new AssertionError(`${String(child)} is not an enum value in '${values.join(',')}'.`, failureMessage);
     }
 }
-function isNotEnumValue(child, checkEnum, failureMessage) {
-    try {
-        isEnumValue(child, checkEnum);
-    }
-    catch {
-        return;
-    }
+export function isEnumValue(child, checkEnum) {
     const values = getEnumValues(checkEnum);
-    throw new AssertionError(`${String(child)} is an enum value in '${values.join(',')}'`, failureMessage);
+    return values.includes(child);
 }
 const assertions = {
-    isEnumValue,
-    isNotEnumValue,
+    /**
+     * Asserts that a child value is an enum member.
+     *
+     * Type guards the child value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * enum MyEnum {
+     *     A = 'a',
+     *     B = 'b',
+     * }
+     *
+     * assert.isEnumValue('a', MyEnum); // passes
+     * assert.isEnumValue('A', MyEnum); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the child is not an enum member.
+     * @see
+     * - {@link assert.isNotEnumValue} : the opposite assertion.
+     */
+    isEnumValue(child, checkEnum, failureMessage) {
+        assertIsEnumValue(child, checkEnum, failureMessage);
+    },
+    /**
+     * Asserts that a child value is _not_ an enum member.
+     *
+     * Type guards the child value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * enum MyEnum {
+     *     A = 'a',
+     *     B = 'b',
+     * }
+     *
+     * assert.isNotEnumValue('a', MyEnum); // fails
+     * assert.isNotEnumValue('A', MyEnum); // passes
+     * ```
+     *
+     * @throws {@link AssertionError} If the child is an enum member.
+     * @see
+     * - {@link assert.isEnumValue} : the opposite assertion.
+     */
+    isNotEnumValue(child, checkEnum, failureMessage) {
+        const values = getEnumValues(checkEnum);
+        if (values.includes(child)) {
+            throw new AssertionError(`${String(child)} is an enum value in '${values.join(',')}'.`, failureMessage);
+        }
+    },
 };
 export const enumGuards = {
     assert: assertions,
@@ -46,7 +93,7 @@ export const enumGuards = {
          * @see
          * - {@link check.isNotEnumValue} : the opposite check.
          */
-        isEnumValue: autoGuard(),
+        isEnumValue,
         /**
          * Checks that a child value is _not_ an enum member.
          *
@@ -69,7 +116,10 @@ export const enumGuards = {
          * @see
          * - {@link check.isEnumValue} : the opposite check.
          */
-        isNotEnumValue: autoGuard(),
+        isNotEnumValue(child, checkEnum) {
+            const values = getEnumValues(checkEnum);
+            return !values.includes(child);
+        },
     },
     assertWrap: {
         /**
@@ -97,7 +147,13 @@ export const enumGuards = {
          * @see
          * - {@link assertWrap.isNotEnumValue} : the opposite assertion.
          */
-        isEnumValue: autoGuard(),
+        isEnumValue(child, checkEnum, failureMessage) {
+            const values = getEnumValues(checkEnum);
+            if (!values.includes(child)) {
+                throw new AssertionError(`${String(child)} is not an enum value in '${values.join(',')}'.`, failureMessage);
+            }
+            return child;
+        },
         /**
          * Asserts that a child value is _not_ an enum member. Returns the child value if the
          * assertion passes.
@@ -123,7 +179,13 @@ export const enumGuards = {
          * @see
          * - {@link assertWrap.isEnumValue} : the opposite assertion.
          */
-        isNotEnumValue: autoGuard(),
+        isNotEnumValue(child, checkEnum, failureMessage) {
+            const values = getEnumValues(checkEnum);
+            if (values.includes(child)) {
+                throw new AssertionError(`${String(child)} is not an enum value in '${values.join(',')}'.`, failureMessage);
+            }
+            return child;
+        },
     },
     checkWrap: {
         /**
@@ -150,7 +212,15 @@ export const enumGuards = {
          * @see
          * - {@link checkWrap.isNotEnumValue} : the opposite check.
          */
-        isEnumValue: autoGuard(),
+        isEnumValue(child, checkEnum) {
+            const values = getEnumValues(checkEnum);
+            if (values.includes(child)) {
+                return child;
+            }
+            else {
+                return undefined;
+            }
+        },
         /**
          * Checks that a child value is _not_ an enum member. Returns the child value if the check
          * passes, otherwise `undefined`.
@@ -175,7 +245,15 @@ export const enumGuards = {
          * @see
          * - {@link checkWrap.isEnumValue} : the opposite check.
          */
-        isNotEnumValue: autoGuard(),
+        isNotEnumValue(child, checkEnum) {
+            const values = getEnumValues(checkEnum);
+            if (values.includes(child)) {
+                return undefined;
+            }
+            else {
+                return child;
+            }
+        },
     },
     waitUntil: {
         /**
@@ -203,7 +281,7 @@ export const enumGuards = {
          * @see
          * - {@link waitUntil.isNotEnumValue} : the opposite assertion.
          */
-        isEnumValue: autoGuard(),
+        isEnumValue: createWaitUntil(assertions.isEnumValue),
         /**
          * Repeatedly calls a callback until its output is _not_ an enum member. Once the callback
          * output passes, it is returned. If the attempts time out, an error is thrown.
@@ -229,6 +307,6 @@ export const enumGuards = {
          * @see
          * - {@link waitUntil.isEnumValue} : the opposite assertion.
          */
-        isNotEnumValue: autoGuard(),
+        isNotEnumValue: createWaitUntil(assertions.isNotEnumValue),
     },
 };

package/dist/assertions/equality/entry-equality.d.ts

@@ -1,9 +1,6 @@
 import type { NarrowToExpected } from '@augment-vir/core';
-import { type MaybePromise } from '@augment-vir/core';
-import { autoGuardSymbol } from '../../guard-types/guard-override.js';
+import { type AnyObject, type MaybePromise } from '@augment-vir/core';
 import { type WaitUntilOptions } from '../../guard-types/wait-until-function.js';
-declare function entriesEqual<const Actual extends object, const Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is Expected;
-declare function notEntriesEqual(actual: object, expected: object, failureMessage?: string | undefined): void;
 export declare const entryEqualityGuards: {
     assert: {
         /**
@@ -33,7 +30,7 @@ export declare const entryEqualityGuards: {
          * - {@link assert.jsonEquals} : another deep equality assertion.
          * - {@link assert.deepEquals} : the most thorough (but also slow) deep equality assertion.
          */
-        entriesEqual: typeof entriesEqual;
+        entriesEqual<Actual extends AnyObject, const Expected extends Actual>(this: void, actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is Expected;
         /**
          * Asserts that two objects are _not_ deeply equal by checking only their top-level values for
          * strict (non-deep, reference, using
@@ -61,7 +58,7 @@ export declare const entryEqualityGuards: {
          * - {@link assert.notJsonEquals} : another not deep equality assertion.
          * - {@link assert.notDeepEquals} : the most thorough (but also slow) not deep equality assertion.
          */
-        notEntriesEqual: typeof notEntriesEqual;
+        notEntriesEqual(this: void, actual: AnyObject, expected: AnyObject, failureMessage?: string | undefined): void;
     };
     check: {
         /**
@@ -90,7 +87,7 @@ export declare const entryEqualityGuards: {
          * - {@link check.jsonEquals} : another deep equality check.
          * - {@link check.deepEquals} : the most thorough (but also slow) deep equality check.
          */
-        entriesEqual: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => actual is Expected;
+        entriesEqual<Actual extends AnyObject, Expected extends Actual>(this: void, actual: Actual, expected: Expected): actual is Expected;
         /**
          * Checks that two objects are _not_ deeply equal by checking only their top-level values
          * for strict (non-deep, reference, using
@@ -117,7 +114,7 @@ export declare const entryEqualityGuards: {
          * - {@link check.notJsonEquals} : another not deep equality check.
          * - {@link check.notDeepEquals} : the most thorough (but also slow) not deep equality check.
          */
-        notEntriesEqual: typeof autoGuardSymbol;
+        notEntriesEqual(this: void, actual: AnyObject, expected: AnyObject): boolean;
     };
     assertWrap: {
         /**
@@ -148,7 +145,7 @@ export declare const entryEqualityGuards: {
          * - {@link assertWrap.jsonEquals} : another deep equality assertion.
          * - {@link assertWrap.deepEquals} : the most thorough (but also slow) deep equality assertion.
          */
-        entriesEqual: <Actual, Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected>;
+        entriesEqual<Actual extends AnyObject, Expected extends Actual>(this: void, actual: Actual, expected: Expected, failureMessage?: string | undefined): NarrowToExpected<Actual, Expected>;
         /**
          * Asserts that two objects are _not_ deeply equal by checking only their top-level values
          * for strict (non-deep, reference, using
@@ -177,7 +174,7 @@ export declare const entryEqualityGuards: {
          * - {@link assertWrap.notJsonEquals} : another not deep equality assertion.
          * - {@link assertWrap.notDeepEquals} : the most thorough (but also slow) not deep equality assertion.
          */
-        notEntriesEqual: typeof autoGuardSymbol;
+        notEntriesEqual<Actual extends AnyObject>(this: void, actual: Actual, expected: AnyObject, failureMessage?: string | undefined): Actual;
     };
     checkWrap: {
         /**
@@ -208,7 +205,7 @@ export declare const entryEqualityGuards: {
          * - {@link checkWrap.jsonEquals} : another deep equality check.
          * - {@link checkWrap.deepEquals} : the most thorough (but also slow) deep equality check.
          */
-        entriesEqual: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => NarrowToExpected<Actual, Expected> | undefined;
+        entriesEqual<Actual extends object, Expected extends Actual>(this: void, actual: Actual, expected: Expected): NarrowToExpected<Actual, Expected> | undefined;
         /**
          * Checks that two objects are _not_ deeply equal by checking only their top-level values
          * for strict (non-deep, reference, using
@@ -237,7 +234,7 @@ export declare const entryEqualityGuards: {
          * - {@link checkWrap.notJsonEquals} : another not deep equality check.
          * - {@link checkWrap.notDeepEquals} : the most thorough (but also slow) not deep equality check.
          */
-        notEntriesEqual: typeof autoGuardSymbol;
+        notEntriesEqual(this: void, actual: AnyObject, expected: AnyObject): AnyObject | undefined;
     };
     waitUntil: {
         /**
@@ -274,7 +271,7 @@ export declare const entryEqualityGuards: {
          * - {@link waitUntil.jsonEquals} : another deep equality assertion.
          * - {@link waitUntil.deepEquals} : the most thorough (but also slow) deep equality assertion.
          */
-        entriesEqual: <Actual, Expected extends Actual>(expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
+        entriesEqual: <Actual extends AnyObject, Expected extends Actual>(this: void, expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
         /**
          * Repeatedly calls a callback until its output is _not_ deeply equal to the first input by
          * checking only their top-level values for strict (non-deep, reference, using
@@ -310,7 +307,6 @@ export declare const entryEqualityGuards: {
          * - {@link waitUntil.notJsonEquals} : another not deep equality assertion.
          * - {@link waitUntil.notDeepEquals} : the most thorough (but also slow) not deep equality assertion.
          */
-        notEntriesEqual: typeof autoGuardSymbol;
+        notEntriesEqual: <Actual extends AnyObject>(this: void, expected: unknown, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Actual>;
     };
 };
-export {};