@dereekb/util 13.0.7 → 13.1.0

package/src/lib/value/vector.d.ts

@@ -1,40 +1,102 @@
 import { type Maybe } from './maybe.type';
+/**
+ * A 2D point or size with x and y components.
+ */
 export interface Vector {
     x: number;
     y: number;
 }
+/**
+ * A {@link Vector} represented as a `[x, y]` tuple.
+ */
 export type VectorTuple = [number, number];
+/**
+ * Safely compares two optional vectors for equality.
+ *
+ * If both values are non-nullish, delegates to {@link vectorsAreEqual}.
+ * If both are nullish, uses strict equality (`===`).
+ *
+ * @param a - first vector
+ * @param b - second vector
+ */
 export declare function isSameVector(a: Maybe<Partial<Vector>>, b: Maybe<Partial<Vector>>): boolean;
+/**
+ * Returns `true` if both vectors have the same `x` and `y` values using strict equality.
+ *
+ * @param a - first vector
+ * @param b - second vector
+ */
 export declare function vectorsAreEqual(a: Partial<Vector>, b: Partial<Vector>): boolean;
 /**
- * Function that resizes a vector.
+ * Function that transforms a {@link Vector} into a new vector, typically used for resizing or clamping dimensions.
  */
 export type VectorResizeFunction = (input: Vector) => Vector;
 /**
- * Creates a VectorResizeFunction that returns the larger x/y values from the input and the minimum vector.
+ * Creates a {@link VectorResizeFunction} that enforces minimum x/y dimensions.
  *
- * @param min
- * @returns
+ * For each axis, if a minimum is specified, the result uses whichever value is larger (input or minimum).
+ * If a minimum is not specified for an axis, the input value is passed through unchanged.
+ *
+ * @param minSize - the minimum dimensions to enforce
+ *
+ * @example
+ * ```ts
+ * const resize = vectorMinimumSizeResizeFunction({ x: 5 });
+ * resize({ x: 3, y: 10 });
+ * // { x: 5, y: 10 }
+ * ```
  */
 export declare function vectorMinimumSizeResizeFunction(minSize: Partial<Vector>): VectorResizeFunction;
+/**
+ * The origin point of a {@link Rectangle}, typically the bottom-left corner.
+ */
 export type RectangleOrigin = Vector;
+/**
+ * The top-right (north-east) corner of a {@link Rectangle}.
+ */
 export type TopRightCorner = Vector;
+/**
+ * The bottom-left (south-west) corner of a {@link Rectangle}.
+ */
 export type BottomLeftCorner = Vector;
+/**
+ * An axis-aligned rectangle defined by its top-right and bottom-left corners.
+ */
 export interface Rectangle {
     /**
-     * Upper-Right/North-East corner.
+     * Upper-right / north-east corner.
      */
     tr: TopRightCorner;
     /**
-     * Bottom-Left/South-West corner.
+     * Bottom-left / south-west corner.
      */
     bl: BottomLeftCorner;
 }
 /**
- * Returns true if the input vector overlaps another.
+ * Returns `true` if the two rectangles overlap (share any interior area).
  *
- * @param a
- * @param b
+ * Degenerate rectangles (where corners coincide on an axis) are considered non-overlapping.
+ *
+ * @param a - first rectangle
+ * @param b - second rectangle
+ *
+ * @example
+ * ```ts
+ * const a: Rectangle = { tr: { x: 10, y: 10 }, bl: { x: 0, y: 0 } };
+ * const b: Rectangle = { tr: { x: 5, y: 5 }, bl: { x: 0, y: 0 } };
+ *
+ * rectangleOverlapsRectangle(a, b);
+ * // true
+ * ```
  */
 export declare function rectangleOverlapsRectangle(a: Rectangle, b: Rectangle): boolean;
+/**
+ * Computes the intersection rectangle of two axis-aligned rectangles.
+ *
+ * Returns the overlapping {@link Rectangle} if the two inputs intersect,
+ * or `undefined` if they do not overlap.
+ *
+ * @param a - first rectangle
+ * @param b - second rectangle
+ */
 export declare function getOverlappingRectangle(a: Rectangle, b: Rectangle): Maybe<Rectangle>;

package/test/index.cjs.js

@@ -218,8 +218,8 @@ function _ts_generator$2(thisArg, body) {
 }
 /**
  * Passes the error to the TestDoneCallback.
- * @param done
- * @param e
+ * @param done - the test framework's done callback to signal completion or failure
+ * @param e - the error to pass to the callback; defaults to a generic error
  */ function failWithTestDoneCallback(done) {
     var e = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Error('failed test');
     if (done.fail != null) {
@@ -335,8 +335,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @param builder
- * @returns
+ * @param builder - configuration defining how to build configs, fixtures, and manage instance lifecycle
+ * @returns a builder function that accepts optional partial config and produces a {@link TestContextFactory}
  */ function testContextBuilder(builder) {
     return function(inputConfig) {
         var config = builder.buildConfig(inputConfig);
@@ -369,7 +369,12 @@ function _ts_generator$2(thisArg, body) {
     };
 }
 /**
- * Creates a test context and configurations that will initialize an instance
+ * Registers beforeEach/afterEach hooks that manage instance lifecycle for a test context fixture.
+ *
+ * Before each test, a new instance is created and set on the fixture. After each test, the instance
+ * is cleared and optionally destroyed. Test declarations happen synchronously between the hooks.
+ *
+ * @param config - fixture, test builder, and instance lifecycle functions
  */ function useTestContextFixture(config) {
     var buildTests = config.buildTests, fixture = config.fixture, initInstance = config.initInstance, destroyInstance = config.destroyInstance;
     var clearInstance;
@@ -665,12 +670,20 @@ function _ts_generator$1(thisArg, body) {
         };
     }
 }
-var AbstractWrappedFixture = function AbstractWrappedFixture(fixture) {
+/**
+ * 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.
+ */ var AbstractWrappedFixture = function AbstractWrappedFixture(fixture) {
     _class_call_check$3(this, AbstractWrappedFixture);
     _define_property$1(this, "fixture", void 0);
     this.fixture = fixture;
 };
-var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestContextFixture) {
+/**
+ * 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}.
+ */ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestContextFixture) {
     _inherits$3(AbstractWrappedFixtureWithInstance, AbstractTestContextFixture);
     function AbstractWrappedFixtureWithInstance(parent) {
         _class_call_check$3(this, AbstractWrappedFixtureWithInstance);
@@ -684,7 +697,7 @@ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestCont
 /**
  * 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
         return function(buildTests) {
@@ -739,7 +752,15 @@ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestCont
         };
     };
 }
-function instanceWrapTestContextFactory(config) {
+/**
+ * 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`
+ */ function instanceWrapTestContextFactory(config) {
     return wrapTestContextFactory({
         wrapFixture: config.wrapFixture,
         setupWrap: function setupWrap(wrap) {
@@ -804,14 +825,26 @@ function instanceWrapTestContextFactory(config) {
 }
 
 /**
- * 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
  */ function useTestFunctionFixture(config, buildTests) {
     var fn = config.fn;
     var forward = util.forwardFunction(fn);
     buildTests(forward);
 }
 /**
- * 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
  */ function useTestFunctionMapFixture(config, buildTests) {
     var forwardedFunctions = util.mapObjectMap(config.fns, function(fn) {
         return util.forwardFunction(fn);
@@ -1037,10 +1070,21 @@ function _ts_generator(thisArg, body) {
     }
     return ExpectedFailError;
 }(makeError.BaseError);
-function failSuccessfullyError(message) {
+/**
+ * Creates an {@link ExpectedFailError} without throwing it, for use in deferred error handling.
+ *
+ * @param message - optional error message
+ */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
-function failSuccessfully(message) {
+/**
+ * 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
+ */ function failSuccessfully(message) {
     throw failSuccessfullyError(message);
 }
 /**
@@ -1053,7 +1097,11 @@ function failSuccessfully(message) {
     }
     return UnexpectedSuccessFailureError;
 }(makeError.BaseError);
-function failDueToSuccessError(message) {
+/**
+ * Creates an {@link UnexpectedSuccessFailureError} without throwing it.
+ *
+ * @param message - optional error message; defaults to a standard "expected an error" message
+ */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
 /**
@@ -1072,13 +1120,24 @@ function failDueToSuccessError(message) {
     }
     return ExpectedErrorOfSpecificTypeError;
 }(makeError.BaseError);
-function failTest(message) {
+/**
+ * Fails the current test by throwing an {@link UnexpectedSuccessFailureError}.
+ * Use when a code path should not have been reached.
+ *
+ * @param message - optional error message
+ */ function failTest(message) {
     throw failDueToSuccessError(message);
 }
-function failDueToSuccess() {
+/**
+ * Throws an {@link UnexpectedSuccessFailureError} with a default message.
+ * Typically called when an operation succeeds but was expected to throw.
+ */ function failDueToSuccess() {
     throw failDueToSuccessError();
 }
-function EXPECT_ERROR_DEFAULT_HANDLER(e) {
+/**
+ * Default error handler for {@link expectSuccessfulFail} that passes through {@link ExpectedFailError}
+ * instances and re-throws all other errors.
+ */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
     }
@@ -1088,8 +1147,8 @@ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
  *
  * 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
  */ function expectFailAssertErrorType(expectedType) {
     return function(error) {
         if (!_instanceof(error, expectedType)) {
@@ -1138,9 +1197,8 @@ function expectSuccessfulFail(errorFn) {
  *
  * 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()`
  */ function shouldFail(fn) {
     var usesDoneCallback = fn.length > 0;
     // Return a function that checks arguments at runtime to avoid done callback deprecation warning
@@ -1205,7 +1263,12 @@ function itShouldFail(describeOrFn, fn) {
     }
     it(description, shouldFail(fn));
 }
-function fakeDoneHandler() {
+/**
+ * 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.
+ */ function fakeDoneHandler() {
     var promiseRef = util.promiseReference();
     var doneHandler = promiseRef.resolve;
     var failHandler = function failHandler(e) {

package/test/index.esm.js

@@ -216,8 +216,8 @@ function _ts_generator$2(thisArg, body) {
 }
 /**
  * Passes the error to the TestDoneCallback.
- * @param done
- * @param e
+ * @param done - the test framework's done callback to signal completion or failure
+ * @param e - the error to pass to the callback; defaults to a generic error
  */ function failWithTestDoneCallback(done) {
     var e = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Error('failed test');
     if (done.fail != null) {
@@ -333,8 +333,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @param builder
- * @returns
+ * @param builder - configuration defining how to build configs, fixtures, and manage instance lifecycle
+ * @returns a builder function that accepts optional partial config and produces a {@link TestContextFactory}
  */ function testContextBuilder(builder) {
     return function(inputConfig) {
         var config = builder.buildConfig(inputConfig);
@@ -367,7 +367,12 @@ function _ts_generator$2(thisArg, body) {
     };
 }
 /**
- * Creates a test context and configurations that will initialize an instance
+ * Registers beforeEach/afterEach hooks that manage instance lifecycle for a test context fixture.
+ *
+ * Before each test, a new instance is created and set on the fixture. After each test, the instance
+ * is cleared and optionally destroyed. Test declarations happen synchronously between the hooks.
+ *
+ * @param config - fixture, test builder, and instance lifecycle functions
  */ function useTestContextFixture(config) {
     var buildTests = config.buildTests, fixture = config.fixture, initInstance = config.initInstance, destroyInstance = config.destroyInstance;
     var clearInstance;
@@ -663,12 +668,20 @@ function _ts_generator$1(thisArg, body) {
         };
     }
 }
-var AbstractWrappedFixture = function AbstractWrappedFixture(fixture) {
+/**
+ * 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.
+ */ var AbstractWrappedFixture = function AbstractWrappedFixture(fixture) {
     _class_call_check$3(this, AbstractWrappedFixture);
     _define_property$1(this, "fixture", void 0);
     this.fixture = fixture;
 };
-var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestContextFixture) {
+/**
+ * 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}.
+ */ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestContextFixture) {
     _inherits$3(AbstractWrappedFixtureWithInstance, AbstractTestContextFixture);
     function AbstractWrappedFixtureWithInstance(parent) {
         _class_call_check$3(this, AbstractWrappedFixtureWithInstance);
@@ -682,7 +695,7 @@ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestCont
 /**
  * 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
         return function(buildTests) {
@@ -737,7 +750,15 @@ var AbstractWrappedFixtureWithInstance = /*#__PURE__*/ function(AbstractTestCont
         };
     };
 }
-function instanceWrapTestContextFactory(config) {
+/**
+ * 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`
+ */ function instanceWrapTestContextFactory(config) {
     return wrapTestContextFactory({
         wrapFixture: config.wrapFixture,
         setupWrap: function setupWrap(wrap) {
@@ -802,14 +823,26 @@ function instanceWrapTestContextFactory(config) {
 }
 
 /**
- * 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
  */ function useTestFunctionFixture(config, buildTests) {
     var fn = config.fn;
     var forward = forwardFunction(fn);
     buildTests(forward);
 }
 /**
- * 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
  */ function useTestFunctionMapFixture(config, buildTests) {
     var forwardedFunctions = mapObjectMap(config.fns, function(fn) {
         return forwardFunction(fn);
@@ -1035,10 +1068,21 @@ function _ts_generator(thisArg, body) {
     }
     return ExpectedFailError;
 }(BaseError);
-function failSuccessfullyError(message) {
+/**
+ * Creates an {@link ExpectedFailError} without throwing it, for use in deferred error handling.
+ *
+ * @param message - optional error message
+ */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
-function failSuccessfully(message) {
+/**
+ * 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
+ */ function failSuccessfully(message) {
     throw failSuccessfullyError(message);
 }
 /**
@@ -1051,7 +1095,11 @@ function failSuccessfully(message) {
     }
     return UnexpectedSuccessFailureError;
 }(BaseError);
-function failDueToSuccessError(message) {
+/**
+ * Creates an {@link UnexpectedSuccessFailureError} without throwing it.
+ *
+ * @param message - optional error message; defaults to a standard "expected an error" message
+ */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
 /**
@@ -1070,13 +1118,24 @@ function failDueToSuccessError(message) {
     }
     return ExpectedErrorOfSpecificTypeError;
 }(BaseError);
-function failTest(message) {
+/**
+ * Fails the current test by throwing an {@link UnexpectedSuccessFailureError}.
+ * Use when a code path should not have been reached.
+ *
+ * @param message - optional error message
+ */ function failTest(message) {
     throw failDueToSuccessError(message);
 }
-function failDueToSuccess() {
+/**
+ * Throws an {@link UnexpectedSuccessFailureError} with a default message.
+ * Typically called when an operation succeeds but was expected to throw.
+ */ function failDueToSuccess() {
     throw failDueToSuccessError();
 }
-function EXPECT_ERROR_DEFAULT_HANDLER(e) {
+/**
+ * Default error handler for {@link expectSuccessfulFail} that passes through {@link ExpectedFailError}
+ * instances and re-throws all other errors.
+ */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
     }
@@ -1086,8 +1145,8 @@ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
  *
  * 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
  */ function expectFailAssertErrorType(expectedType) {
     return function(error) {
         if (!_instanceof(error, expectedType)) {
@@ -1136,9 +1195,8 @@ function expectSuccessfulFail(errorFn) {
  *
  * 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()`
  */ function shouldFail(fn) {
     var usesDoneCallback = fn.length > 0;
     // Return a function that checks arguments at runtime to avoid done callback deprecation warning
@@ -1203,7 +1261,12 @@ function itShouldFail(describeOrFn, fn) {
     }
     it(description, shouldFail(fn));
 }
-function fakeDoneHandler() {
+/**
+ * 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.
+ */ function fakeDoneHandler() {
     var promiseRef = promiseReference();
     var doneHandler = promiseRef.resolve;
     var failHandler = function failHandler(e) {

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.0.7",
+  "version": "13.1.0",
   "peerDependencies": {
-    "@dereekb/util": "13.0.7",
+    "@dereekb/util": "13.1.0",
     "make-error": "^1.3.0"
   },
   "exports": {

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

@@ -16,12 +16,22 @@ export type TestDoneCallback = ((...args: any[]) => any) & {
 };
 /**
  * Passes the error to the TestDoneCallback.
- * @param done
- * @param e
+ * @param done - the test framework's done callback to signal completion or failure
+ * @param e - the error to pass to the callback; defaults to a generic error
  */
 export declare function failWithTestDoneCallback(done: TestDoneCallback, e?: unknown): void;
+/**
+ * A test function that receives a done callback to signal completion.
+ */
 export type TestProvidesCallbackWithDone = (cb: TestDoneCallback) => void | undefined;
+/**
+ * A test function that either uses a done callback or returns a promise to signal completion.
+ */
 export type TestProvidesCallback = TestProvidesCallbackWithDone | (() => Promise<unknown>);
+/**
+ * Reference wrapper around a {@link TestDoneCallback} that exposes the underlying promise,
+ * allowing callers to await the done signal.
+ */
 export type TestDoneCallbackRef = Omit<TestDoneCallback, 'fail'> & {
     readonly _promise: PromiseReference<void>;
     readonly done: TestDoneCallback;
@@ -65,6 +75,9 @@ export type TestFixtureInstance<I> = I;
 export interface TestFixture<I> {
     readonly instance: TestFixtureInstance<I>;
 }
+/**
+ * Cleanup function returned by {@link TestContextFixture.setInstance} to clear the current instance after a test completes.
+ */
 export type TestContextFixtureClearInstanceFunction = () => void;
 /**
  * TestFixture with additional functions that the TestContextFactory sees for managing the instance.
@@ -96,6 +109,10 @@ export declare abstract class AbstractChildTestContextFixture<I, P extends TestC
     readonly parent: P;
     constructor(parent: P);
 }
+/**
+ * Function that declares tests using the provided fixture. Called during test suite setup
+ * to register test cases that will later run against fresh fixture instances.
+ */
 export type BuildTestsWithContextFunction<F> = (fixture: F) => void;
 /**
  * Used for tests to execute a number of tests using the fixture.
@@ -138,10 +155,14 @@ export interface TestContextBuilderConfig<I, F extends TestContextFixture<I>, C>
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @param builder
- * @returns
+ * @param builder - configuration defining how to build configs, fixtures, and manage instance lifecycle
+ * @returns a builder function that accepts optional partial config and produces a {@link TestContextFactory}
  */
 export declare function testContextBuilder<I, F extends TestContextFixture<I>, C>(builder: TestContextBuilderConfig<I, F, C>): TestContextBuilderFunction<I, F, C>;
+/**
+ * Configuration for {@link useTestContextFixture} that defines how to initialize and destroy
+ * test instances, along with the fixture and test-building function.
+ */
 export interface UseContextFixture<C extends TestContextFixture<I>, I> {
     readonly fixture: C;
     readonly buildTests: BuildTestsWithContextFunction<C>;
@@ -149,6 +170,11 @@ export interface UseContextFixture<C extends TestContextFixture<I>, I> {
     destroyInstance?(instance: I): PromiseOrValue<void>;
 }
 /**
- * Creates a test context and configurations that will initialize an instance
+ * Registers beforeEach/afterEach hooks that manage instance lifecycle for a test context fixture.
+ *
+ * Before each test, a new instance is created and set on the fixture. After each test, the instance
+ * is cleared and optionally destroyed. Test declarations happen synchronously between the hooks.
+ *
+ * @param config - fixture, test builder, and instance lifecycle functions
  */
 export declare function useTestContextFixture<C extends TestContextFixture<I>, I>(config: UseContextFixture<C, I>): void;