@dereekb/util 13.11.14 → 13.11.15

package/test/index.cjs.js

@@ -219,8 +219,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Passes the error to the TestDoneCallback.
  *
- * @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
+ * @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) {
@@ -234,7 +234,7 @@ function _ts_generator$2(thisArg, body) {
  *
  * Used to create a promise reference that can be used to assert that a test function was called.
  *
- * @returns a new {@link TestDoneCallbackRef} with a done callback and underlying promise
+ * @returns A new {@link TestDoneCallbackRef} with a done callback and underlying promise.
  */ function testDoneCallbackRef() {
     var _promise = util.promiseReference();
     var done = function done(e) {
@@ -256,22 +256,22 @@ function _ts_generator$2(thisArg, body) {
  *
  * This also supports calling the input test with async, but still only returns when done is called.
  *
- * @example
+ * @param testFn - The callback-based test function that receives a done callback.
+ * @returns Promise-based wrapper function suitable for Vitest or other async test runners.
  *
+ * @example
+ * ```ts
  * // Before (Jasmine/Jest style):
  * it('test name', (done) => {
  *   // async test code
  *   done();
  * });
- *
  * // After (Vitest compatible):
  * it('test name', callbackTest((done) => {
  *   // async test code
  *   done();
  * }));
- *
- * @param testFn - the callback-based test function that receives a done callback
- * @returns a Promise-based wrapper function suitable for Vitest or other async test runners
+ * ```
  */ function callbackTest(testFn) {
     return function() {
         return _async_to_generator$2(function() {
@@ -341,8 +341,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @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}
+ * @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);
@@ -380,7 +380,7 @@ function _ts_generator$2(thisArg, body) {
  * 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
+ * @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 = null;
@@ -703,8 +703,8 @@ function _ts_generator$1(thisArg, body) {
 /**
  * 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
         return function(buildTests) {
@@ -766,8 +766,8 @@ function _ts_generator$1(thisArg, body) {
  * 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`
  */ function instanceWrapTestContextFactory(config) {
     return wrapTestContextFactory({
         wrapFixture: config.wrapFixture,
@@ -838,8 +838,8 @@ function _ts_generator$1(thisArg, body) {
  * 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.
  */ function useTestFunctionFixture(config, buildTests) {
     var fn = config.fn;
     var forward = util.forwardFunction(fn);
@@ -851,8 +851,8 @@ function _ts_generator$1(thisArg, body) {
  * 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.
  */ function useTestFunctionMapFixture(config, buildTests) {
     var forwardedFunctions = util.mapObjectMap(config.fns, function(fn) {
         return util.forwardFunction(fn);
@@ -1082,8 +1082,8 @@ function _ts_generator(thisArg, body) {
 /**
  * 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.
  */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
@@ -1094,7 +1094,8 @@ function _ts_generator(thisArg, body) {
  * 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.
  */ function failSuccessfully(message) {
     throw failSuccessfullyError(message);
 }
@@ -1111,8 +1112,8 @@ function _ts_generator(thisArg, body) {
 /**
  * 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.
  */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
@@ -1136,13 +1137,16 @@ function _ts_generator(thisArg, body) {
  * 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.
  */ function failTest(message) {
     throw failDueToSuccessError(message);
 }
 /**
  * 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.
  */ function failDueToSuccess() {
     throw failDueToSuccessError();
 }
@@ -1150,7 +1154,8 @@ function _ts_generator(thisArg, body) {
  * 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}.
  */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
@@ -1161,8 +1166,8 @@ function _ts_generator(thisArg, body) {
  *
  * 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.
  */ function expectFailAssertErrorType(expectedType) {
     return function(error) {
         if (!_instanceof(error, expectedType)) {
@@ -1178,9 +1183,9 @@ function _ts_generator(thisArg, body) {
  * 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
@@ -1237,8 +1242,8 @@ function expectSuccessfulFail(errorFn) {
  *
  * 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()`
  */ function shouldFail(fn) {
     var usesDoneCallback = fn.length > 0;
     // Return a function that checks arguments at runtime to avoid done callback deprecation warning
@@ -1309,7 +1314,7 @@ function itShouldFail(describeOrFn, fn) {
  * 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.
  */ function fakeDoneHandler() {
     var promiseRef = util.promiseReference();
     var doneHandler = promiseRef.resolve;
@@ -1513,9 +1518,9 @@ function _is_native_reflect_construct() {
     return JestExpectedErrorOfSpecificTypeError;
 }(ExpectedErrorOfSpecificTypeError);
 /**
- * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
+ * @param done - The test done callback to invoke with the failure error.
  *
- * @param done - the test done callback to invoke with the failure error
+ * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
  */ function failWithDoneDueToSuccess(done) {
     failWithTestDoneCallback(done, failDueToSuccessError());
 }

package/test/index.esm.js

@@ -217,8 +217,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Passes the error to the TestDoneCallback.
  *
- * @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
+ * @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) {
@@ -232,7 +232,7 @@ function _ts_generator$2(thisArg, body) {
  *
  * Used to create a promise reference that can be used to assert that a test function was called.
  *
- * @returns a new {@link TestDoneCallbackRef} with a done callback and underlying promise
+ * @returns A new {@link TestDoneCallbackRef} with a done callback and underlying promise.
  */ function testDoneCallbackRef() {
     var _promise = promiseReference();
     var done = function done(e) {
@@ -254,22 +254,22 @@ function _ts_generator$2(thisArg, body) {
  *
  * This also supports calling the input test with async, but still only returns when done is called.
  *
- * @example
+ * @param testFn - The callback-based test function that receives a done callback.
+ * @returns Promise-based wrapper function suitable for Vitest or other async test runners.
  *
+ * @example
+ * ```ts
  * // Before (Jasmine/Jest style):
  * it('test name', (done) => {
  *   // async test code
  *   done();
  * });
- *
  * // After (Vitest compatible):
  * it('test name', callbackTest((done) => {
  *   // async test code
  *   done();
  * }));
- *
- * @param testFn - the callback-based test function that receives a done callback
- * @returns a Promise-based wrapper function suitable for Vitest or other async test runners
+ * ```
  */ function callbackTest(testFn) {
     return function() {
         return _async_to_generator$2(function() {
@@ -339,8 +339,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @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}
+ * @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);
@@ -378,7 +378,7 @@ function _ts_generator$2(thisArg, body) {
  * 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
+ * @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 = null;
@@ -701,8 +701,8 @@ function _ts_generator$1(thisArg, body) {
 /**
  * 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
         return function(buildTests) {
@@ -764,8 +764,8 @@ function _ts_generator$1(thisArg, body) {
  * 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`
  */ function instanceWrapTestContextFactory(config) {
     return wrapTestContextFactory({
         wrapFixture: config.wrapFixture,
@@ -836,8 +836,8 @@ function _ts_generator$1(thisArg, body) {
  * 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.
  */ function useTestFunctionFixture(config, buildTests) {
     var fn = config.fn;
     var forward = forwardFunction(fn);
@@ -849,8 +849,8 @@ function _ts_generator$1(thisArg, body) {
  * 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.
  */ function useTestFunctionMapFixture(config, buildTests) {
     var forwardedFunctions = mapObjectMap(config.fns, function(fn) {
         return forwardFunction(fn);
@@ -1080,8 +1080,8 @@ function _ts_generator(thisArg, body) {
 /**
  * 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.
  */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
@@ -1092,7 +1092,8 @@ function _ts_generator(thisArg, body) {
  * 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.
  */ function failSuccessfully(message) {
     throw failSuccessfullyError(message);
 }
@@ -1109,8 +1110,8 @@ function _ts_generator(thisArg, body) {
 /**
  * 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.
  */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
@@ -1134,13 +1135,16 @@ function _ts_generator(thisArg, body) {
  * 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.
  */ function failTest(message) {
     throw failDueToSuccessError(message);
 }
 /**
  * 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.
  */ function failDueToSuccess() {
     throw failDueToSuccessError();
 }
@@ -1148,7 +1152,8 @@ function _ts_generator(thisArg, body) {
  * 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}.
  */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
@@ -1159,8 +1164,8 @@ function _ts_generator(thisArg, body) {
  *
  * 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.
  */ function expectFailAssertErrorType(expectedType) {
     return function(error) {
         if (!_instanceof(error, expectedType)) {
@@ -1176,9 +1181,9 @@ function _ts_generator(thisArg, body) {
  * 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
@@ -1235,8 +1240,8 @@ function expectSuccessfulFail(errorFn) {
  *
  * 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()`
  */ function shouldFail(fn) {
     var usesDoneCallback = fn.length > 0;
     // Return a function that checks arguments at runtime to avoid done callback deprecation warning
@@ -1307,7 +1312,7 @@ function itShouldFail(describeOrFn, fn) {
  * 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.
  */ function fakeDoneHandler() {
     var promiseRef = promiseReference();
     var doneHandler = promiseRef.resolve;
@@ -1511,9 +1516,9 @@ function _is_native_reflect_construct() {
     return JestExpectedErrorOfSpecificTypeError;
 }(ExpectedErrorOfSpecificTypeError);
 /**
- * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
+ * @param done - The test done callback to invoke with the failure error.
  *
- * @param done - the test done callback to invoke with the failure error
+ * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
  */ function failWithDoneDueToSuccess(done) {
     failWithTestDoneCallback(done, failDueToSuccessError());
 }

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.11.14",
+  "version": "13.11.15",
   "peerDependencies": {
-    "@dereekb/util": "13.11.14",
+    "@dereekb/util": "13.11.15",
     "make-error": "^1.3.6"
   },
   "exports": {

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

@@ -37,9 +37,9 @@ export declare class JestUnexpectedSuccessFailureError extends UnexpectedSuccess
 export declare class JestExpectedErrorOfSpecificTypeError extends ExpectedErrorOfSpecificTypeError {
 }
 /**
- * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
+ * @param done - The test done callback to invoke with the failure error.
  *
- * @param done - the test done callback to invoke with the failure error
+ * @deprecated Use failWithTestDoneCallback with failDueToSuccessError from shared instead. This is kept for backwards compatibility.
  */
 export declare function failWithDoneDueToSuccess(done: TestDoneCallback): void;
 /**

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

@@ -1,4 +1,4 @@
-import { type PromiseOrValue, type PromiseReference } from '@dereekb/util';
+import { type Maybe, type PromiseOrValue, type PromiseReference } from '@dereekb/util';
 /**
  * A done callback function used by test frameworks to signal that a test has completed.
  *
@@ -17,14 +17,14 @@ export type TestDoneCallback = ((...args: any[]) => any) & {
 /**
  * Passes the error to the TestDoneCallback.
  *
- * @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
+ * @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;
+export type TestProvidesCallbackWithDone = (cb: TestDoneCallback) => Maybe<void>;
 /**
  * A test function that either uses a done callback or returns a promise to signal completion.
  */
@@ -42,7 +42,7 @@ export type TestDoneCallbackRef = Omit<TestDoneCallback, 'fail'> & {
  *
  * Used to create a promise reference that can be used to assert that a test function was called.
  *
- * @returns a new {@link TestDoneCallbackRef} with a done callback and underlying promise
+ * @returns A new {@link TestDoneCallbackRef} with a done callback and underlying promise.
  */
 export declare function testDoneCallbackRef(): TestDoneCallbackRef;
 /**
@@ -51,24 +51,24 @@ export declare function testDoneCallbackRef(): TestDoneCallbackRef;
  *
  * This also supports calling the input test with async, but still only returns when done is called.
  *
- * @example
+ * @param testFn - The callback-based test function that receives a done callback.
+ * @returns Promise-based wrapper function suitable for Vitest or other async test runners.
  *
+ * @example
+ * ```ts
  * // Before (Jasmine/Jest style):
  * it('test name', (done) => {
  *   // async test code
  *   done();
  * });
- *
  * // After (Vitest compatible):
  * it('test name', callbackTest((done) => {
  *   // async test code
  *   done();
  * }));
- *
- * @param testFn - the callback-based test function that receives a done callback
- * @returns a Promise-based wrapper function suitable for Vitest or other async test runners
+ * ```
  */
-export declare function callbackTest(testFn: TestProvidesCallbackWithDone | ((cb: TestDoneCallback) => PromiseOrValue<void | undefined>)): () => Promise<void>;
+export declare function callbackTest(testFn: TestProvidesCallbackWithDone | ((cb: TestDoneCallback) => PromiseOrValue<Maybe<void>>)): () => Promise<void>;
 /**
  * A fixture instance that is generated new for each test run.
  */
@@ -134,35 +134,35 @@ export interface TestContextBuilderConfig<I, F extends TestContextFixture<I>, C>
     /**
      * Builds a config given the optional, partial input config. This is used across all tests.
      */
-    buildConfig: (config?: Partial<C>) => C;
+    readonly buildConfig: (config?: Partial<C>) => C;
     /**
      * Builds a new fixture to use across all encapsulated tests.
      */
-    buildFixture: (config: C) => F;
+    readonly buildFixture: (config: C) => F;
     /**
      * Arbitrary before each function, called before the instance is setup.
      */
-    beforeEach?: () => Promise<void>;
+    readonly beforeEach?: () => Promise<void>;
     /**
      * Use for building an instance.
      *
      * When the promise resolves it should be ready to be used by the test being executed.
      */
-    setupInstance: (config: C) => Promise<I>;
+    readonly setupInstance: (config: C) => Promise<I>;
     /**
      * Use for cleaning up the instance before the next test.
      */
-    teardownInstance: (instance: I, config: C) => Promise<void>;
+    readonly teardownInstance: (instance: I, config: C) => Promise<void>;
     /**
      * Arbitrary after each function.
      */
-    afterEach?: () => Promise<void>;
+    readonly afterEach?: () => Promise<void>;
 }
 /**
  * Creates a TestContextBuilderFunction given the input builder.
  *
- * @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}
+ * @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>;
 /**
@@ -181,6 +181,6 @@ export interface UseContextFixture<C extends TestContextFixture<I>, I> {
  * 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
+ * @param config - Fixture, test builder, and instance lifecycle functions.
  */
 export declare function useTestContextFixture<C extends TestContextFixture<I>, I>(config: UseContextFixture<C, I>): void;