@dereekb/util 13.11.14 → 13.11.15

package/test/src/lib/shared/shared.fail.d.ts

@@ -12,8 +12,8 @@ export declare class ExpectedFailError extends BaseError {
 /**
  * Creates an {@link ExpectedFailError} without throwing it, for use in deferred error handling.
  *
- * @param message - optional error message
- * @returns a new {@link ExpectedFailError} instance
+ * @param message - Optional error message.
+ * @returns A new {@link ExpectedFailError} instance.
  */
 export declare function failSuccessfullyError(message?: string): ExpectedFailError;
 /**
@@ -23,7 +23,8 @@ export declare function failSuccessfullyError(message?: string): ExpectedFailErr
  * which catch `ExpectedFailError` and convert it into a passing test. Calling it inside a plain
  * `it()` block causes the test to fail because the error propagates uncaught.
  *
- * @param message - optional error message
+ * @param message - Optional error message.
+ * @throws {ExpectedFailError} Always; never returns normally.
  */
 export declare function failSuccessfully(message?: string): never;
 /**
@@ -34,8 +35,8 @@ export declare class UnexpectedSuccessFailureError extends BaseError {
 /**
  * Creates an {@link UnexpectedSuccessFailureError} without throwing it.
  *
- * @param message - optional error message; defaults to a standard "expected an error" message
- * @returns a new {@link UnexpectedSuccessFailureError} instance
+ * @param message - Optional error message; defaults to a standard "expected an error" message.
+ * @returns A new {@link UnexpectedSuccessFailureError} instance.
  */
 export declare function failDueToSuccessError(message?: string): UnexpectedSuccessFailureError;
 /**
@@ -50,19 +51,23 @@ export declare class ExpectedErrorOfSpecificTypeError extends BaseError {
  * Fails the current test by throwing an {@link UnexpectedSuccessFailureError}.
  * Use when a code path should not have been reached.
  *
- * @param message - optional error message
+ * @param message - Optional error message.
+ * @throws {UnexpectedSuccessFailureError} Always; never returns normally.
  */
 export declare function failTest(message?: string): never;
 /**
  * Throws an {@link UnexpectedSuccessFailureError} with a default message.
  * Typically called when an operation succeeds but was expected to throw.
+ *
+ * @throws {UnexpectedSuccessFailureError} Always; never returns normally.
  */
 export declare function failDueToSuccess(): never;
 /**
  * Default error handler for {@link expectSuccessfulFail} that passes through {@link ExpectedFailError}
  * instances and re-throws all other errors.
  *
- * @param e - the caught error to evaluate
+ * @param e - The caught error to evaluate.
+ * @throws {unknown} Re-throws the supplied error when it is not an {@link ExpectedFailError}.
  */
 export declare function EXPECT_ERROR_DEFAULT_HANDLER(e: unknown): void;
 /**
@@ -76,8 +81,8 @@ export type ExpectFailAssertionFunction = (error: unknown) => PromiseOrValue<May
  *
  * Throws an ExpectedErrorOfSpecificTypeError on failures.
  *
- * @param expectedType - the class or constructor function that the error should be an instance of
- * @returns an assertion function that validates the error type via instanceof
+ * @param expectedType - The class or constructor function that the error should be an instance of.
+ * @returns An assertion function that validates the error type via instanceof.
  */
 export declare function expectFailAssertErrorType(expectedType: ClassType | ClassLikeType | typeof Error | any): ExpectFailAssertionFunction;
 /**
@@ -88,9 +93,9 @@ export declare function expectFailAssertErrorType(expectedType: ClassType | Clas
  * the thrown `ExpectedFailError` propagates and fails the test even though `errorFn` rejected
  * as expected — for that case use vitest's `await expect(...).rejects.toThrow(...)` instead.
  *
- * @param errorFn - function expected to throw an error (sync or async)
- * @param assertFailType - optional assertion to validate the type or content of the thrown error
- * @returns a promise that rejects with {@link ExpectedFailError} when the expected failure is verified, or with {@link UnexpectedSuccessFailureError} when `errorFn` resolves successfully
+ * @param errorFn - Function expected to throw an error (sync or async)
+ * @param assertFailType - Optional assertion to validate the type or content of the thrown error.
+ * @returns Rejects with {@link ExpectedFailError} when the expected failure is verified, or with {@link UnexpectedSuccessFailureError} when `errorFn` resolves successfully.
  *
  * @example
  * ```ts
@@ -123,7 +128,7 @@ export interface ShouldFailDoneCallback extends TestDoneCallback {
 /**
  * A test function for {@link shouldFail} that receives a {@link ShouldFailDoneCallback} to signal failure outcomes.
  */
-export type ShouldFailProvidesCallbackWithDone = (cb: ShouldFailDoneCallback) => void | undefined;
+export type ShouldFailProvidesCallbackWithDone = (cb: ShouldFailDoneCallback) => Maybe<void>;
 /**
  * A test function for {@link shouldFail} that returns its result directly (sync or async), without using a done callback.
  */
@@ -137,8 +142,8 @@ export type ShouldFailProvidesCallback = ShouldFailProvidesCallbackWithDone | Sh
  *
  * This is typically used in conjunction with failSuccessfully(), expectSuccessfulFail(), or expectFail().
  *
- * @param fn - the test function that is expected to throw an {@link ExpectedFailError}
- * @returns an async test function suitable for use with `it()`
+ * @param fn - The test function that is expected to throw an {@link ExpectedFailError}
+ * @returns An async test function suitable for use with `it()`
  */
 export declare function shouldFail(fn: ShouldFailProvidesCallback): () => Promise<unknown>;
 /**
@@ -166,6 +171,6 @@ export interface FakeDoneHandler extends TestDoneCallback, PromiseReference {
  * Calling the returned function with no arguments resolves the promise;
  * calling it with an error (or calling `.fail()`) rejects the promise.
  *
- * @returns a new {@link FakeDoneHandler} backed by a promise reference
+ * @returns A new {@link FakeDoneHandler} backed by a promise reference.
  */
 export declare function fakeDoneHandler(): FakeDoneHandler;

package/test/src/lib/shared/shared.function.d.ts

@@ -20,8 +20,8 @@ export type TestFunctionFixtureBuildTests<I> = (fn: I) => void;
  * The forwarded function delegates to the getter at call time, so the underlying implementation
  * can change between tests while test declarations remain stable.
  *
- * @param config - provides the getter for the function under test
- * @param buildTests - declares test cases using the forwarded function
+ * @param config - Provides the getter for the function under test.
+ * @param buildTests - Declares test cases using the forwarded function.
  */
 export declare function useTestFunctionFixture<I extends (...args: any[]) => O, O = any>(config: UseTestFunctionFixture<I, O>, buildTests: TestFunctionFixtureBuildTests<I>): void;
 /**
@@ -57,7 +57,7 @@ export type TestFunctionFixtureMapBuildTests<T extends UseTestFunctionMapObject>
  * Similar to {@link useTestFunctionFixture} but operates on a map of functions, allowing tests
  * to be declared against multiple related function implementations at once.
  *
- * @param config - provides getters for each named function under test
- * @param buildTests - declares test cases using the map of forwarded functions
+ * @param config - Provides getters for each named function under test.
+ * @param buildTests - Declares test cases using the map of forwarded functions.
  */
 export declare function useTestFunctionMapFixture<T extends UseTestFunctionMapObject>(config: UseTestFunctionMapFixture<T>, buildTests: TestFunctionFixtureMapBuildTests<T>): void;

package/test/src/lib/shared/shared.wrap.d.ts

@@ -28,7 +28,7 @@ export interface WrapTestContextConfig<W, F, E = any> {
     /**
      * Wraps the fixture. This occurs once before any tests execute.
      */
-    wrapFixture: (fixture: F) => W;
+    readonly wrapFixture: (fixture: F) => W;
     /**
      * Use for doing any setup that may be required on a per-test basis.
      *
@@ -36,38 +36,38 @@ export interface WrapTestContextConfig<W, F, E = any> {
      *
      * The setup can return an effect. This effect is passed to the teardown function later, if provided.
      */
-    setupWrap?: (wrap: W) => Promise<E>;
+    readonly setupWrap?: (wrap: W) => Promise<E>;
     /**
      * Use for cleaning up the instance before the next function.
      *
      * This occurs after every test, but after the fixture's instance has already been configured.
      */
-    teardownWrap?: (wrap: W, effect: E) => Promise<void>;
+    readonly teardownWrap?: (wrap: W, effect: E) => Promise<void>;
 }
 /**
  * Wraps the input TestContextFactory to emit another type of Fixture for tests.
  *
- * @param config - configuration specifying how to wrap fixtures and optional setup/teardown hooks
- * @returns a function that transforms a {@link TestContextFactory} of type `F` into one of type `W`
+ * @param config - Configuration specifying how to wrap fixtures and optional setup/teardown hooks.
+ * @returns Transforms a {@link TestContextFactory} of type `F` into one of type `W`
  */
 export declare function wrapTestContextFactory<W, F, E = any>(config: WrapTestContextConfig<W, F, E>): (factory: TestContextFactory<F>) => TestContextFactory<W>;
 export interface InstanceWrapTestContextConfig<I, W extends AbstractWrappedFixtureWithInstance<I, F>, F> extends Pick<WrapTestContextConfig<W, F>, 'wrapFixture'> {
     /**
      * Creates a new instance for the tests.
      */
-    makeInstance: (wrap: W) => I | Promise<I>;
+    readonly makeInstance: (wrap: W) => I | Promise<I>;
     /**
      * Use for doing any setup that may be required on a per-test basis.
      *
      * This occurs before every test, but after the fixture's instance has already been configured.
      */
-    setupInstance?: (instance: I, wrap: W) => void | Promise<void>;
+    readonly setupInstance?: (instance: I, wrap: W) => void | Promise<void>;
     /**
      * Use for cleaning up the instance before the next function.
      *
      * This occurs after every test, but after the fixture's instance has already been configured.
      */
-    teardownInstance?: (instance: I) => void | Promise<void>;
+    readonly teardownInstance?: (instance: I) => void | Promise<void>;
 }
 /**
  * Wraps a {@link TestContextFactory} to produce a fixture that manages its own instance lifecycle.
@@ -75,7 +75,7 @@ export interface InstanceWrapTestContextConfig<I, W extends AbstractWrappedFixtu
  * Built on top of {@link wrapTestContextFactory}, this variant automatically creates, sets, and tears down
  * an instance on the wrapped fixture for each test, using the provided {@link InstanceWrapTestContextConfig}.
  *
- * @param config - configuration for wrapping the fixture and managing instance lifecycle
- * @returns a function that transforms a {@link TestContextFactory} of type `F` into one of type `W`
+ * @param config - Configuration for wrapping the fixture and managing instance lifecycle.
+ * @returns Transforms a {@link TestContextFactory} of type `F` into one of type `W`
  */
 export declare function instanceWrapTestContextFactory<I, W extends AbstractWrappedFixtureWithInstance<I, F>, F>(config: InstanceWrapTestContextConfig<I, W, F>): (factory: TestContextFactory<F>) => TestContextFactory<W>;