bupkis 0.6.0 → 0.7.2

package/src/assertion/assertion-async.ts

@@ -1,9 +1,8 @@
-import Debug from 'debug';
 import { inspect } from 'util';
 import z from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
-import { AssertionError } from '../error.js';
+import { AssertionError, AssertionImplementationError } from '../error.js';
 import {
   isA,
   isAssertionFailure,
@@ -26,7 +25,6 @@ import {
   type ParsedValues,
 } from './assertion-types.js';
 import { BupkisAssertion } from './assertion.js';
-const debug = Debug('bupkis:assertion:async');
 
 export abstract class BupkisAssertionAsync<
     Parts extends AssertionParts,
@@ -68,7 +66,6 @@ export abstract class BupkisAssertionAsync<
       // unknown/any accept anything
       // IMPORTANT: do not use a type guard here; it will break inference
       if (slot.def.type === 'unknown' || slot.def.type === 'any') {
-        debug('Skipping unknown/any slot validation for arg', arg);
         parsedValues.push(arg);
         exactMatch = false;
         continue;
@@ -143,8 +140,9 @@ export class BupkisAssertionFunctionAsync<
     } else if (isError(result) && result instanceof z.ZodError) {
       throw this.fromZodError(result, stackStartFn, parsedValues);
     } else if (result as unknown) {
-      throw new TypeError(
+      throw new AssertionImplementationError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
+        { result },
       );
     }
   }
@@ -182,19 +180,13 @@ export class BupkisAssertionSchemaAsync<
       ? parseResult.subjectValidationResult
       : undefined;
 
-    if (cachedValidation) {
-      debug(
-        'Using cached subject validation result from parseValuesAsync for %s',
-        this,
+    if (cachedValidation && !cachedValidation.success) {
+      // Subject validation failed during parseValuesAsync, throw the cached error
+      throw this.fromZodError(
+        cachedValidation.error,
+        stackStartFn,
+        parsedValues,
       );
-      if (!cachedValidation.success) {
-        // Subject validation failed during parseValuesAsync, throw the cached error
-        throw this.fromZodError(
-          cachedValidation.error,
-          stackStartFn,
-          parsedValues,
-        );
-      }
     }
 
     // Fall back to standard validation if no cached result
@@ -258,7 +250,6 @@ export class BupkisAssertionSchemaAsync<
 
       // Standard slot processing for non-optimized cases
       if (slot.def.type === 'unknown' || slot.def.type === 'any') {
-        debug('Skipping unknown/any slot validation for arg', arg);
         parsedValues.push(arg);
         exactMatch = false;
         continue;

package/src/assertion/assertion-sync.ts

@@ -6,18 +6,21 @@
  * @see {@link AssertionSchemaSync} for schema-based assertions
  */
 
-import Debug from 'debug';
+import createDebug from 'debug';
 import { inspect } from 'util';
 import { z } from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
-import { AssertionError } from '../error.js';
+import {
+  AssertionError,
+  AssertionImplementationError,
+  UnexpectedAsyncError,
+} from '../error.js';
 import {
   isAssertionFailure,
   isBoolean,
   isError,
   isPromiseLike,
-  isZodPromise,
   isZodType,
 } from '../guards.js';
 import { BupkisRegistry } from '../metadata.js';
@@ -36,7 +39,7 @@ import {
 } from './assertion-types.js';
 import { BupkisAssertion } from './assertion.js';
 
-const debug = Debug('bupkis:assertion:sync');
+const debug = createDebug('bupkis:assertion:sync');
 
 /**
  * Abstract class for synchronous assertions.
@@ -106,17 +109,11 @@ export abstract class BupkisAssertionSync<
       // unknown/any accept anything
       // IMPORTANT: do not use a type guard here
       if (slot.def.type === 'unknown' || slot.def.type === 'any') {
-        // debug('Skipping unknown/any slot validation for arg', arg);
         parsedValues.push(arg);
         exactMatch = false;
         continue;
       }
-      // low-effort check
-      if (isZodPromise(slot)) {
-        throw new TypeError(
-          `${this} expects a Promise for slot ${i}; use expectAsync() instead of expect()`,
-        );
-      }
+
       const result = slot.safeParse(arg);
       if (!result.success) {
         return {
@@ -156,10 +153,10 @@ export class BupkisAssertionFunctionSync<
     if (isPromiseLike(result)) {
       // Avoid unhandled promise rejection
       Promise.resolve(result).catch((err) => {
-        debug(`Ate unhandled rejection from assertion %s: %O`, this, err);
+        debug(`⚠️ Ate unhandled rejection from assertion %s: %O`, this, err);
       });
 
-      throw new TypeError(
+      throw new UnexpectedAsyncError(
         `Assertion ${this} returned a Promise; use expectAsync() instead of expect()`,
       );
     }
@@ -183,8 +180,9 @@ export class BupkisAssertionFunctionSync<
     } else if (isError(result) && result instanceof z.ZodError) {
       throw this.fromZodError(result, stackStartFn, parsedValues);
     } else if (result as unknown) {
-      throw new TypeError(
+      throw new AssertionImplementationError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
+        { result },
       );
     }
   }
@@ -223,10 +221,6 @@ export class BupkisAssertionSchemaSync<
       : undefined;
 
     if (cachedValidation) {
-      debug(
-        'Using cached subject validation result from parseValues for %s',
-        this,
-      );
       if (!cachedValidation.success) {
         // Subject validation failed during parseValues, throw the cached error
         throw this.fromZodError(
@@ -293,17 +287,11 @@ export class BupkisAssertionSchemaSync<
 
       // Standard slot processing for non-optimized cases
       if (slot.def.type === 'unknown' || slot.def.type === 'any') {
-        debug('Skipping unknown/any slot validation for arg', arg);
         parsedValues.push(arg);
         exactMatch = false;
         continue;
       }
 
-      if (isZodPromise(slot)) {
-        throw new TypeError(
-          `${this} expects a Promise for slot ${i}; use expectAsync() instead of expect()`,
-        );
-      }
       const result = slot.safeParse(arg);
       if (!result.success) {
         return {

package/src/assertion/assertion.ts

@@ -9,14 +9,14 @@
  * @packageDocumentation
  */
 
-import Debug from 'debug';
+import createDebug from 'debug';
 import slug from 'slug';
 import { type ArrayValues } from 'type-fest';
 import { inspect } from 'util';
 import { z } from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
-import { AssertionError } from '../error.js';
+import { AssertionError, InvalidMetadataError } from '../error.js';
 import { BupkisRegistry } from '../metadata.js';
 import {
   type Assertion,
@@ -28,7 +28,7 @@ import {
   type ParsedValues,
 } from './assertion-types.js';
 
-const debug = Debug('bupkis:assertion');
+const debug = createDebug('bupkis:assertion');
 
 /**
  * Modified charmap for {@link slug} to use underscores to replace hyphens (`-`;
@@ -64,7 +64,7 @@ export abstract class BupkisAssertion<
     readonly impl: Impl,
   ) {
     this.id = this.generateAssertionId();
-    debug('Created assertion %s', this);
+    debug('ℹ Created assertion %s', this);
   }
 
   public metadata(): AssertionMetadata | undefined {
@@ -96,7 +96,7 @@ export abstract class BupkisAssertion<
                   : 'custom';
             } catch (err) {
               debug(
-                `Warning: Unable to extract custom class name from Zod type(did Zod's API change?): ${err}`,
+                `⚠️ WARNING: Unable to extract custom class name from Zod type(did Zod's API change?): ${err}`,
               );
               repr = 'custom';
             }
@@ -251,8 +251,9 @@ export abstract class BupkisAssertion<
         }
       } else {
         /* c8 ignore next */
-        throw new TypeError(
+        throw new InvalidMetadataError(
           `Invalid metadata for slot ${slotIndex} with value ${inspect(rawArg)}`,
+          { metadata: meta },
         );
       }
       return true;

package/src/assertion/create.ts

@@ -75,6 +75,7 @@ import type {
   AssertionParts,
 } from './assertion-types.js';
 
+import { AssertionImplementationError } from '../error.js';
 import { isFunction, isString, isZodType } from '../guards.js';
 import {
   BupkisAssertionFunctionAsync,
@@ -107,20 +108,26 @@ export const createAssertion: CreateAssertionFn = <
   metadata?: AssertionMetadata,
 ) => {
   if (!Array.isArray(parts)) {
-    throw new TypeError('First parameter must be an array');
+    throw new AssertionImplementationError('First parameter must be an array');
   }
   if (parts.length === 0) {
-    throw new TypeError('At least one value is required for an assertion');
+    throw new AssertionImplementationError(
+      'At least one value is required for an assertion',
+    );
   }
   if (
     !parts.every(
       (part) => isString(part) || Array.isArray(part) || isZodType(part),
     )
   ) {
-    throw new TypeError('All assertion parts must be strings or Zod schemas');
+    throw new AssertionImplementationError(
+      'All assertion parts must be strings or Zod schemas',
+    );
   }
   if (!impl) {
-    throw new TypeError('An assertion implementation is required');
+    throw new AssertionImplementationError(
+      'An assertion implementation is required',
+    );
   }
   try {
     const slots = slotify<Parts>(parts);
@@ -140,11 +147,17 @@ export const createAssertion: CreateAssertionFn = <
     }
   } catch (err) {
     if (err instanceof z.ZodError) {
-      throw new TypeError(z.prettifyError(err));
+      throw new AssertionImplementationError(
+        `Failed to slotify assertion parts: ${z.prettifyError(err)}`,
+        { cause: err },
+      );
     }
-    throw err;
+    throw new AssertionImplementationError(
+      `Failed to slotify assertion parts: ${err}`,
+      { cause: err },
+    );
   }
-  throw new TypeError(
+  throw new AssertionImplementationError(
     'Assertion implementation must be a function, Zod schema or Zod schema factory',
   );
 };
@@ -164,20 +177,26 @@ export const createAsyncAssertion: CreateAsyncAssertionFn = <
   metadata?: AssertionMetadata,
 ) => {
   if (!Array.isArray(parts)) {
-    throw new TypeError('First parameter must be an array');
+    throw new AssertionImplementationError('First parameter must be an array');
   }
   if (parts.length === 0) {
-    throw new TypeError('At least one value is required for an assertion');
+    throw new AssertionImplementationError(
+      'At least one value is required for an assertion',
+    );
   }
   if (
     !parts.every(
       (part) => isString(part) || Array.isArray(part) || isZodType(part),
     )
   ) {
-    throw new TypeError('All assertion parts must be strings or Zod schemas');
+    throw new AssertionImplementationError(
+      'All assertion parts must be strings or Zod schemas',
+    );
   }
   if (!impl) {
-    throw new TypeError('An assertion implementation is required');
+    throw new AssertionImplementationError(
+      'An assertion implementation is required',
+    );
   }
   const slots = slotify<Parts>(parts);
 
@@ -200,7 +219,7 @@ export const createAsyncAssertion: CreateAsyncAssertionFn = <
     }
     return assertion;
   }
-  throw new TypeError(
+  throw new AssertionImplementationError(
     'Assertion implementation must be a function, Zod schema or Zod schema factory',
   );
 };

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

@@ -16,6 +16,7 @@
 import { inspect } from 'node:util';
 import { z } from 'zod/v4';
 
+import { InvalidSchemaError } from '../../error.js';
 import { isA, isNonNullObject, isString } from '../../guards.js';
 import {
   ConstructibleSchema,
@@ -266,8 +267,9 @@ export const functionRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
     }
     /* c8 ignore next 5 */
     if (!schema) {
-      throw new TypeError(
+      throw new InvalidSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
+        { schema: param },
       );
     }
 
@@ -334,8 +336,9 @@ export const promiseRejectWithErrorSatisfyingAssertion = createAsyncAssertion(
     }
     /* c8 ignore next 5 */
     if (!schema) {
-      throw new TypeError(
+      throw new InvalidSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
+        { schema: param },
       );
     }
 
@@ -391,30 +394,8 @@ export const promiseFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
         )}`,
       };
     }
-    let schema: undefined | z.ZodType;
-    // TODO: can valueToSchema handle the first two conditional branches?
-    if (isString(param)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().pipe(z.literal(param)),
-        })
-        .or(z.coerce.string().pipe(z.literal(param)));
-    } else if (isA(param, RegExp)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().regex(param),
-        })
-        .or(z.coerce.string().regex(param));
-    } else if (isNonNullObject(param)) {
-      schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
-    }
-    /* c8 ignore next 5 */
-    if (!schema) {
-      throw new TypeError(
-        `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
-      );
-    }
 
+    const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
     const result = schema.safeParse(value);
     if (!result.success) {
       return result.error;
@@ -468,30 +449,7 @@ export const functionFulfillWithValueSatisfyingAssertion = createAsyncAssertion(
       };
     }
 
-    let schema: undefined | z.ZodType;
-    // TODO: can valueToSchema handle the first two conditional branches?
-    if (isString(param)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().pipe(z.literal(param)),
-        })
-        .or(z.coerce.string().pipe(z.literal(param)));
-    } else if (isA(param, RegExp)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().regex(param),
-        })
-        .or(z.coerce.string().regex(param));
-    } else if (isNonNullObject(param)) {
-      schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
-    }
-    /* c8 ignore next 5 */
-    if (!schema) {
-      throw new TypeError(
-        `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
-      );
-    }
-
+    const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
     const result = schema.safeParse(value);
     if (!result.success) {
       return result.error;

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

@@ -462,7 +462,7 @@ export const objectSizeAssertion = createAssertion(
     const actual = Object.keys(subject).length;
     if (actual !== expectedSize) {
       return {
-        actual: actual,
+        actual,
         expected: expectedSize,
         message: `Expected object to have ${expectedSize} keys, but it has ${actual} keys`,
       };

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

@@ -16,6 +16,7 @@
 import { inspect } from 'node:util';
 import { z } from 'zod/v4';
 
+import { BupkisError, InvalidSchemaError } from '../../error.js';
 import { isA, isError, isNonNullObject, isString } from '../../guards.js';
 import {
   ArrayLikeSchema,
@@ -146,7 +147,7 @@ export const typeOfAssertion = createAssertion(
         return z.instanceof(WeakSet);
       // c8 ignore next 2
       default:
-        throw new TypeError(`Unknown type: "${type}"`);
+        throw new BupkisError(`Unknown "type": "${type}"`);
     }
   },
 );
@@ -274,7 +275,7 @@ export const numberCloseToAssertion = createAssertion(
     if (diff > tolerance) {
       return {
         actual: subject,
-        expected: expected,
+        expected,
         message: `Expected ${subject} to be close to ${expected} (within ${tolerance}), but difference was ${diff}`,
       };
     }
@@ -748,7 +749,10 @@ export const functionThrowsMatchingAssertion = createAssertion(
       const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
       return schema.safeParse(error).success;
     } else {
-      throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+      throw new InvalidSchemaError(
+        `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
+        { schema: param },
+      );
     }
   },
 );
@@ -819,8 +823,9 @@ export const functionThrowsTypeSatisfyingAssertion = createAssertion(
       schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
     }
     if (!schema) {
-      throw new TypeError(
+      throw new InvalidSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
+        { schema: param },
       );
     }
 
@@ -892,8 +897,17 @@ export const stringMatchesAssertion = createAssertion(
  * @group Parametric Assertions (Sync)
  */
 export const objectSatisfiesAssertion = createAssertion(
-  [z.looseObject({}).nonoptional(), ['to satisfy', 'to be like'], z.any()],
+  [
+    z.looseObject({}).nonoptional(),
+    ['to satisfy', 'to be like', 'satisfies'],
+    z.any(),
+  ],
   (_subject, shape) => valueToSchema(shape, valueToSchemaOptionsForSatisfies),
+  {
+    anchor: 'object-to-satisfy-any',
+    category: 'object',
+    redirect: 'satisfies',
+  },
 );
 
 /**

package/src/assertion/slotify.ts

@@ -14,6 +14,7 @@ import { z } from 'zod/v4';
 import type { AssertionParts, AssertionSlots } from './assertion-types.js';
 
 import { kStringLiteral } from '../constant.js';
+import { AssertionImplementationError } from '../error.js';
 import {
   isPhraseLiteral,
   isPhraseLiteralChoice,
@@ -43,7 +44,7 @@ export const slotify = <const Parts extends AssertionParts>(
 
     if (isPhraseLiteralChoice(part)) {
       if (part.some((p) => p.startsWith('not '))) {
-        throw new TypeError(
+        throw new AssertionImplementationError(
           `PhraseLiteralChoice at parts[${index}] must not include phrases starting with "not ": ${inspect(
             part,
           )}`,
@@ -60,7 +61,7 @@ export const slotify = <const Parts extends AssertionParts>(
       );
     } else if (isPhraseLiteral(part)) {
       if (part.startsWith('not ')) {
-        throw new TypeError(
+        throw new AssertionImplementationError(
           `PhraseLiteral at parts[${index}] must not start with "not ": ${inspect(
             part,
           )}`,
@@ -77,7 +78,7 @@ export const slotify = <const Parts extends AssertionParts>(
       );
     } else {
       if (!isZodType(part)) {
-        throw new TypeError(
+        throw new AssertionImplementationError(
           `Expected Zod schema, phrase literal, or phrase literal choice at parts[${index}] but received ${inspect(
             part,
           )} (${typeof part})`,

package/src/constant.ts

@@ -77,3 +77,10 @@ export const kExpectIt: unique symbol = Symbol('bupkis-expect-it');
 
 export const KEYPATH_REGEX =
   /^[a-zA-Z_$][-a-zA-Z0-9_$]*(?:(?:\.[a-zA-Z_$][-a-zA-Z0-9_$]*)|(?:\[(?:\d+|"[^"]*"|'[^']*')\]))*$/;
+
+/**
+ * Symbol used to flag a function as a Bupkis-thrown error.
+ *
+ * @internal
+ */
+export const kBupkisError: unique symbol = Symbol('bupkis-error');