@dereekb/util 13.3.1 → 13.4.1

package/test/index.cjs.js

@@ -218,6 +218,7 @@ 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
  */ function failWithTestDoneCallback(done) {
@@ -232,6 +233,8 @@ function _ts_generator$2(thisArg, body) {
  * Creates a new TestDoneCallbackRef.
  *
  * 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
  */ function testDoneCallbackRef() {
     var _promise = util.promiseReference();
     var done = function done(e) {
@@ -266,6 +269,9 @@ function _ts_generator$2(thisArg, body) {
  *   // 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() {
@@ -697,6 +703,7 @@ 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
@@ -705,7 +712,8 @@ function _ts_generator$1(thisArg, body) {
                 var wrap = config.wrapFixture(inputFixture);
                 var effect;
                 // add before each
-                if (config.setupWrap != null) {
+                var setupWrap = config.setupWrap, teardownWrap = config.teardownWrap;
+                if (setupWrap != null) {
                     beforeEach(function() {
                         return _async_to_generator$1(function() {
                             return _ts_generator$1(this, function(_state) {
@@ -713,7 +721,7 @@ function _ts_generator$1(thisArg, body) {
                                     case 0:
                                         return [
                                             4,
-                                            config.setupWrap(wrap)
+                                            setupWrap(wrap)
                                         ];
                                     case 1:
                                         effect = _state.sent();
@@ -728,7 +736,7 @@ function _ts_generator$1(thisArg, body) {
                 // add tests
                 buildTests(wrap);
                 // add after each
-                if (config.teardownWrap != null) {
+                if (teardownWrap != null) {
                     afterEach(function() {
                         return _async_to_generator$1(function() {
                             return _ts_generator$1(this, function(_state) {
@@ -736,7 +744,7 @@ function _ts_generator$1(thisArg, body) {
                                     case 0:
                                         return [
                                             4,
-                                            config.teardownWrap(wrap, effect)
+                                            teardownWrap(wrap, effect)
                                         ];
                                     case 1:
                                         _state.sent();
@@ -801,7 +809,7 @@ function _ts_generator$1(thisArg, body) {
                 return _ts_generator$1(this, function(_state) {
                     switch(_state.label){
                         case 0:
-                            deleteInstanceEffect === null || deleteInstanceEffect === void 0 ? void 0 : deleteInstanceEffect();
+                            deleteInstanceEffect();
                             if (!config.teardownInstance) return [
                                 3,
                                 2
@@ -1074,6 +1082,7 @@ 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
  */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
@@ -1101,6 +1110,7 @@ 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
  */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
@@ -1137,6 +1147,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
  */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
@@ -1156,7 +1168,13 @@ function _ts_generator(thisArg, body) {
         }
     };
 }
-function expectFail(errorFn, assertFailType) {
+/**
+ * Function that expects any failure to be thrown, then throws an ExpectedFailError.
+ *
+ * @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 resolves when the expected failure is verified
+ */ function expectFail(errorFn, assertFailType) {
     function handleError(e) {
         if (_instanceof(e, UnexpectedSuccessFailureError)) {
             throw e;
@@ -1178,6 +1196,7 @@ function expectFail(errorFn, assertFailType) {
     } catch (e) {
         handleError(e);
     }
+    return Promise.resolve();
 }
 function expectSuccessfulFail(errorFn) {
     var handleError = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : EXPECT_ERROR_DEFAULT_HANDLER;
@@ -1268,6 +1287,8 @@ 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
  */ function fakeDoneHandler() {
     var promiseRef = util.promiseReference();
     var doneHandler = promiseRef.resolve;
@@ -1472,6 +1493,8 @@ function _is_native_reflect_construct() {
 }(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
  */ function failWithDoneDueToSuccess(done) {
     failWithTestDoneCallback(done, failDueToSuccessError());
 }

package/test/index.esm.js

@@ -216,6 +216,7 @@ 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
  */ function failWithTestDoneCallback(done) {
@@ -230,6 +231,8 @@ function _ts_generator$2(thisArg, body) {
  * Creates a new TestDoneCallbackRef.
  *
  * 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
  */ function testDoneCallbackRef() {
     var _promise = promiseReference();
     var done = function done(e) {
@@ -264,6 +267,9 @@ function _ts_generator$2(thisArg, body) {
  *   // 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() {
@@ -695,6 +701,7 @@ 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`
  */ function wrapTestContextFactory(config) {
     return function(factory) {
@@ -703,7 +710,8 @@ function _ts_generator$1(thisArg, body) {
                 var wrap = config.wrapFixture(inputFixture);
                 var effect;
                 // add before each
-                if (config.setupWrap != null) {
+                var setupWrap = config.setupWrap, teardownWrap = config.teardownWrap;
+                if (setupWrap != null) {
                     beforeEach(function() {
                         return _async_to_generator$1(function() {
                             return _ts_generator$1(this, function(_state) {
@@ -711,7 +719,7 @@ function _ts_generator$1(thisArg, body) {
                                     case 0:
                                         return [
                                             4,
-                                            config.setupWrap(wrap)
+                                            setupWrap(wrap)
                                         ];
                                     case 1:
                                         effect = _state.sent();
@@ -726,7 +734,7 @@ function _ts_generator$1(thisArg, body) {
                 // add tests
                 buildTests(wrap);
                 // add after each
-                if (config.teardownWrap != null) {
+                if (teardownWrap != null) {
                     afterEach(function() {
                         return _async_to_generator$1(function() {
                             return _ts_generator$1(this, function(_state) {
@@ -734,7 +742,7 @@ function _ts_generator$1(thisArg, body) {
                                     case 0:
                                         return [
                                             4,
-                                            config.teardownWrap(wrap, effect)
+                                            teardownWrap(wrap, effect)
                                         ];
                                     case 1:
                                         _state.sent();
@@ -799,7 +807,7 @@ function _ts_generator$1(thisArg, body) {
                 return _ts_generator$1(this, function(_state) {
                     switch(_state.label){
                         case 0:
-                            deleteInstanceEffect === null || deleteInstanceEffect === void 0 ? void 0 : deleteInstanceEffect();
+                            deleteInstanceEffect();
                             if (!config.teardownInstance) return [
                                 3,
                                 2
@@ -1072,6 +1080,7 @@ 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
  */ function failSuccessfullyError(message) {
     return new ExpectedFailError(message);
 }
@@ -1099,6 +1108,7 @@ 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
  */ function failDueToSuccessError(message) {
     return new UnexpectedSuccessFailureError(message !== null && message !== void 0 ? message : 'expected an error to occur but was successful instead');
 }
@@ -1135,6 +1145,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
  */ function EXPECT_ERROR_DEFAULT_HANDLER(e) {
     if (_instanceof(e, ExpectedFailError)) ; else {
         throw e;
@@ -1154,7 +1166,13 @@ function _ts_generator(thisArg, body) {
         }
     };
 }
-function expectFail(errorFn, assertFailType) {
+/**
+ * Function that expects any failure to be thrown, then throws an ExpectedFailError.
+ *
+ * @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 resolves when the expected failure is verified
+ */ function expectFail(errorFn, assertFailType) {
     function handleError(e) {
         if (_instanceof(e, UnexpectedSuccessFailureError)) {
             throw e;
@@ -1176,6 +1194,7 @@ function expectFail(errorFn, assertFailType) {
     } catch (e) {
         handleError(e);
     }
+    return Promise.resolve();
 }
 function expectSuccessfulFail(errorFn) {
     var handleError = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : EXPECT_ERROR_DEFAULT_HANDLER;
@@ -1266,6 +1285,8 @@ 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
  */ function fakeDoneHandler() {
     var promiseRef = promiseReference();
     var doneHandler = promiseRef.resolve;
@@ -1470,6 +1491,8 @@ function _is_native_reflect_construct() {
 }(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
  */ function failWithDoneDueToSuccess(done) {
     failWithTestDoneCallback(done, failDueToSuccessError());
 }

package/test/package.json

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

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

@@ -4,7 +4,7 @@
  * Since fail() was silently removed, we redefine it.
  */
 import { type TestDoneCallback, failWithTestDoneCallback, type TestProvidesCallbackWithDone, type TestProvidesCallback } from '../shared';
-import { ExpectedFailError, failSuccessfullyError, failSuccessfully, UnexpectedSuccessFailureError, failDueToSuccessError, ExpectedErrorOfSpecificTypeError, failTest, failDueToSuccess, EXPECT_ERROR_DEFAULT_HANDLER, type ExpectFailAssertionFunction, expectFailAssertErrorType, expectFail, expectSuccessfulFail, type ShouldFailDoneCallback, type ShouldFailProvidesCallbackWithDone, type ShouldFailProvidesCallbackWithResult, type ShouldFailProvidesCallback, type FakeDoneHandler } from '../shared/shared.fail';
+import { ExpectedFailError, UnexpectedSuccessFailureError, ExpectedErrorOfSpecificTypeError, type ExpectFailAssertionFunction, expectFailAssertErrorType, type ShouldFailDoneCallback, type ShouldFailProvidesCallbackWithDone, type ShouldFailProvidesCallbackWithResult, type ShouldFailProvidesCallback, type FakeDoneHandler } from '../shared/shared.fail';
 /**
  * @deprecated Use TestDoneCallback from shared instead. This is kept for backwards compatibility.
  */
@@ -38,9 +38,10 @@ export declare class JestExpectedErrorOfSpecificTypeError extends ExpectedErrorO
 }
 /**
  * @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
  */
 export declare function failWithDoneDueToSuccess(done: TestDoneCallback): void;
-export { failSuccessfullyError, failSuccessfully, failDueToSuccessError, failTest, failDueToSuccess, EXPECT_ERROR_DEFAULT_HANDLER };
 /**
  * @deprecated Use ExpectFailAssertionFunction from shared instead. This is kept for backwards compatibility.
  */
@@ -49,7 +50,6 @@ export type JestExpectFailAssertionFunction = ExpectFailAssertionFunction;
  * @deprecated Use expectFailAssertErrorType from shared instead. This is kept for backwards compatibility.
  */
 export declare const jestExpectFailAssertErrorType: typeof expectFailAssertErrorType;
-export { expectFail, expectSuccessfulFail };
 /**
  * @deprecated Use ShouldFailDoneCallback from shared instead. This is kept for backwards compatibility.
  */

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

@@ -10,12 +10,13 @@ export type TestDoneCallback = ((...args: any[]) => any) & {
      *
      * @param error
      */
-    fail(error?: string | {
+    fail?(error?: string | {
         message: string;
     }): 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
  */
@@ -40,6 +41,8 @@ export type TestDoneCallbackRef = Omit<TestDoneCallback, 'fail'> & {
  * Creates a new TestDoneCallbackRef.
  *
  * 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
  */
 export declare function testDoneCallbackRef(): TestDoneCallbackRef;
 /**
@@ -61,6 +64,9 @@ export declare function testDoneCallbackRef(): TestDoneCallbackRef;
  *   // 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>;
 /**

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

@@ -13,6 +13,7 @@ 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
  */
 export declare function failSuccessfullyError(message?: string): ExpectedFailError;
 /**
@@ -33,6 +34,7 @@ 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
  */
 export declare function failDueToSuccessError(message?: string): UnexpectedSuccessFailureError;
 /**
@@ -58,6 +60,8 @@ 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
  */
 export declare function EXPECT_ERROR_DEFAULT_HANDLER(e: unknown): void;
 /**
@@ -80,9 +84,9 @@ export declare function expectFailAssertErrorType(expectedType: ClassType | Clas
  *
  * @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 resolves when the expected failure is verified
  */
-export declare function expectFail(errorFn: () => void, assertFailType?: ExpectFailAssertionFunction): void;
-export declare function expectFail(errorFn: () => Promise<void>, assertFailType?: ExpectFailAssertionFunction): Promise<void>;
+export declare function expectFail(errorFn: () => PromiseOrValue<any>, assertFailType?: ExpectFailAssertionFunction): Promise<void>;
 /**
  * Function that expects an ExpectedFailError to be thrown.
  *
@@ -142,5 +146,7 @@ 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
  */
 export declare function fakeDoneHandler(): FakeDoneHandler;

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

@@ -47,6 +47,7 @@ export interface WrapTestContextConfig<W, F, E = any> {
 /**
  * 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`
  */
 export declare function wrapTestContextFactory<W, F, E = any>(config: WrapTestContextConfig<W, F, E>): (factory: TestContextFactory<F>) => TestContextFactory<W>;