bupkis 0.7.2 → 0.9.0

package/src/assertion/impl/assertion-util.ts

@@ -5,33 +5,47 @@
  * @packageDocumentation
  */
 
+type TrapResult =
+  | { error: unknown; result?: never }
+  | { error?: never; result: unknown };
+
 /**
  * Executes & traps a `Promise` rejected from an async function, capturing the
  * error.
  *
+ * @function
  * @param fn The function to execute that may throw an error or return a
  *   `Promise`
- * @returns Rejection
+ * @returns Rejection or whatever was fulfilled
  */
-export const trapAsyncFnError = async (fn: () => unknown) => {
+export const trapAsyncFnError = async (
+  fn: () => unknown,
+): Promise<TrapResult> => {
   try {
-    await fn();
-  } catch (err) {
-    return err;
+    const result = await fn();
+    return { result };
+  } catch (error) {
+    return {
+      error: error ?? new TypeError(`Function rejected with undefined: ${fn}`),
+    };
   }
 };
 
 /**
  * Awaits & traps a Promise, capturing any rejection error.
  *
+ * @function
  * @param promise The `Promise` to trap
- * @returns Rejection
+ * @returns Result object
  */
-export const trapPromiseError = async (promise: PromiseLike<unknown>) => {
+export const trapPromiseError = async (
+  promise: PromiseLike<unknown>,
+): Promise<TrapResult> => {
   try {
-    await promise;
-  } catch (err) {
-    return err;
+    const result = await promise;
+    return { result };
+  } catch (error) {
+    return { error: error ?? new TypeError('Promise rejected with undefined') };
   }
 };
 
@@ -41,16 +55,15 @@ export const trapPromiseError = async (promise: PromiseLike<unknown>) => {
  *
  * @remarks
  * Avoids throwing `undefined` for some reason.
+ * @function
  * @param fn Function to execute
- * @returns Error
+ * @returns Result object
  */
-export const trapError = (fn: () => unknown): unknown => {
+export const trapError = (fn: () => unknown): TrapResult => {
   try {
-    fn();
-  } catch (err) {
-    if (err === undefined) {
-      return new Error('Function threw undefined');
-    }
-    return err;
+    const result = fn();
+    return { result };
+  } catch (error) {
+    return { error: error ?? new TypeError(`Function threw undefined: ${fn}`) };
   }
 };

package/src/assertion/impl/async-parametric.ts

@@ -16,7 +16,7 @@
 import { inspect } from 'node:util';
 import { z } from 'zod/v4';
 
-import { InvalidSchemaError } from '../../error.js';
+import { InvalidObjectSchemaError } from '../../error.js';
 import { isA, isNonNullObject, isString } from '../../guards.js';
 import {
   ConstructibleSchema,
@@ -56,7 +56,7 @@ export const functionResolveAssertion = createAsyncAssertion(
     }
   },
   {
-    anchor: 'to-resolve',
+    anchor: 'promise-to-resolve',
     category: 'promise',
   },
 );
@@ -86,6 +86,10 @@ export const promiseResolveAssertion = createAsyncAssertion(
       };
     }
   },
+  {
+    anchor: 'promise-to-resolve',
+    category: 'promise',
+  },
 );
 
 /**
@@ -103,14 +107,14 @@ export const promiseResolveAssertion = createAsyncAssertion(
 export const functionRejectAssertion = createAsyncAssertion(
   [FunctionSchema, 'to reject'],
   async (subject) => {
-    try {
-      await subject();
+    const { error, result } = await trapAsyncFnError(subject);
+    if (error === undefined) {
       return {
         actual: 'function fulfilled',
-        expected: 'function to reject',
-        message: 'Expected function to reject, but it fulfilled instead',
+        expected: 'function rejected',
+        message: `Expected function to reject, but it fulfilled with ${inspect(result)}`,
       };
-    } catch {}
+    }
   },
 );
 
@@ -129,14 +133,14 @@ export const functionRejectAssertion = createAsyncAssertion(
 export const promiseRejectAssertion = createAsyncAssertion(
   [WrappedPromiseLikeSchema, 'to reject'],
   async (subject) => {
-    try {
-      await subject;
+    const { error, result } = await trapPromiseError(subject);
+    if (error === undefined) {
       return {
-        actual: 'function fulfilled',
-        expected: 'function to reject',
-        message: 'Expected function to reject, but it fulfilled instead',
+        actual: 'Promise fulfilled',
+        expected: 'Promise rejected',
+        message: `Expected Promise to reject, but it fulfilled with ${inspect(result)}`,
       };
-    } catch {}
+    }
   },
 );
 
@@ -167,11 +171,29 @@ export const functionRejectWithTypeAssertion = createAsyncAssertion(
     ConstructibleSchema,
   ],
   async (subject, ctor) => {
-    const error = await trapAsyncFnError(subject);
-    if (!error) {
-      return false;
+    const { error, result } = await trapAsyncFnError(subject);
+    if (error === undefined) {
+      return {
+        actual: 'function fulfilled',
+        expect: 'function rejected',
+        message: `Expected function to reject, but it fulfilled with ${inspect(result)}`,
+      };
+    }
+    if (!isA(error, ctor)) {
+      if (isNonNullObject(error)) {
+        const err = error as object;
+        return {
+          actual: err.constructor.name,
+          expected: ctor.name,
+          message: `Expected function to reject with an instance of ${ctor.name}, but it rejected with a ${err.constructor.name}`,
+        };
+      }
+      return {
+        actual: typeof error,
+        expected: ctor.name,
+        message: `Expected function to reject with an instance of ${ctor.name}, but it rejected with a value of type ${typeof error}: ${inspect(error)}`,
+      };
     }
-    return isA(error, ctor);
   },
 );
 
@@ -202,11 +224,29 @@ export const promiseRejectWithTypeAssertion = createAsyncAssertion(
     ConstructibleSchema,
   ],
   async (subject, ctor) => {
-    const error = await trapPromiseError(subject);
-    if (!error) {
-      return false;
+    const { error, result } = await trapPromiseError(subject);
+    if (error === undefined) {
+      return {
+        actual: 'Promise fulfilled',
+        expect: 'Promise rejected',
+        message: `Expected Promise to reject, but it fulfilled with ${inspect(result)}`,
+      };
+    }
+    if (!isA(error, ctor)) {
+      if (isNonNullObject(error)) {
+        const err = error as object;
+        return {
+          actual: err.constructor.name,
+          expected: ctor.name,
+          message: `Expected Promise to reject with an instance of ${ctor.name}, but it rejected with a ${err.constructor.name}`,
+        };
+      }
+      return {
+        actual: typeof error,
+        expected: ctor.name,
+        message: `Expected Promise to reject with an instance of ${ctor.name}, but it rejected with a value of type ${typeof error}: ${inspect(error)}`,
+      };
     }
-    return isA(error, ctor);
   },
 );
 
@@ -239,12 +279,12 @@ export const promiseRejectWithTypeAssertion = createAsyncAssertion(
 export const functionRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
   [FunctionSchema, ['to reject with error satisfying'], z.any()],
   async (subject, param) => {
-    const error = await trapAsyncFnError(subject);
-    if (!error) {
+    const { error, result } = await trapAsyncFnError(subject);
+    if (error === undefined) {
       return {
         actual: 'function fulfilled',
         expect: 'function to reject',
-        message: 'Expected function to reject, but it fulfilled instead',
+        message: `Expected function to reject, but it fulfilled with ${inspect(result)}`,
       };
     }
 
@@ -267,16 +307,16 @@ export const functionRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
     }
     /* c8 ignore next 5 */
     if (!schema) {
-      throw new InvalidSchemaError(
+      throw new InvalidObjectSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
         { schema: param },
       );
     }
 
-    const result = schema.safeParse(error);
-    if (!result.success) {
-      return result.error;
-    }
+    return {
+      schema,
+      subject: error,
+    };
   },
 );
 
@@ -309,12 +349,12 @@ export const functionRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
 export const promiseRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
   [WrappedPromiseLikeSchema, ['to reject with error satisfying'], z.any()],
   async (subject, param) => {
-    const error = await trapPromiseError(subject);
-    if (!error) {
+    const { error, result } = await trapPromiseError(subject);
+    if (error === undefined) {
       return {
-        actual: 'promise fulfilled',
-        expect: 'promise to reject',
-        message: 'Expected promise to reject, but it fulfilled instead',
+        actual: 'Promise fulfilled',
+        expect: 'Promise rejected',
+        message: `Expected Promise to reject, but it fulfilled with ${inspect(result)}`,
       };
     }
     let schema: undefined | z.ZodType;
@@ -336,16 +376,16 @@ export const promiseRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
     }
     /* c8 ignore next 5 */
     if (!schema) {
-      throw new InvalidSchemaError(
+      throw new InvalidObjectSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
         { schema: param },
       );
     }
 
-    const result = schema.safeParse(error);
-    if (!result.success) {
-      return result.error;
-    }
+    return {
+      schema,
+      subject: error,
+    };
   },
 );
 
@@ -375,7 +415,7 @@ export const promiseRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
  *
  * @group Parametric Assertions (Async)
  */
-export const promiseFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
+export const promiseResolveWithValueSatisfyingAssertion = createAsyncAssertion(
   [
     WrappedPromiseLikeSchema,
     ['to fulfill with value satisfying', 'to resolve with value satisfying'],
@@ -387,19 +427,20 @@ export const promiseFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
       value = await promise;
     } catch (err) {
       return {
-        actual: err,
-        expect: 'promise to fulfill',
-        message: `Expected promise to not reject, but it rejected with ${inspect(
+        actual: 'Promise rejected',
+        expect: 'Promise to fulfill',
+        message: `Expected Promise to fulfill, but it rejected with ${inspect(
           err,
         )}`,
       };
     }
 
     const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
-    const result = schema.safeParse(value);
-    if (!result.success) {
-      return result.error;
-    }
+
+    return {
+      schema,
+      subject: value,
+    };
   },
 );
 
@@ -442,7 +483,7 @@ export const functionFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
     } catch (err) {
       return {
         actual: 'function rejected',
-        expect: 'function to fulfill',
+        expect: 'function fulfilled',
         message: `Expected function to fulfill, but it rejected with ${inspect(
           err,
         )}`,
@@ -450,9 +491,9 @@ export const functionFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
     }
 
     const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
-    const result = schema.safeParse(value);
-    if (!result.success) {
-      return result.error;
-    }
+    return {
+      schema,
+      subject: value,
+    };
   },
 );

package/src/assertion/impl/async.ts

@@ -13,11 +13,11 @@ import {
   functionRejectWithErrorSatisfyingAssertion,
   functionRejectWithTypeAssertion,
   functionResolveAssertion,
-  promiseFulfillWithValueSatisfyingAssertion,
   promiseRejectAssertion,
   promiseRejectWithErrorSatisfyingAssertion,
   promiseRejectWithTypeAssertion,
   promiseResolveAssertion,
+  promiseResolveWithValueSatisfyingAssertion,
 } from './async-parametric.js';
 
 /**
@@ -34,7 +34,7 @@ export const AsyncParametricAssertions = [
   promiseRejectWithTypeAssertion,
   functionRejectWithErrorSatisfyingAssertion,
   promiseRejectWithErrorSatisfyingAssertion,
-  promiseFulfillWithValueSatisfyingAssertion,
+  promiseResolveWithValueSatisfyingAssertion,
   functionFulfillWithValueSatisfyingAssertion,
 ] as const;
 

package/src/assertion/impl/sync-basic.ts

@@ -27,6 +27,8 @@ import {
 } from '../../schema.js';
 import { createAssertion } from '../create.js';
 
+const { ownKeys } = Reflect;
+
 /**
  * Asserts that the subject is a string value.
  *
@@ -39,7 +41,10 @@ import { createAssertion } from '../create.js';
  *
  * @group Basic Assertions
  */
-export const stringAssertion = createAssertion(['to be a string'], z.string());
+export const stringAssertion = createAssertion(['to be a string'], z.string(), {
+  anchor: 'unknown-to-be-a-string',
+  category: 'primitives',
+});
 
 /**
  * Asserts that the subject is a finite number value.
@@ -571,9 +576,7 @@ export const emptyArrayAssertion = createAssertion(
  */
 export const emptyObjectAssertion = createAssertion(
   [z.record(z.any(), z.unknown()), 'to be empty'],
-  z
-    .record(z.any(), z.unknown())
-    .refine((obj) => Reflect.ownKeys(obj).length === 0),
+  z.record(z.any(), z.unknown()).refine((obj) => ownKeys(obj).length === 0),
 );
 
 /**

package/src/assertion/impl/sync-collection.ts

@@ -32,6 +32,8 @@ import {
 import { has } from '../../util.js';
 import { createAssertion } from '../create.js';
 
+const { hasOwn, keys } = Object;
+
 /**
  * Asserts that a Map or WeakMap contains a specific key. For WeakMap, the key
  * must be an object.
@@ -101,7 +103,9 @@ export const mapContainsAssertion = createAssertion(
 export const mapSizeAssertion = createAssertion(
   [z.map(z.unknown(), z.unknown()), 'to have size', NonNegativeIntegerSchema],
   (subject, expectedSize): AssertionFailure | boolean => {
-    if (subject.size === expectedSize) return true;
+    if (subject.size === expectedSize) {
+      return true;
+    }
     return {
       actual: subject.size,
       expected: expectedSize,
@@ -242,7 +246,9 @@ export const emptySetAssertion = createAssertion(
 export const arrayContainsAssertion = createAssertion(
   [z.array(z.any()), ['to contain', 'to include'], z.any()],
   (subject, value): AssertionFailure | boolean => {
-    if (subject.includes(value)) return true;
+    if (subject.includes(value)) {
+      return true;
+    }
     return {
       actual: subject,
       expected: `array containing ${String(value)}`,
@@ -266,7 +272,9 @@ export const arrayContainsAssertion = createAssertion(
 export const arraySizeAssertion = createAssertion(
   [z.array(z.any()), 'to have size', NonNegativeIntegerSchema],
   (subject, expectedSize): AssertionFailure | boolean => {
-    if (subject.length === expectedSize) return true;
+    if (subject.length === expectedSize) {
+      return true;
+    }
     return {
       actual: subject.length,
       expected: expectedSize,
@@ -339,7 +347,7 @@ export const objectKeysAssertion = createAssertion(
     z.array(z.string()).nonempty(),
   ],
   (subject, keys) => {
-    const missing = keys.filter((k) => !Object.hasOwn(subject, k));
+    const missing = keys.filter((k) => !hasOwn(subject, k));
     if (missing.length > 0) {
       return {
         actual: `missing keys: ${missing.join(', ')}`,
@@ -439,7 +447,7 @@ export const objectExactKeyAssertion = createAssertion(
   ],
   (_, key) =>
     NonCollectionObjectSchema.transform((v) => ({ ...v })).refine(
-      (value) => Object.hasOwn(value, key),
+      (value) => hasOwn(value, key),
       { error: `Expected object to have own exact key "${String(key)}"` },
     ),
 );
@@ -459,7 +467,7 @@ export const objectExactKeyAssertion = createAssertion(
 export const objectSizeAssertion = createAssertion(
   [z.looseObject({}), 'to have size', NonNegativeIntegerSchema],
   (subject, expectedSize) => {
-    const actual = Object.keys(subject).length;
+    const actual = keys(subject).length;
     if (actual !== expectedSize) {
       return {
         actual,
@@ -713,9 +721,11 @@ export const setSymmetricDifferenceEqualityAssertion = createAssertion(
 export const mapKeyAssertion = createAssertion(
   [z.map(z.unknown(), z.unknown()), 'to have key', z.unknown()],
   (map, key): AssertionFailure | boolean => {
-    if (map.has(key)) return true;
+    if (map.has(key)) {
+      return true;
+    }
     return {
-      actual: Array.from(map.keys()),
+      actual: [...map.keys()],
       expected: key,
       message: `Expected Map to have key`,
     };
@@ -739,10 +749,12 @@ export const mapValueAssertion = createAssertion(
   [z.map(z.unknown(), z.unknown()), 'to have value', z.unknown()],
   (map, value): AssertionFailure | boolean => {
     for (const mapValue of map.values()) {
-      if (mapValue === value) return true;
+      if (mapValue === value) {
+        return true;
+      }
     }
     return {
-      actual: Array.from(map.values()),
+      actual: [...map.values()],
       expected: value,
       message: `Expected Map to have value`,
     };
@@ -781,7 +793,9 @@ export const mapEntryAssertion = createAssertion(
     // At this point, if it's a WeakMap, we know key is a WeakKey
     const actualValue =
       map instanceof WeakMap ? map.get(key as WeakKey) : map.get(key);
-    if (actualValue === value) return true;
+    if (actualValue === value) {
+      return true;
+    }
 
     const hasKey =
       map instanceof WeakMap ? map.has(key as WeakKey) : map.has(key);
@@ -867,7 +881,9 @@ export const collectionSizeGreaterThanAssertion = createAssertion(
     NonNegativeIntegerSchema,
   ],
   (collection, minSize): AssertionFailure | boolean => {
-    if (collection.size > minSize) return true;
+    if (collection.size > minSize) {
+      return true;
+    }
     return {
       actual: collection.size,
       expected: `size greater than ${minSize}`,
@@ -895,7 +911,9 @@ export const collectionSizeLessThanAssertion = createAssertion(
     NonNegativeIntegerSchema,
   ],
   (collection, maxSize): AssertionFailure | boolean => {
-    if (collection.size < maxSize) return true;
+    if (collection.size < maxSize) {
+      return true;
+    }
     return {
       actual: collection.size,
       expected: `size less than ${maxSize}`,
@@ -924,7 +942,9 @@ export const collectionSizeBetweenAssertion = createAssertion(
   ],
   (collection, [min, max]): AssertionFailure | boolean => {
     const size = collection.size;
-    if (size >= min && size <= max) return true;
+    if (size >= min && size <= max) {
+      return true;
+    }
     return {
       actual: size,
       expected: `size between ${min} and ${max} (inclusive)`,

package/src/assertion/impl/sync-esoteric.ts

@@ -12,9 +12,12 @@
 
 import { z } from 'zod/v4';
 
+import { isNonNullObject } from '../../guards.js';
 import { DictionarySchema, PropertyKeySchema } from '../../schema.js';
 import { createAssertion } from '../create.js';
 
+const { getOwnPropertyDescriptor, isExtensible, isFrozen, isSealed } = Object;
+
 /**
  * Asserts that an object has a null prototype (i.e.,
  * `Object.getPrototypeOf(obj) === null`).
@@ -72,7 +75,7 @@ export const enumerablePropertyAssertion = createAssertion(
     z.unknown().nonoptional(),
   ],
   (subject, obj) => {
-    if (!Object.getOwnPropertyDescriptor(obj, subject)?.enumerable) {
+    if (!getOwnPropertyDescriptor(obj, subject)?.enumerable) {
       return {
         actual: false,
         expected: true,
@@ -112,15 +115,16 @@ export const enumerablePropertyAssertion = createAssertion(
  */
 export const enumerablePropertyAssertion2 = createAssertion(
   [z.unknown().nonoptional(), 'to have enumerable property', PropertyKeySchema],
-  (subject, key) => {
-    if (!Object.getOwnPropertyDescriptor(subject, key)?.enumerable) {
-      return {
-        actual: false,
-        expected: true,
-        message: `Expected property ${String(key)} to be enumerable`,
-      };
-    }
-  },
+  (_subject, key) =>
+    z.custom(
+      (value) =>
+        isNonNullObject(value) &&
+        key in value &&
+        !!getOwnPropertyDescriptor(value, key)?.enumerable,
+      {
+        error: `Expected property "${String(key)}" to be enumerable`,
+      },
+    ),
 );
 
 /**
@@ -150,7 +154,7 @@ export const enumerablePropertyAssertion2 = createAssertion(
  */
 export const sealedAssertion = createAssertion(
   ['to be sealed'],
-  z.any().refine((obj) => Object.isSealed(obj)),
+  z.any().refine((obj) => isSealed(obj)),
 );
 
 /**
@@ -181,7 +185,7 @@ export const sealedAssertion = createAssertion(
  * @group Esoteric Assertions
  */
 export const frozenAssertion = createAssertion(['to be frozen'], (subject) => {
-  if (!Object.isFrozen(subject)) {
+  if (!isFrozen(subject)) {
     return {
       actual: false,
       expected: true,
@@ -221,5 +225,5 @@ export const frozenAssertion = createAssertion(['to be frozen'], (subject) => {
  */
 export const extensibleAssertion = createAssertion(
   ['to be extensible'],
-  z.any().refine((obj) => Object.isExtensible(obj)),
+  z.any().refine((obj) => isExtensible(obj)),
 );