@dereekb/util 13.0.7 → 13.2.0

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

@@ -9,13 +9,31 @@ import { type TestDoneCallback } from './shared';
  */
 export declare class ExpectedFailError extends BaseError {
 }
+/**
+ * Creates an {@link ExpectedFailError} without throwing it, for use in deferred error handling.
+ *
+ * @param message - optional error message
+ */
 export declare function failSuccessfullyError(message?: string): ExpectedFailError;
+/**
+ * Throws an {@link ExpectedFailError} to signal that a test reached the expected failure point.
+ *
+ * Used within {@link shouldFail} or {@link expectSuccessfulFail} to indicate that the expected
+ * error path was taken successfully.
+ *
+ * @param message - optional error message
+ */
 export declare function failSuccessfully(message?: string): never;
 /**
  * Error thrown when success occurs when it should not have.
  */
 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
+ */
 export declare function failDueToSuccessError(message?: string): UnexpectedSuccessFailureError;
 /**
  * Error thrown when the error type was different than the expected type.
@@ -25,8 +43,22 @@ export declare class ExpectedErrorOfSpecificTypeError extends BaseError {
     readonly expectedType?: Maybe<ClassLikeType | string>;
     constructor(encounteredType: unknown, expectedType?: Maybe<ClassLikeType | string>);
 }
+/**
+ * Fails the current test by throwing an {@link UnexpectedSuccessFailureError}.
+ * Use when a code path should not have been reached.
+ *
+ * @param message - optional error message
+ */
 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.
+ */
 export declare function failDueToSuccess(): never;
+/**
+ * Default error handler for {@link expectSuccessfulFail} that passes through {@link ExpectedFailError}
+ * instances and re-throws all other errors.
+ */
 export declare function EXPECT_ERROR_DEFAULT_HANDLER(e: unknown): void;
 /**
  * Used to assert additional information about the expected error.
@@ -39,45 +71,76 @@ export type ExpectFailAssertionFunction = (error: unknown) => PromiseOrValue<May
  *
  * Throws an ExpectedErrorOfSpecificTypeError on failures.
  *
- * @param expectedType
- * @returns
+ * @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;
 /**
  * Function that expects any failure to be thrown, then throws an ExpectedFailError.
  *
- * @param errorFn
- * @param handleError
+ * @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
  */
 export declare function expectFail(errorFn: () => void, assertFailType?: ExpectFailAssertionFunction): void;
 export declare function expectFail(errorFn: () => Promise<void>, assertFailType?: ExpectFailAssertionFunction): Promise<void>;
 /**
  * Function that expects an ExpectedFailError to be thrown.
  *
- * @param errorFn
- * @param handleError
+ * @param errorFn - function expected to throw (sync or async); if it succeeds, the test fails
+ * @param handleError - optional custom error handler; defaults to {@link EXPECT_ERROR_DEFAULT_HANDLER}
  */
 export declare function expectSuccessfulFail(errorFn: () => void, handleError?: (e: unknown) => void): void;
 export declare function expectSuccessfulFail(errorFn: () => Promise<void>, handleError?: (e: unknown) => void): Promise<void>;
+/**
+ * Extended done callback for {@link shouldFail} tests that adds a {@link failSuccessfully} convenience method.
+ */
 export interface ShouldFailDoneCallback extends TestDoneCallback {
     failSuccessfully(): void;
 }
+/**
+ * A test function for {@link shouldFail} that receives a {@link ShouldFailDoneCallback} to signal failure outcomes.
+ */
 export type ShouldFailProvidesCallbackWithDone = (cb: ShouldFailDoneCallback) => void | undefined;
+/**
+ * A test function for {@link shouldFail} that returns its result directly (sync or async), without using a done callback.
+ */
 export type ShouldFailProvidesCallbackWithResult = () => PromiseOrValue<unknown>;
+/**
+ * Union type for test functions accepted by {@link shouldFail}. Supports both done-callback and promise-based patterns.
+ */
 export type ShouldFailProvidesCallback = ShouldFailProvidesCallbackWithDone | ShouldFailProvidesCallbackWithResult;
 /**
  * Used to wrap a testing function and watch for ExpectedFailError errors in order to pass the test. Other exceptions are treated normally as failures.
  *
  * This is typically used in conjunction with failSuccessfully(), expectSuccessfulFail(), or expectFail().
  *
- * @param fn
- * @param strict
- * @returns
+ * @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>;
+/**
+ * Convenience wrapper that registers an `it()` test case which is expected to fail.
+ *
+ * Automatically generates a "should fail" description and wraps the test function with {@link shouldFail}.
+ *
+ * @param describeOrFn - either a description suffix (e.g., "when input is null") or the test function directly
+ * @param fn - the test function, if a description string was provided as the first argument
+ */
 export declare function itShouldFail(fn: ShouldFailProvidesCallback): void;
 export declare function itShouldFail(describe: string, fn: ShouldFailProvidesCallback): void;
+/**
+ * A simulated done callback that bridges callback-based test patterns to promises.
+ *
+ * Calling the handler or its `fail` method resolves or rejects the underlying promise,
+ * allowing callback-style tests to be awaited.
+ */
 export interface FakeDoneHandler extends TestDoneCallback, PromiseReference {
     _ref: PromiseReference;
 }
+/**
+ * Creates a {@link FakeDoneHandler} that converts done-callback invocations into promise resolution/rejection.
+ *
+ * Calling the returned function with no arguments resolves the promise;
+ * calling it with an error (or calling `.fail()`) rejects the promise.
+ */
 export declare function fakeDoneHandler(): FakeDoneHandler;

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

@@ -1,25 +1,63 @@
 import { type Getter } from '@dereekb/util';
+/**
+ * A getter that returns the function under test. Allows the function reference to be swapped
+ * between tests without re-declaring test cases.
+ */
 export type UseTestFunctionFixtureFunctionGetter<I extends (...args: any[]) => O, O = any> = Getter<I>;
+/**
+ * Configuration for {@link useTestFunctionFixture} providing a getter for the function under test.
+ */
 export interface UseTestFunctionFixture<I extends (...args: any[]) => O, O = any> {
     fn: Getter<I>;
 }
+/**
+ * Function that declares test cases using the provided forwarded function reference.
+ */
 export type TestFunctionFixtureBuildTests<I> = (fn: I) => void;
 /**
- * Creates a test context and configurations that provides a function to build tests based on the configuration.
+ * Sets up a test fixture that forwards calls to a lazily-resolved function reference.
+ *
+ * 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
  */
 export declare function useTestFunctionFixture<I extends (...args: any[]) => O, O = any>(config: UseTestFunctionFixture<I, O>, buildTests: TestFunctionFixtureBuildTests<I>): void;
+/**
+ * A record of named functions, used as the shape for multi-function test fixtures.
+ */
 export type UseTestFunctionMapObject = Record<string, (...args: any[]) => any>;
+/**
+ * Configuration for {@link useTestFunctionMapFixture} providing getters for multiple named functions.
+ */
 export type UseTestFunctionMapFixture<T extends UseTestFunctionMapObject> = {
     fns: UseTestFunctionMapFixtureGetterFunctions<T>;
 };
+/**
+ * Maps each key in `T` to its corresponding function getter type, filtering out non-getter entries.
+ */
 export type UseTestFunctionMapFixtureGetterFunctions<T extends UseTestFunctionMapObject> = {
     [K in keyof T]: T[K] extends UseTestFunctionFixtureFunctionGetter<infer I, infer O> ? T[K] : never;
 };
+/**
+ * Maps each key in `T` to the unwrapped function type returned by its getter.
+ * This is the shape of the object passed to test-building functions.
+ */
 export type UseTestFunctionMapFixtureFunctions<T extends UseTestFunctionMapObject> = {
     [K in keyof T]: T[K] extends UseTestFunctionFixtureFunctionGetter<infer I, infer O> ? I : never;
 };
+/**
+ * Function that declares test cases using the provided map of forwarded function references.
+ */
 export type TestFunctionFixtureMapBuildTests<T extends UseTestFunctionMapObject> = (fixture: UseTestFunctionMapFixtureFunctions<T>) => void;
 /**
- * Creates a test context and configurations that provides a function to build tests based on the configuration.
+ * Sets up a test fixture for multiple named functions, forwarding each to its lazily-resolved getter.
+ *
+ * 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
  */
 export declare function useTestFunctionMapFixture<T extends UseTestFunctionMapObject>(config: UseTestFunctionMapFixture<T>, buildTests: TestFunctionFixtureMapBuildTests<T>): void;

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

@@ -1,8 +1,18 @@
 import { AbstractTestContextFixture, type TestContextFactory } from './shared';
+/**
+ * Abstract base class for wrapping an existing test fixture to add additional context or behavior.
+ *
+ * Subclasses extend this to provide a richer test API while delegating to the underlying fixture.
+ */
 export declare abstract class AbstractWrappedFixture<F> {
     readonly fixture: F;
     constructor(fixture: F);
 }
+/**
+ * Abstract base class for a wrapped fixture that also manages its own test instance.
+ *
+ * Combines fixture wrapping with per-test instance lifecycle management from {@link AbstractTestContextFixture}.
+ */
 export declare abstract class AbstractWrappedFixtureWithInstance<I, F> extends AbstractTestContextFixture<I> {
     readonly parent: F;
     constructor(parent: F);
@@ -37,7 +47,7 @@ export interface WrapTestContextConfig<W, F, E = any> {
 /**
  * Wraps the input TestContextFactory to emit another type of Fixture for tests.
  *
- * @returns
+ * @returns a function that 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'> {
@@ -58,4 +68,13 @@ export interface InstanceWrapTestContextConfig<I, W extends AbstractWrappedFixtu
      */
     teardownInstance?: (instance: I) => void | Promise<void>;
 }
+/**
+ * Wraps a {@link TestContextFactory} to produce a fixture that manages its own instance lifecycle.
+ *
+ * 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`
+ */
 export declare function instanceWrapTestContextFactory<I, W extends AbstractWrappedFixtureWithInstance<I, F>, F>(config: InstanceWrapTestContextConfig<I, W, F>): (factory: TestContextFactory<F>) => TestContextFactory<W>;