bupkis 0.7.2 → 0.9.0

package/src/assertion/assertion-async.ts

@@ -3,19 +3,18 @@ import z from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
 import { AssertionError, AssertionImplementationError } from '../error.js';
+import { isA, isBoolean, isError, isZodType } from '../guards.js';
 import {
-  isA,
   isAssertionFailure,
-  isBoolean,
-  isError,
-  isZodType,
-} from '../guards.js';
+  isAssertionParseRequest,
+} from '../internal-schema.js';
 import { BupkisRegistry } from '../metadata.js';
 import {
   type AssertionAsync,
   type AssertionFunctionAsync,
   type AssertionImplAsync,
   type AssertionImplFnAsync,
+  type AssertionImplFnReturnType,
   type AssertionImplSchemaAsync,
   type AssertionParts,
   type AssertionSchemaAsync,
@@ -114,8 +113,25 @@ export class BupkisAssertionFunctionAsync<
     stackStartFn: (...args: any[]) => any,
     _parseResult?: ParsedResult<Parts>,
   ): Promise<void> {
-    const { impl } = this;
-    const result = await impl(...parsedValues);
+    let result: AssertionImplFnReturnType<Parts>;
+    try {
+      result = await (this.impl as AssertionImplFnAsync<Parts>).call(
+        null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        ...(parsedValues as any),
+      );
+    } catch (err) {
+      if (AssertionError.isAssertionError(err)) {
+        throw err;
+      }
+      if (isError(err) && err instanceof z.ZodError) {
+        throw this.fromZodError(err, stackStartFn, parsedValues);
+      }
+      throw new AssertionImplementationError(
+        `Unexpected error thrown from assertion ${this}: ${err}`,
+        { cause: err },
+      );
+    }
     if (isZodType(result)) {
       try {
         await result.parseAsync(parsedValues[0]);
@@ -131,14 +147,27 @@ export class BupkisAssertionFunctionAsync<
           message: `Assertion ${this} failed for arguments: ${inspect(args)}`,
         });
       }
+    } else if (isError(result) && result instanceof z.ZodError) {
+      throw this.fromZodError(result, stackStartFn, parsedValues);
+    } else if (isAssertionParseRequest(result)) {
+      const { asyncSchema, schema, subject } = result;
+      let zodResult: z.ZodSafeParseResult<unknown>;
+      if (schema) {
+        zodResult = schema.safeParse(subject);
+      } else {
+        zodResult = asyncSchema.safeParse(subject);
+      }
+      if (!zodResult.success) {
+        throw this.fromZodError(zodResult.error, stackStartFn, subject);
+      }
     } else if (isAssertionFailure(result)) {
       throw new AssertionError({
         actual: result.actual,
         expected: result.expected,
-        message: result.message ?? `Assertion ${this} failed`,
+        message:
+          result.message ??
+          `Assertion ${this} failed for arguments: ${inspect(args)}`,
       });
-    } else if (isError(result) && result instanceof z.ZodError) {
-      throw this.fromZodError(result, stackStartFn, parsedValues);
     } else if (result as unknown) {
       throw new AssertionImplementationError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
@@ -197,6 +226,8 @@ export class BupkisAssertionSchemaAsync<
       if (isA(error, z.ZodError)) {
         throw this.fromZodError(error, stackStartFn, parsedValues);
       }
+      /* c8 ignore next */
+      throw error;
     }
   }
 
@@ -211,10 +242,7 @@ export class BupkisAssertionSchemaAsync<
     }
 
     let exactMatch = true;
-    let subjectValidationResult:
-      | undefined
-      | { data: any; success: true }
-      | { error: z.ZodError; success: false };
+    let subjectValidationResult: ParsedResultSuccess<Parts>['subjectValidationResult'];
 
     for (let i = 0; i < slots.length; i++) {
       const slot = slots[i]!;

package/src/assertion/assertion-sync.ts

@@ -16,16 +16,15 @@ import {
   AssertionImplementationError,
   UnexpectedAsyncError,
 } from '../error.js';
+import { isBoolean, isError, isPromiseLike, isZodType } from '../guards.js';
 import {
   isAssertionFailure,
-  isBoolean,
-  isError,
-  isPromiseLike,
-  isZodType,
-} from '../guards.js';
+  isAssertionParseRequest,
+} from '../internal-schema.js';
 import { BupkisRegistry } from '../metadata.js';
 import {
   type AssertionFunctionSync,
+  type AssertionImplFnReturnType,
   type AssertionImplFnSync,
   type AssertionImplSchemaSync,
   type AssertionImplSync,
@@ -145,11 +144,25 @@ export class BupkisAssertionFunctionSync<
     stackStartFn: (...args: any[]) => any,
     _parseResult?: ParsedResult<Parts>,
   ): void {
-    const result = (this.impl as AssertionImplFnSync<Parts>).call(
-      null,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-      ...(parsedValues as any),
-    );
+    let result: AssertionImplFnReturnType<Parts>;
+    try {
+      result = (this.impl as AssertionImplFnSync<Parts>).call(
+        null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        ...(parsedValues as any),
+      );
+    } catch (err) {
+      if (AssertionError.isAssertionError(err)) {
+        throw err;
+      }
+      if (isError(err) && err instanceof z.ZodError) {
+        throw this.fromZodError(err, stackStartFn, parsedValues);
+      }
+      throw new AssertionImplementationError(
+        `Unexpected error thrown from assertion ${this}: ${err}`,
+        { cause: err },
+      );
+    }
     if (isPromiseLike(result)) {
       // Avoid unhandled promise rejection
       Promise.resolve(result).catch((err) => {
@@ -171,14 +184,27 @@ export class BupkisAssertionFunctionSync<
           message: `Assertion ${this} failed for arguments: ${inspect(args)}`,
         });
       }
+    } else if (isError(result) && result instanceof z.ZodError) {
+      throw this.fromZodError(result, stackStartFn, parsedValues);
+    } else if (isAssertionParseRequest(result)) {
+      const { asyncSchema, schema, subject } = result;
+      if (asyncSchema) {
+        throw new AssertionImplementationError(
+          `Sync assertion ${this} returned an async schema in its AssertionParseRequest`,
+        );
+      }
+      const zodResult = schema.safeParse(subject);
+      if (!zodResult.success) {
+        throw this.fromZodError(zodResult.error, stackStartFn, subject);
+      }
     } else if (isAssertionFailure(result)) {
       throw new AssertionError({
         actual: result.actual,
         expected: result.expected,
-        message: result.message ?? `Assertion ${this} failed`,
+        message:
+          result.message ??
+          `Assertion ${this} failed for arguments: ${inspect(args)}`,
       });
-    } else if (isError(result) && result instanceof z.ZodError) {
-      throw this.fromZodError(result, stackStartFn, parsedValues);
     } else if (result as unknown) {
       throw new AssertionImplementationError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
@@ -252,10 +278,7 @@ export class BupkisAssertionSchemaSync<
     }
 
     let exactMatch = true;
-    let subjectValidationResult:
-      | undefined
-      | { data: any; success: true }
-      | { error: z.ZodError; success: false };
+    let subjectValidationResult: ParsedResultSuccess<Parts>['subjectValidationResult'];
 
     for (let i = 0; i < slots.length; i++) {
       const slot = slots[i]!;

package/src/assertion/assertion-types.ts

@@ -17,7 +17,7 @@
  */
 
 import { type ArrayValues, type NonEmptyTuple } from 'type-fest';
-import { z } from 'zod/v4';
+import { type z } from 'zod/v4';
 
 import type { AsyncAssertions, SyncAssertions } from './impl/index.js';
 
@@ -271,6 +271,7 @@ export type AssertionImplFnAsync<Parts extends AssertionParts> = (
  */
 export type AssertionImplFnReturnType<Parts extends AssertionParts> =
   | AssertionFailure
+  | AssertionParseRequest
   | boolean
   | void
   | z.ZodError
@@ -379,6 +380,57 @@ export type AssertionImplSync<Parts extends AssertionParts> =
   | AssertionImplFnSync<Parts>
   | AssertionImplSchemaSync<Parts>;
 
+/**
+ * Internal metadata for assertions.
+ *
+ * For internal use by documentation tooling.
+ */
+export interface AssertionMetadata {
+  /**
+   * Anchor ID for linking to this assertion
+   */
+  anchor: string;
+  /**
+   * Category to map to page of logically grouped assertions
+   */
+  category:
+    | 'collections'
+    | 'date'
+    | 'equality'
+    | 'error'
+    | 'function'
+    | 'numeric'
+    | 'object'
+    | 'other'
+    | 'primitives'
+    | 'promise'
+    | 'strings';
+  /**
+   * Redirect for assertion to its documentation page, including anchor
+   */
+  redirect?: string | undefined;
+}
+
+/**
+ * When you want to use a Zod schema in an assertion implementation function
+ * against some value that _isn't_ the subject, you can return this object and
+ * <span class="bupkis">BUPKIS</span> will do it for you (with better diffs).
+ *
+ * @group Assertion Creation
+ */
+export type AssertionParseRequest = {
+  subject: unknown;
+} & (
+  | {
+      asyncSchema: z.ZodType;
+      schema?: never;
+    }
+  | {
+      asyncSchema?: never;
+      schema: z.ZodType;
+    }
+);
+
 /**
  * Union type representing the fundamental building blocks of an assertion.
  *
@@ -740,7 +792,6 @@ export interface CreateAssertionFn {
     metadata?: AssertionMetadata,
   ): AssertionFunctionSync<Parts, Impl, Slots>;
 }
-
 /**
  * The main factory function for creating asynchronous assertions.
  *
@@ -789,6 +840,7 @@ export interface CreateAsyncAssertionFn {
     metadata?: AssertionMetadata,
   ): AssertionFunctionAsync<Parts, Impl, Slots>;
 }
+
 /**
  * Utility type for parsed values that may be empty.
  *
@@ -1014,7 +1066,6 @@ export type ParsedValues<Parts extends AssertionParts = AssertionParts> =
  * @see {@link AssertionPart} for how phrases fit into assertion structure
  */
 export type Phrase = PhraseLiteral | PhraseLiteralChoice;
-
 /**
  * Type representing a single phrase literal string.
  *
@@ -1044,6 +1095,7 @@ export type Phrase = PhraseLiteral | PhraseLiteralChoice;
  * @see {@link AssertionPart} for how phrases fit into assertion structure
  */
 export type PhraseLiteral = string;
+
 /**
  * Type representing a choice between multiple phrase literals.
  *
@@ -1152,45 +1204,3 @@ export type RawAssertionImplSchemaAsync<Parts extends AssertionParts> =
  */
 export type RawAssertionImplSchemaSync<Parts extends AssertionParts> =
   z.ZodType<ParsedSubject<Parts>>;
-
-/**
- * Metadata associated with an assertion, for internal use by documentation
- * tooling.
- *
- * @private
- */
-export const AssertionMetadataSchema = z
-  .looseObject({
-    anchor: z.string().describe('Anchor ID for linking to this assertion.'),
-    category: z
-      .enum([
-        'collections',
-        'date',
-        'equality',
-        'error',
-        'function',
-        'numeric',
-        'object',
-        'other',
-        'primitives',
-        'promise',
-        'strings',
-      ])
-      .describe('Category to map to page of logically grouped assertions'),
-    redirectName: z
-      .string()
-      .optional()
-      .describe(
-        'Redirect for assertion to its documentation page, including anchor',
-      ),
-  })
-  .describe(
-    'Metadata associated with an assertion, for internal use by documentation tooling.',
-  );
-
-/**
- * {@inheritDoc AssertionMetadataSchema}
- *
- * @private
- */
-export type AssertionMetadata = z.infer<typeof AssertionMetadataSchema>;

package/src/assertion/assertion.ts

@@ -16,6 +16,11 @@ import { inspect } from 'util';
 import { z } from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
+import {
+  extractDiffValues,
+  generateDiff,
+  shouldGenerateDiff,
+} from '../diff.js';
 import { AssertionError, InvalidMetadataError } from '../error.js';
 import { BupkisRegistry } from '../metadata.js';
 import {
@@ -25,11 +30,11 @@ import {
   type AssertionParts,
   type AssertionSlots,
   type ParsedResult,
-  type ParsedValues,
 } from './assertion-types.js';
 
 const debug = createDebug('bupkis:assertion');
-
+const { hasOwn, keys } = Object;
+const { isArray } = Array;
 /**
  * Modified charmap for {@link slug} to use underscores to replace hyphens (`-`;
  * and for hyphens to replace everything else that needs replacing) and `<` with
@@ -75,6 +80,14 @@ export abstract class BupkisAssertion<
    * @returns String representation
    */
   public toString(): string {
+    /**
+     * Expands a Zod type into a human-readable string representation.
+     *
+     * @function
+     * @param zodType The Zod type to expand
+     * @param wrapCurlies Whether to wrap the result in curly braces
+     * @returns String representation of the Zod type
+     */
     const expand = (
       zodType: z.core.$ZodType | z.ZodType,
       wrapCurlies = false,
@@ -107,7 +120,7 @@ export abstract class BupkisAssertion<
             repr = `{${expand((def as z.core.$ZodDefaultDef).innerType)}}`;
             break;
           case 'enum':
-            repr = `${Object.keys((def as z.core.$ZodEnumDef<any>).entries as Record<PropertyKey, unknown>).join(' / ')}`;
+            repr = `${keys((def as z.core.$ZodEnumDef<any>).entries as Record<PropertyKey, unknown>).join(' / ')}`;
             break;
           case 'intersection':
             repr = `${expand((def as z.core.$ZodIntersectionDef<z.core.$ZodType>).left)} & ${expand((def as z.core.$ZodIntersectionDef<z.core.$ZodType>).right)}`;
@@ -154,7 +167,7 @@ export abstract class BupkisAssertion<
     };
     return `"${this.slots
       .map((slot) =>
-        Object.hasOwn(BupkisRegistry.get(slot) ?? {}, kStringLiteral)
+        hasOwn(BupkisRegistry.get(slot) ?? {}, kStringLiteral)
           ? expand(slot)
           : expand(slot, true),
       )
@@ -174,40 +187,44 @@ export abstract class BupkisAssertion<
    * @param values Values which caused the error
    * @returns New `AssertionError`
    */
-  /**
-   * Translates a {@link z.ZodError} into an {@link AssertionError} with a
-   * human-friendly message.
-   *
-   * @remarks
-   * This does not handle parameterized assertions with more than one parameter
-   * too cleanly; it's unclear how a test runner would display the expected
-   * values. This will probably need a fix in the future.
-   * @param stackStartFn The function to start the stack trace from
-   * @param zodError The original `ZodError`
-   * @param values Values which caused the error
-   * @returns New `AssertionError`
-   */
-  protected fromZodError<Parts extends AssertionParts>(
+  protected fromZodError<Values>(
     zodError: z.ZodError,
     stackStartFn: (...args: any[]) => any,
-    values: ParsedValues<Parts>,
+    values: Values,
   ): AssertionError {
-    const flat = z.flattenError(zodError);
+    const subject: unknown = isArray(values) ? values[0] : values;
 
-    let pretty = flat.formErrors.join('; ');
-    for (const [keypath, errors] of Object.entries(flat.fieldErrors)) {
-      pretty += `; ${keypath}: ${(errors as unknown[]).join('; ')}`;
-    }
+    const { actual, expected } = extractDiffValues(zodError, subject);
 
-    const [actual, ...expected] = values as unknown as [unknown, ...unknown[]];
+    // Only use custom message if we could extract diff values
+    if (shouldGenerateDiff(actual, expected)) {
+      // Use jest-diff to generate rich, colored diff output
+      const diffOutput = generateDiff(expected, actual, {
+        aAnnotation: 'expected',
+        bAnnotation: 'actual',
+        expand: false,
+        includeChangeCounts: true,
+      });
 
-    return new AssertionError({
-      actual,
-      expected: expected.length === 1 ? expected[0] : expected,
-      message: `Assertion ${this} failed: ${pretty}`,
-      operator: `${this}`,
-      stackStartFn,
-    });
+      const message = diffOutput
+        ? `Assertion ${this} failed:\n${diffOutput}`
+        : `Assertion ${this} failed: values are not equal`;
+
+      return new AssertionError({
+        actual,
+        expected,
+        message,
+        stackStartFn,
+      });
+    } else {
+      // Fall back to Zod's prettified error message
+      const pretty = z.prettifyError(zodError).slice(2);
+      return new AssertionError({
+        actual: subject,
+        message: `Assertion ${this} failed:\n${pretty}`,
+        stackStartFn,
+      });
+    }
   }
 
   protected maybeParseValuesArgMismatch<Args extends readonly unknown[]>(

package/src/assertion/create.ts

@@ -76,7 +76,12 @@ import type {
 } from './assertion-types.js';
 
 import { AssertionImplementationError } from '../error.js';
-import { isFunction, isString, isZodType } from '../guards.js';
+import { isFunction, isZodType } from '../guards.js';
+import {
+  AssertionMetadataSchema,
+  CreateAssertionInputSchema,
+  CreateAssertionInputSchemaAsync,
+} from '../internal-schema.js';
 import {
   BupkisAssertionFunctionAsync,
   BupkisAssertionSchemaAsync,
@@ -86,7 +91,6 @@ import {
   BupkisAssertionSchemaSync,
 } from './assertion-sync.js';
 import {
-  AssertionMetadataSchema,
   type CreateAssertionFn,
   type CreateAsyncAssertionFn,
 } from './assertion-types.js';
@@ -96,6 +100,7 @@ import { slotify } from './slotify.js';
 /**
  * {@inheritDoc CreateAssertionFn}
  *
+ * @function
  * @throws {TypeError} Invalid assertion implementation type
  * @group Assertion Creation
  */
@@ -107,56 +112,37 @@ export const createAssertion: CreateAssertionFn = <
   impl: Impl,
   metadata?: AssertionMetadata,
 ) => {
-  if (!Array.isArray(parts)) {
-    throw new AssertionImplementationError('First parameter must be an array');
-  }
-  if (parts.length === 0) {
-    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 AssertionImplementationError(
-      'All assertion parts must be strings or Zod schemas',
-    );
-  }
-  if (!impl) {
-    throw new AssertionImplementationError(
-      'An assertion implementation is required',
-    );
-  }
+  // Validate inputs using Zod schema
   try {
-    const slots = slotify<Parts>(parts);
-
-    if (isZodType(impl)) {
-      const assertion = new BupkisAssertionSchemaSync(parts, slots, impl);
-      if (metadata) {
-        AssertionMetadataRegistry.set(assertion, metadata);
-      }
-      return assertion;
-    } else if (isFunction(impl)) {
-      const assertion = new BupkisAssertionFunctionSync(parts, slots, impl);
-      if (metadata) {
-        AssertionMetadataRegistry.set(assertion, metadata);
-      }
-      return assertion;
-    }
+    CreateAssertionInputSchema.parse([parts, impl, metadata]);
   } catch (err) {
     if (err instanceof z.ZodError) {
       throw new AssertionImplementationError(
-        `Failed to slotify assertion parts: ${z.prettifyError(err)}`,
+        `Invalid input parameters: ${z.prettifyError(err)}`,
         { cause: err },
       );
     }
-    throw new AssertionImplementationError(
-      `Failed to slotify assertion parts: ${err}`,
-      { cause: err },
-    );
+    /* c8 ignore next */
+    throw err;
+  }
+
+  const slots = slotify<Parts>(parts);
+
+  if (isZodType(impl)) {
+    const assertion = new BupkisAssertionSchemaSync(parts, slots, impl);
+    if (metadata) {
+      AssertionMetadataRegistry.set(assertion, metadata);
+    }
+    return assertion;
+  } else if (isFunction(impl)) {
+    const assertion = new BupkisAssertionFunctionSync(parts, slots, impl);
+    if (metadata) {
+      AssertionMetadataRegistry.set(assertion, metadata);
+    }
+    return assertion;
   }
+  // should be impossible if CreateAssertionInputSchema is correct
+  /* c8 ignore next */
   throw new AssertionImplementationError(
     'Assertion implementation must be a function, Zod schema or Zod schema factory',
   );
@@ -165,6 +151,7 @@ export const createAssertion: CreateAssertionFn = <
 /**
  * {@inheritDoc CreateAsyncAssertionFn}
  *
+ * @function
  * @throws {TypeError} Invalid assertion implementation type
  * @group Assertion Creation
  */
@@ -176,28 +163,20 @@ export const createAsyncAssertion: CreateAsyncAssertionFn = <
   impl: Impl,
   metadata?: AssertionMetadata,
 ) => {
-  if (!Array.isArray(parts)) {
-    throw new AssertionImplementationError('First parameter must be an array');
-  }
-  if (parts.length === 0) {
-    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 AssertionImplementationError(
-      'All assertion parts must be strings or Zod schemas',
-    );
-  }
-  if (!impl) {
-    throw new AssertionImplementationError(
-      'An assertion implementation is required',
-    );
+  // Validate inputs using Zod schema
+  try {
+    CreateAssertionInputSchemaAsync.parse([parts, impl, metadata]);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new AssertionImplementationError(
+        `Invalid input parameters: ${z.prettifyError(err)}`,
+        { cause: err },
+      );
+    }
+    /* c8 ignore next */
+    throw err;
   }
+
   const slots = slotify<Parts>(parts);
 
   if (isZodType(impl)) {
@@ -219,6 +198,8 @@ export const createAsyncAssertion: CreateAsyncAssertionFn = <
     }
     return assertion;
   }
+  // should be impossible if CreateAssertionInputSchemaAsync is correct
+  /* c8 ignore next */
   throw new AssertionImplementationError(
     'Assertion implementation must be a function, Zod schema or Zod schema factory',
   );