@augment-vir/assert 30.0.0 → 30.0.1

package/dist/assertions/output.d.ts

@@ -7,6 +7,7 @@ import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
  * default.
  *
  * @category Assert : Util
+ * @category Package : @augment-vir/assert
  * @example
  *
  * ```ts
@@ -32,7 +33,7 @@ import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
  * ```
  *
  * @param FunctionToCall The function type that your custom asserter will be run on.
- * @package @augment-vir/assert
+ * @package [`@augment-vir/assert`](https://www.npmjs.com/package/@augment-vir/assert)
  */
 export type CustomOutputAsserter<FunctionToCall extends AnyFunction> = (actual: Awaited<ReturnType<FunctionToCall>>, expected: Awaited<ReturnType<FunctionToCall>>, failureMessage?: string | undefined) => void;
 type OutputReturn<FunctionToCall extends AnyFunction, Return> = Promise<any> extends ReturnType<NoInfer<FunctionToCall>> ? IsAny<ReturnType<FunctionToCall>> extends true ? Return : Promise<Return> : Return;
@@ -57,26 +58,125 @@ export type OutputWaitUntilWithAsserter = <const FunctionToCall extends AnyFunct
 export declare function waitUntilOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
 export declare function waitUntilOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
 export declare const outputGuards: {
-    assertions: {
+    assert: {
         /**
-         * Checks that the output of the given function deeply equals expectations. A custom asserter
+         * Asserts that the output of the given function deeply equals expectations. A custom asserter
          * can optionally be provided as the first argument to change the expectation checking from
          * "deeply equals" to whatever you want.
          *
          * Performs no type guarding.
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.output((input: number) => String(input), [5], '5'); // passes
+         * assert.output((input: number) => String(input), [10], '5'); // fails
+         *
+         * assert.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // fails
+         * assert.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // passes
+         * ```
+         *
+         * @throws {@link AssertionError} If the assertion fails.
          */
         output: typeof assertOutput;
     };
-    checkOverrides: {
+    check: {
+        /**
+         * Checks that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.output((input: number) => String(input), [5], '5'); // returns `true`
+         * check.output((input: number) => String(input), [10], '5'); // returns `false`
+         *
+         * check.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // returns `false`
+         * check.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `true`
+         * ```
+         */
         output: typeof checkOutput;
     };
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want. Returns the output if the
+         * assertion passes.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * assertWrap.output((input: number) => String(input), [10], '5'); // throws an error
+         *
+         * assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // throws an error
+         * assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`
+         * ```
+         *
+         * @returns The output if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         */
         output: typeof assertWrapOutput;
     };
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Asserts that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want. Returns the output if the
+         * check passes, otherwise `undefined`.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * checkWrap.output((input: number) => String(input), [10], '5'); // returns `undefined`
+         *
+         * checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // returns `undefined`
+         * checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`
+         * ```
+         *
+         * @returns The output if the assertion passes, otherwise `undefined`.
+         */
         output: typeof checkWrapOutput;
     };
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * await waitUntil.output((input: number) => String(input), [10], '5'); // throws an error
+         *
+         * await waitUntil.output(
+         *     assert.isLengthAtLeast,
+         *     (input: number) => String(input),
+         *     [5],
+         *     2,
+         * ); // throws an error
+         * await waitUntil.output(
+         *     assert.isLengthAtLeast,
+         *     (input: number) => String(input),
+         *     [10],
+         *     2,
+         * ); // returns `10`
+         * ```
+         *
+         * @throws {@link AssertionError} If the assertion fails.
+         */
         output: typeof waitUntilOutput;
     };
 };

package/dist/assertions/output.js

@@ -157,17 +157,104 @@ const assertions = {
     output: assertOutput,
 };
 export const outputGuards = {
-    assertions,
-    checkOverrides: {
+    assert: assertions,
+    check: {
+        /**
+         * Checks that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.output((input: number) => String(input), [5], '5'); // returns `true`
+         * check.output((input: number) => String(input), [10], '5'); // returns `false`
+         *
+         * check.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // returns `false`
+         * check.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `true`
+         * ```
+         */
         output: checkOutput,
     },
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want. Returns the output if the
+         * assertion passes.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * assertWrap.output((input: number) => String(input), [10], '5'); // throws an error
+         *
+         * assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // throws an error
+         * assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`
+         * ```
+         *
+         * @returns The output if the assertion passes.
+         * @throws {@link AssertionError} If the assertion fails.
+         */
         output: assertWrapOutput,
     },
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Asserts that the output of the given function deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want. Returns the output if the
+         * check passes, otherwise `undefined`.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * checkWrap.output((input: number) => String(input), [10], '5'); // returns `undefined`
+         *
+         * checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // returns `undefined`
+         * checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`
+         * ```
+         *
+         * @returns The output if the assertion passes, otherwise `undefined`.
+         */
         output: checkWrapOutput,
     },
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * Repeatedly calls a callback until its output deeply equals expectations. A custom
+         * asserter can optionally be provided as the first argument to change the expectation
+         * checking from the default "deeply equals" to whatever you want.
+         *
+         * Performs no type guarding.
+         *
+         * ```ts
+         * import {waitUntil} from '@augment-vir/assert';
+         *
+         * await waitUntil.output((input: number) => String(input), [5], '5'); // returns `'5'`
+         * await waitUntil.output((input: number) => String(input), [10], '5'); // throws an error
+         *
+         * await waitUntil.output(
+         *     assert.isLengthAtLeast,
+         *     (input: number) => String(input),
+         *     [5],
+         *     2,
+         * ); // throws an error
+         * await waitUntil.output(
+         *     assert.isLengthAtLeast,
+         *     (input: number) => String(input),
+         *     [10],
+         *     2,
+         * ); // returns `10`
+         * ```
+         *
+         * @throws {@link AssertionError} If the assertion fails.
+         */
         output: waitUntilOutput,
     },
 };