@augment-vir/assert 30.0.0 → 30.0.2

package/dist/assertions/extendable-assertions.js

@@ -19,26 +19,26 @@ import { throwGuards } from './throws.js';
 import { uuidGuards } from './uuid.js';
 import { valueGuards } from './values.js';
 export const extendableAssertions = {
-    ...booleanGuards.assertions,
-    ...boundaryGuards.assertions,
-    ...entryEqualityGuards.assertions,
-    ...enumGuards.assertions,
-    ...instanceGuards.assertions,
-    ...jsonEqualityGuards.assertions,
-    ...keyGuards.assertions,
-    ...lengthGuards.assertions,
-    ...nullishGuards.assertions,
-    ...numericGuards.assertions,
-    ...primitiveGuards.assertions,
-    ...promiseGuards.assertions,
-    ...regexpGuards.assertions,
-    ...runtimeTypeGuards.assertions,
-    ...simpleEqualityGuards.assertions,
-    ...throwGuards.assertions,
-    ...uuidGuards.assertions,
-    ...valueGuards.assertions,
-    ...httpGuards.assertions,
-    ...outputGuards.assertions,
+    ...booleanGuards.assert,
+    ...boundaryGuards.assert,
+    ...entryEqualityGuards.assert,
+    ...enumGuards.assert,
+    ...instanceGuards.assert,
+    ...jsonEqualityGuards.assert,
+    ...keyGuards.assert,
+    ...lengthGuards.assert,
+    ...nullishGuards.assert,
+    ...numericGuards.assert,
+    ...primitiveGuards.assert,
+    ...promiseGuards.assert,
+    ...regexpGuards.assert,
+    ...runtimeTypeGuards.assert,
+    ...simpleEqualityGuards.assert,
+    ...throwGuards.assert,
+    ...uuidGuards.assert,
+    ...valueGuards.assert,
+    ...httpGuards.assert,
+    ...outputGuards.assert,
 };
 /**
  * These overrides are required for more complex guards because TypeScript won't allow us to
@@ -66,43 +66,15 @@ export const guardOverrides = [
     httpGuards,
     outputGuards,
 ];
-export const checkOverrides = Object.assign({}, ...guardOverrides
-    .map((entry) => {
-    if ('checkOverrides' in entry) {
-        return entry.checkOverrides;
-    }
-    else {
-        return undefined;
-    }
-})
-    .filter((entry) => !!entry));
-export const assertWrapOverrides = Object.assign({}, ...guardOverrides
-    .map((entry) => {
-    if ('assertWrapOverrides' in entry) {
-        return entry.assertWrapOverrides;
-    }
-    else {
-        return undefined;
-    }
-})
-    .filter((entry) => !!entry));
-export const checkWrapOverrides = Object.assign({}, ...guardOverrides
-    .map((entry) => {
-    if ('checkWrapOverrides' in entry) {
-        return entry.checkWrapOverrides;
-    }
-    else {
-        return undefined;
-    }
-})
-    .filter((entry) => !!entry));
-export const waitUntilOverrides = Object.assign({}, ...guardOverrides
-    .map((entry) => {
-    if ('waitUntilOverrides' in entry) {
-        return entry.waitUntilOverrides;
-    }
-    else {
-        return undefined;
-    }
-})
-    .filter((entry) => !!entry));
+export const checkOverrides = Object.assign({}, ...guardOverrides.map((entry) => {
+    return entry.check;
+}));
+export const assertWrapOverrides = Object.assign({}, ...guardOverrides.map((entry) => {
+    return entry.assertWrap;
+}));
+export const checkWrapOverrides = Object.assign({}, ...guardOverrides.map((entry) => {
+    return entry.checkWrap;
+}));
+export const waitUntilOverrides = Object.assign({}, ...guardOverrides.map((entry) => {
+    return entry.waitUntil;
+}));

package/dist/assertions/http.d.ts

@@ -1,35 +1,242 @@
 import { HttpStatus, type HttpStatusByCategory, type HttpStatusCategory, type MaybePromise, type NarrowToExpected } from '@augment-vir/core';
+import { autoGuardSymbol } from '../guard-types/guard-override.js';
 import type { WaitUntilOptions } from '../guard-types/wait-until-function.js';
 declare function isHttpStatus(actual: unknown, failureMessage?: string | undefined): asserts actual is HttpStatus;
 declare function isHttpStatusCategory<const Actual, const Category extends HttpStatusCategory>(actual: Actual, category: Category, failureMessage?: string | undefined): asserts actual is NarrowToExpected<Actual, HttpStatusByCategory<Category>>;
 export declare const httpGuards: {
-    assertions: {
+    assert: {
         /**
-         * Checks that a value is a standardized HTTP status code. See {@link HttpStatus} for the
-         * statuses.
+         * 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: typeof isHttpStatus;
         /**
-         * Checks that a value is a standardized HTTP status code within the given category of HTTP
-         * status codes. See {@link HttpStatus} for the statuses and {@link HttpStatusCategory} for the
-         * categories.
+         * 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: typeof isHttpStatusCategory;
     };
-    checkOverrides: {
+    check: {
+        /**
+         * Checks that a value is an {@link HttpStatus}.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isHttpStatus(400); // returns `true`
+         * check.isHttpStatus(500); // returns `true`
+         * check.isHttpStatus(99); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isHttpStatusCategory} : the category check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: typeof autoGuardSymbol;
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `true`
+         * check.isHttpStatusCategory(500, HttpStatusCategory.Success); // returns `false`
+         * check.isHttpStatusCategory(99, HttpStatusCategory.Information); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isHttpStatus} : the status check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: <const Actual, const Category extends HttpStatusCategory>(actual: Actual, category: Category, failureMessage?: string | undefined) => actual is NarrowToExpected<Actual, HttpStatusByCategory<Category>>;
     };
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that a value is an {@link HttpStatus}. Returns the value if the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isHttpStatus(400); // returns `400`
+         * assertWrap.isHttpStatus(500); // returns `500`
+         * assertWrap.isHttpStatus(99); // throws an error
+         * ```
+         *
+         * @throws {@link AssertionError} If the value is not an {@link HttpStatus}.
+         * @see
+         * - {@link assertWrap.isHttpStatusCategory} : the category assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: typeof autoGuardSymbol;
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         * Returns the value if the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
+         * assertWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // throws an error
+         * assertWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // throws an error
+         * ```
+         *
+         * @see
+         * - {@link assertWrap.isHttpStatus} : the status assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: <const Actual, const Category extends HttpStatusCategory>(actual: Actual, category: Category, failureMessage?: string | undefined) => NarrowToExpected<Actual, HttpStatusByCategory<Category>>;
     };
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that a value is an {@link HttpStatus}. Returns the value if the check passes,
+         * otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isHttpStatus(400); // returns `400`
+         * checkWrap.isHttpStatus(500); // returns `500`
+         * checkWrap.isHttpStatus(99); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the check passes, otherwise `undefined`.
+         * @see
+         * - {@link checkWrap.isHttpStatusCategory} : the category check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: typeof autoGuardSymbol;
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         * Returns the value if the check passes, otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
+         * checkWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // returns `undefined`
+         * checkWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // returns `undefined`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isHttpStatus} : the status check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: <const Actual, const Category extends HttpStatusCategory>(actual: Actual, category: Category, failureMessage?: string | undefined) => NarrowToExpected<Actual, HttpStatusByCategory<Category>> | undefined;
     };
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is an {@link HttpStatus}. 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.isHttpStatus(() => 400); // returns `400`
+         * await waitUntil.isHttpStatus(() => 500); // returns `500`
+         * await waitUntil.isHttpStatus(() => 99); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isHttpStatusCategory} : the category assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: typeof autoGuardSymbol;
+        /**
+         * 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
+         * attempts time out, an error is thrown.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.ClientError, () => 400); // returns `400`
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.Success, () => 500); // throws an error more
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.Information, () => 99); // throws an error more
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isHttpStatus} : the status assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: <const Actual, const Category extends HttpStatusCategory>(category: Category, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, HttpStatusByCategory<Category>>>;
     };
 };

package/dist/assertions/http.js

@@ -1,6 +1,6 @@
 import { HttpStatus, httpStatusByCategory, 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';
 import { isEnumValue } from './enum.js';
 import { isIn } from './values.js';
 function isHttpStatus(actual, failureMessage) {
@@ -25,17 +25,193 @@ const assertions = {
     isHttpStatusCategory,
 };
 export const httpGuards = {
-    assertions,
-    checkOverrides: {
+    assert: assertions,
+    check: {
+        /**
+         * Checks that a value is an {@link HttpStatus}.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isHttpStatus(400); // returns `true`
+         * check.isHttpStatus(500); // returns `true`
+         * check.isHttpStatus(99); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isHttpStatusCategory} : the category check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: autoGuardSymbol,
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `true`
+         * check.isHttpStatusCategory(500, HttpStatusCategory.Success); // returns `false`
+         * check.isHttpStatusCategory(99, HttpStatusCategory.Information); // returns `false`
+         * ```
+         *
+         * @see
+         * - {@link check.isHttpStatus} : the status check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: autoGuard(),
     },
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that a value is an {@link HttpStatus}. Returns the value if the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isHttpStatus(400); // returns `400`
+         * assertWrap.isHttpStatus(500); // returns `500`
+         * assertWrap.isHttpStatus(99); // throws an error
+         * ```
+         *
+         * @throws {@link AssertionError} If the value is not an {@link HttpStatus}.
+         * @see
+         * - {@link assertWrap.isHttpStatusCategory} : the category assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: autoGuardSymbol,
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         * Returns the value if the assertion passes.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
+         * assertWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // throws an error
+         * assertWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // throws an error
+         * ```
+         *
+         * @see
+         * - {@link assertWrap.isHttpStatus} : the status assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: autoGuard(),
     },
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that a value is an {@link HttpStatus}. Returns the value if the check passes,
+         * otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isHttpStatus(400); // returns `400`
+         * checkWrap.isHttpStatus(500); // returns `500`
+         * checkWrap.isHttpStatus(99); // returns `undefined`
+         * ```
+         *
+         * @returns The value if the check passes, otherwise `undefined`.
+         * @see
+         * - {@link checkWrap.isHttpStatusCategory} : the category check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: autoGuardSymbol,
+        /**
+         * Checks that a value is an {@link HttpStatus} within a specific {@link HttpStatusCategory}.
+         * Returns the value if the check passes, otherwise `undefined`.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
+         * checkWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // returns `undefined`
+         * checkWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // returns `undefined`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.isHttpStatus} : the status check.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: autoGuard(),
     },
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output is an {@link HttpStatus}. 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.isHttpStatus(() => 400); // returns `400`
+         * await waitUntil.isHttpStatus(() => 500); // returns `500`
+         * await waitUntil.isHttpStatus(() => 99); // throws an error
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isHttpStatusCategory} : the category assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
+        isHttpStatus: autoGuardSymbol,
+        /**
+         * 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
+         * attempts time out, an error is thrown.
+         *
+         * Type guards the value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.ClientError, () => 400); // returns `400`
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.Success, () => 500); // throws an error more
+         * await waitUntil.isHttpStatusCategory(HttpStatusCategory.Information, () => 99); // throws an error more
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.isHttpStatus} : the status assertion.
+         * - {@link HttpStatus} : all included statuses.
+         * - {@link HttpStatusCategory} : all status categories.
+         */
         isHttpStatusCategory: autoGuard(),
     },
 };