@augment-vir/assert 30.8.4 → 31.0.1

package/dist/assertions/http.js

@@ -1,28 +1,65 @@
 import { HttpStatus, httpStatusByCategory, stringify, } from '@augment-vir/core';
 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';
 import { isEnumValue } from './enum.js';
 import { isIn } from './values.js';
-function isHttpStatus(actual, failureMessage) {
-    try {
-        isEnumValue(actual, HttpStatus);
-    }
-    catch {
-        throw new AssertionError(`${stringify(actual)} is not a valid http status.`, failureMessage);
-    }
-}
-function isHttpStatusCategory(actual, category, failureMessage) {
-    try {
-        isEnumValue(actual, HttpStatus);
-        isIn(actual, httpStatusByCategory[category]);
-    }
-    catch {
-        throw new AssertionError(`${stringify(actual)} is not a '${category}' http status.`, failureMessage);
-    }
-}
 const assertions = {
-    isHttpStatus,
-    isHttpStatusCategory,
+    /**
+     * Asserts that a value is an {@link HttpStatus}.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * assert.isHttpStatus(400); // passes
+     * assert.isHttpStatus(500); // passes
+     * assert.isHttpStatus(99); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is not an {@link HttpStatus}.
+     * @see
+     * - {@link assert.isHttpStatusCategory} : the category assertion.
+     * - {@link HttpStatus} : all included statuses.
+     * - {@link HttpStatusCategory} : all status categories.
+     */
+    isHttpStatus(actual, failureMessage) {
+        if (!isEnumValue(actual, HttpStatus)) {
+            throw new AssertionError(`${stringify(actual)} is not a valid HTTP status.`, failureMessage);
+        }
+    },
+    /**
+     * Asserts that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * assert.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // passes
+     * assert.isHttpStatusCategory(500, HttpStatusCategory.Success); // fails
+     * assert.isHttpStatusCategory(99, HttpStatusCategory.Information); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is not an {@link HttpStatus} within the
+     *   {@link HttpStatusCategory}.
+     * @see
+     * - {@link assert.isHttpStatus} : the status assertion.
+     * - {@link HttpStatus} : all included statuses.
+     * - {@link HttpStatusCategory} : all status categories.
+     */
+    isHttpStatusCategory(actual, category, failureMessage) {
+        if (!isEnumValue(actual, HttpStatus)) {
+            throw new AssertionError(`${stringify(actual)} is not a valid HTTP status.`, failureMessage);
+        }
+        else if (!isIn(actual, httpStatusByCategory[category])) {
+            throw new AssertionError(`${stringify(actual)} is not a '${category}' HTTP status.`, failureMessage);
+        }
+    },
 };
 export const httpGuards = {
     assert: assertions,
@@ -47,7 +84,9 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatus: autoGuardSymbol,
+        isHttpStatus(actual) {
+            return isEnumValue(actual, HttpStatus);
+        },
         /**
          * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
          *
@@ -68,7 +107,9 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatusCategory: autoGuard(),
+        isHttpStatusCategory(actual, category) {
+            return isEnumValue(actual, HttpStatus) && isIn(actual, httpStatusByCategory[category]);
+        },
     },
     assertWrap: {
         /**
@@ -92,7 +133,12 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatus: autoGuardSymbol,
+        isHttpStatus(actual, failureMessage) {
+            if (!isEnumValue(actual, HttpStatus)) {
+                throw new AssertionError(`${stringify(actual)} is not a valid HTTP status.`, failureMessage);
+            }
+            return actual;
+        },
         /**
          * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
          * Returns the value if the assertion passes.
@@ -114,7 +160,15 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatusCategory: autoGuard(),
+        isHttpStatusCategory(actual, category, failureMessage) {
+            if (!isEnumValue(actual, HttpStatus)) {
+                throw new AssertionError(`${stringify(actual)} is not a valid HTTP status.`, failureMessage);
+            }
+            else if (!isIn(actual, httpStatusByCategory[category])) {
+                throw new AssertionError(`${stringify(actual)} is not a '${category}' HTTP status.`, failureMessage);
+            }
+            return actual;
+        },
     },
     checkWrap: {
         /**
@@ -139,7 +193,14 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatus: autoGuardSymbol,
+        isHttpStatus(actual) {
+            if (isEnumValue(actual, HttpStatus)) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        },
         /**
          * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
          * Returns the value if the check passes, otherwise `undefined`.
@@ -161,7 +222,14 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatusCategory: autoGuard(),
+        isHttpStatusCategory(actual, category) {
+            if (isEnumValue(actual, HttpStatus) && isIn(actual, httpStatusByCategory[category])) {
+                return actual;
+            }
+            else {
+                return undefined;
+            }
+        },
     },
     waitUntil: {
         /**
@@ -187,7 +255,7 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatus: autoGuardSymbol,
+        isHttpStatus: createWaitUntil(assertions.isHttpStatus),
         /**
          * Repeatedly calls a callback until its output is an {@link HttpStatus} within a specific
          * {@link HttpStatusCategory}. Once the callback output passes, it is returned. If the
@@ -212,6 +280,6 @@ export const httpGuards = {
          * - {@link HttpStatus} : all included statuses.
          * - {@link HttpStatusCategory} : all status categories.
          */
-        isHttpStatusCategory: autoGuard(),
+        isHttpStatusCategory: createWaitUntil(assertions.isHttpStatusCategory),
     },
 };

package/dist/assertions/instance.d.ts

@@ -1,13 +1,6 @@
 import { type MaybePromise } from '@augment-vir/core';
 import { type Constructor } from 'type-fest';
 import { type WaitUntilOptions } from '../guard-types/wait-until-function.js';
-/** Wraps the JavaScript built-in "instanceof" in a type guard assertion. */
-declare function instanceOf<const Instance>(instance: unknown, 
-/** The constructor that the "instance" input will be checked against. */
-constructor: Constructor<Instance>, 
-/** Message to include in error message if this assertion fails. */
-failureMessage?: string | undefined): asserts instance is Instance;
-declare function notInstanceOf<const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>, failureMessage?: string | undefined): asserts instance is Exclude<Actual, Instance>;
 export declare const instanceGuards: {
     assert: {
         /**
@@ -29,7 +22,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link assert.notInstanceOf} : the opposite assertion.
          */
-        instanceOf: typeof instanceOf;
+        instanceOf<const Instance>(this: void, instance: unknown, constructor: Constructor<Instance>, failureMessage?: string | undefined): asserts instance is Instance;
         /**
          * Asserts that a value is _not_ an instance of the given class constructor.
          *
@@ -48,7 +41,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link assert.instanceOf} : the opposite assertion.
          */
-        notInstanceOf: typeof notInstanceOf;
+        notInstanceOf<const Actual, const Instance>(this: void, instance: Actual, constructor: Constructor<Instance>, failureMessage?: string | undefined): asserts instance is Exclude<Actual, Instance>;
     };
     check: {
         /**
@@ -68,7 +61,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link check.notInstanceOf} : the opposite check.
          */
-        instanceOf: <const Instance>(instance: unknown, constructor: Constructor<Instance>) => instance is Instance;
+        instanceOf<const Instance>(this: void, instance: unknown, constructor: Constructor<Instance>): instance is Instance;
         /**
          * Checks that a value is _not_ an instance of the given class constructor.
          *
@@ -86,7 +79,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link check.instanceOf} : the opposite check.
          */
-        notInstanceOf: <const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>) => instance is Exclude<Actual, Instance>;
+        notInstanceOf<const Actual, const Instance>(this: void, instance: Actual, constructor: Constructor<Instance>): instance is Exclude<Actual, Instance>;
     };
     assertWrap: {
         /**
@@ -109,7 +102,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link assertWrap.notInstanceOf} : the opposite assertion.
          */
-        instanceOf: <const Instance>(instance: unknown, constructor: Constructor<Instance>, failureMessage?: string | undefined) => Instance;
+        instanceOf<const Instance>(this: void, instance: unknown, constructor: Constructor<Instance>, failureMessage?: string | undefined): Instance;
         /**
          * Asserts that a value is _not_ an instance of the given class constructor. Returns the
          * value if the assertion passes.
@@ -130,7 +123,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link assertWrap.instanceOf} : the opposite assertion.
          */
-        notInstanceOf: <const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>, failureMessage?: string | undefined) => Exclude<Actual, Instance>;
+        notInstanceOf<const Actual, const Instance>(this: void, instance: Actual, constructor: Constructor<Instance>, failureMessage?: string | undefined): Exclude<Actual, Instance>;
     };
     checkWrap: {
         /**
@@ -152,7 +145,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link checkWrap.notInstanceOf} : the opposite check.
          */
-        instanceOf: <const Instance>(instance: unknown, constructor: Constructor<Instance>) => Instance | undefined;
+        instanceOf<const Instance>(this: void, instance: unknown, constructor: Constructor<Instance>): Instance | undefined;
         /**
          * Checks that a value is _not_ an instance of the given class constructor. Returns the
          * value if the check passes, otherwise `undefined`.
@@ -172,7 +165,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link checkWrap.instanceOf} : the opposite check.
          */
-        notInstanceOf: <const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>) => Exclude<Actual, Instance> | undefined;
+        notInstanceOf<const Actual, const Instance>(this: void, instance: Actual, constructor: Constructor<Instance>): Exclude<Actual, Instance> | undefined;
     };
     waitUntil: {
         /**
@@ -196,7 +189,7 @@ export declare const instanceGuards: {
          * @see
          * - {@link waitUntil.notInstanceOf} : the opposite assertion.
          */
-        instanceOf: <const Instance>(constructor: Constructor<Instance>, callback: () => MaybePromise<unknown>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Instance>;
+        instanceOf: <const Instance>(this: void, constructor: Constructor<Instance>, callback: () => MaybePromise<unknown>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Instance>;
         /**
          * Repeatedly calls a callback until its output is not an instance of the given class
          * constructor. Once the callback output passes, it is returned. If the attempts time out,
@@ -218,7 +211,6 @@ export declare const instanceGuards: {
          * @see
          * - {@link waitUntil.instanceOf} : the opposite assertion.
          */
-        notInstanceOf: <const Actual, const Instance>(constructor: Constructor<Instance>, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Instance>>;
+        notInstanceOf: <const Actual, const Instance>(this: void, constructor: Constructor<Instance>, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Instance>>;
     };
 };
-export {};

package/dist/assertions/instance.js

@@ -1,24 +1,58 @@
 import { stringify } from '@augment-vir/core';
 import { AssertionError } from '../augments/assertion.error.js';
-import { autoGuard } from '../guard-types/guard-override.js';
-/** Wraps the JavaScript built-in "instanceof" in a type guard assertion. */
-function instanceOf(instance, 
-/** The constructor that the "instance" input will be checked against. */
-constructor, 
-/** Message to include in error message if this assertion fails. */
-failureMessage) {
-    if (!(instance instanceof constructor)) {
-        throw new AssertionError(`'${stringify(instance)}' is not an instance of '${constructor.name}'`, failureMessage);
-    }
-}
-function notInstanceOf(instance, constructor, failureMessage) {
-    if (instance instanceof constructor) {
-        throw new AssertionError(`'${stringify(instance)}' is an instance of '${constructor.name}'`, failureMessage);
-    }
-}
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
 const assertions = {
-    instanceOf,
-    notInstanceOf,
+    /**
+     * Asserts that a value is an instance of the given class constructor.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * assert.instanceOf(/abc/, RegExp); // passes
+     * assert.instanceOf('abc', RegExp); // fails
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is not an instance of the given class
+     *   constructor.
+     * @see
+     * - {@link assert.notInstanceOf} : the opposite assertion.
+     */
+    instanceOf(instance, 
+    /** The constructor that the "instance" input will be checked against. */
+    constructor, 
+    /** Message to include in error message if this assertion fails. */
+    failureMessage) {
+        if (!(instance instanceof constructor)) {
+            throw new AssertionError(`'${stringify(instance)}' is not an instance of '${constructor.name}'`, failureMessage);
+        }
+    },
+    /**
+     * Asserts that a value is _not_ an instance of the given class constructor.
+     *
+     * Type guards the value.
+     *
+     * @example
+     *
+     * ```ts
+     * import {assert} from '@augment-vir/assert';
+     *
+     * assert.notInstanceOf(/abc/, RegExp); // fails
+     * assert.notInstanceOf('abc', RegExp); // passes
+     * ```
+     *
+     * @throws {@link AssertionError} If the value is an instance of the given class constructor.
+     * @see
+     * - {@link assert.instanceOf} : the opposite assertion.
+     */
+    notInstanceOf(instance, constructor, failureMessage) {
+        if (instance instanceof constructor) {
+            throw new AssertionError(`'${stringify(instance)}' is an instance of '${constructor.name}'`, failureMessage);
+        }
+    },
 };
 export const instanceGuards = {
     assert: assertions,
@@ -40,7 +74,9 @@ export const instanceGuards = {
          * @see
          * - {@link check.notInstanceOf} : the opposite check.
          */
-        instanceOf: autoGuard(),
+        instanceOf(instance, constructor) {
+            return instance instanceof constructor;
+        },
         /**
          * Checks that a value is _not_ an instance of the given class constructor.
          *
@@ -58,7 +94,9 @@ export const instanceGuards = {
          * @see
          * - {@link check.instanceOf} : the opposite check.
          */
-        notInstanceOf: autoGuard(),
+        notInstanceOf(instance, constructor) {
+            return !(instance instanceof constructor);
+        },
     },
     assertWrap: {
         /**
@@ -81,7 +119,14 @@ export const instanceGuards = {
          * @see
          * - {@link assertWrap.notInstanceOf} : the opposite assertion.
          */
-        instanceOf: autoGuard(),
+        instanceOf(instance, constructor, failureMessage) {
+            if (instance instanceof constructor) {
+                return instance;
+            }
+            else {
+                throw new AssertionError(`'${stringify(instance)}' is not an instance of '${constructor.name}'`, failureMessage);
+            }
+        },
         /**
          * Asserts that a value is _not_ an instance of the given class constructor. Returns the
          * value if the assertion passes.
@@ -102,7 +147,14 @@ export const instanceGuards = {
          * @see
          * - {@link assertWrap.instanceOf} : the opposite assertion.
          */
-        notInstanceOf: autoGuard(),
+        notInstanceOf(instance, constructor, failureMessage) {
+            if (instance instanceof constructor) {
+                throw new AssertionError(`'${stringify(instance)}' is an instance of '${constructor.name}'`, failureMessage);
+            }
+            else {
+                return instance;
+            }
+        },
     },
     checkWrap: {
         /**
@@ -124,7 +176,14 @@ export const instanceGuards = {
          * @see
          * - {@link checkWrap.notInstanceOf} : the opposite check.
          */
-        instanceOf: autoGuard(),
+        instanceOf(instance, constructor) {
+            if (instance instanceof constructor) {
+                return instance;
+            }
+            else {
+                return undefined;
+            }
+        },
         /**
          * Checks that a value is _not_ an instance of the given class constructor. Returns the
          * value if the check passes, otherwise `undefined`.
@@ -144,7 +203,14 @@ export const instanceGuards = {
          * @see
          * - {@link checkWrap.instanceOf} : the opposite check.
          */
-        notInstanceOf: autoGuard(),
+        notInstanceOf(instance, constructor) {
+            if (instance instanceof constructor) {
+                return undefined;
+            }
+            else {
+                return instance;
+            }
+        },
     },
     waitUntil: {
         /**
@@ -168,7 +234,7 @@ export const instanceGuards = {
          * @see
          * - {@link waitUntil.notInstanceOf} : the opposite assertion.
          */
-        instanceOf: autoGuard(),
+        instanceOf: createWaitUntil(assertions.instanceOf),
         /**
          * Repeatedly calls a callback until its output is not an instance of the given class
          * constructor. Once the callback output passes, it is returned. If the attempts time out,
@@ -190,6 +256,6 @@ export const instanceGuards = {
          * @see
          * - {@link waitUntil.instanceOf} : the opposite assertion.
          */
-        notInstanceOf: autoGuard(),
+        notInstanceOf: createWaitUntil(assertions.notInstanceOf),
     },
 };