bupkis 0.7.2 → 0.8.0

package/src/diff.ts

@@ -0,0 +1,343 @@
+/**
+ * Diff utilities for generating rich assertion failure output.
+ *
+ * This module provides utilities for extracting meaningful actual/expected
+ * values from Zod validation errors and generating high-quality diff output
+ * using `jest-diff` for assertion failures.
+ *
+ * @packageDocumentation
+ * @see {@link https://npm.im/jest-diff | jest-diff}
+ */
+
+import type { DiffOptions } from 'jest-diff';
+import type { z } from 'zod/v4';
+
+import { diff } from 'jest-diff';
+export type { DiffOptions };
+
+const { isArray } = Array;
+const { max } = Math;
+const { stringify } = JSON;
+const { entries } = Object;
+
+/**
+ * Result of extracting diff values from a `ZodError`
+ */
+export interface DiffValues {
+  /** The actual value that was validated */
+  actual: unknown;
+  /** The expected value (corrected version) */
+  expected: unknown;
+}
+
+/**
+ * Extracts actual and expected values from a `ZodError` for meaningful diffs.
+ *
+ * @function
+ * @param zodError The `ZodError` to extract values from
+ * @param subject The original subject that failed validation
+ * @returns Object with actual and expected values for diff
+ */
+export const extractDiffValues = (
+  zodError: z.ZodError,
+  subject: unknown,
+): DiffValues => {
+  try {
+    // Start with the original subject as the actual value
+    const actual = subject;
+
+    // Create a copy to modify as the expected value
+    let expected = subject != null ? deepClone(subject) : subject;
+
+    // Process each issue to build the expected value
+    for (const issue of zodError.issues) {
+      try {
+        // Filter path to only string/number keys (symbols are rare in practice)
+        const filteredPath = issue.path.filter(
+          (key): key is number | string =>
+            typeof key === 'string' || typeof key === 'number',
+        );
+
+        switch (issue.code) {
+          case 'invalid_type': {
+            const correctedValue = createCorrectValueForType(
+              issue.expected,
+              getValueAtPath(actual, filteredPath),
+            );
+            expected = setValueAtPath(expected, filteredPath, correctedValue);
+            break;
+          }
+
+          case 'invalid_value': {
+            // For literal/enum errors, use the first valid value
+            const correctedValue =
+              issue.values && issue.values.length > 0
+                ? issue.values[0]
+                : '<valid value>';
+            expected = setValueAtPath(expected, filteredPath, correctedValue);
+            break;
+          }
+
+          case 'too_big': {
+            const actualValue = getValueAtPath(actual, filteredPath);
+            let correctedValue;
+
+            if (issue.origin === 'string' && typeof actualValue === 'string') {
+              correctedValue = actualValue.slice(0, Number(issue.maximum));
+            } else if (issue.origin === 'array' && isArray(actualValue)) {
+              correctedValue = actualValue.slice(0, Number(issue.maximum));
+            } else {
+              correctedValue = issue.maximum;
+            }
+
+            expected = setValueAtPath(expected, filteredPath, correctedValue);
+            break;
+          }
+
+          case 'too_small': {
+            const actualValue = getValueAtPath(actual, filteredPath);
+            let correctedValue;
+
+            if (issue.origin === 'string' && typeof actualValue === 'string') {
+              const needed = Number(issue.minimum) - actualValue.length;
+              correctedValue = actualValue + 'x'.repeat(max(0, needed));
+            } else if (issue.origin === 'array' && isArray(actualValue)) {
+              const needed = Number(issue.minimum) - actualValue.length;
+              correctedValue = actualValue.concat(
+                new Array(max(0, needed)).fill(null),
+              );
+            } else {
+              correctedValue = issue.minimum;
+            }
+
+            expected = setValueAtPath(expected, filteredPath, correctedValue);
+            break;
+          }
+
+          case 'unrecognized_keys': {
+            // Remove unrecognized keys from expected
+            if (
+              filteredPath.length === 0 &&
+              typeof expected === 'object' &&
+              expected !== null
+            ) {
+              const expectedCopy = {
+                ...(expected as Record<string, unknown>),
+              };
+              for (const key of issue.keys) {
+                delete expectedCopy[key];
+              }
+              expected = expectedCopy;
+            }
+            break;
+          }
+
+          default: {
+            // For other error types, just mark that something should be different
+            // but don't try to guess what the correct value should be
+            break;
+          }
+        }
+      } catch {
+        // If we can't process an individual issue, continue with others
+        continue;
+      }
+    }
+
+    return { actual, expected };
+  } catch {
+    // If anything goes wrong, return undefined to fall back to pretty error
+    return { actual: undefined, expected: undefined };
+  }
+};
+
+/**
+ * Generates a rich diff string using jest-diff for assertion failures.
+ *
+ * @function
+ * @param expected The expected value
+ * @param actual The actual value
+ * @param options Configuration options for diff generation
+ * @returns A formatted diff string, or null if values are identical
+ */
+export const generateDiff = (
+  expected: unknown,
+  actual: unknown,
+  options: DiffOptions = {},
+): null | string => {
+  if (!shouldGenerateDiff(actual, expected)) {
+    return null;
+  }
+
+  return diff(expected, actual, {
+    aAnnotation: 'expected',
+    bAnnotation: 'actual',
+    expand: false,
+    includeChangeCounts: true,
+    ...options,
+  });
+};
+
+/**
+ * Checks if two values should generate a meaningful diff.
+ *
+ * @function
+ * @param actual The actual value
+ * @param expected The expected value
+ * @returns True if a diff should be generated, false otherwise
+ */
+export const shouldGenerateDiff = (
+  actual: unknown,
+  expected: unknown,
+): boolean =>
+  actual !== undefined && expected !== undefined && actual !== expected;
+
+/**
+ * Creates a corrected value for a given type
+ *
+ * @function
+ */
+const createCorrectValueForType = (
+  expectedType: string,
+  actualValue: unknown,
+): unknown => {
+  switch (expectedType) {
+    case 'array':
+      return isArray(actualValue) ? actualValue : [];
+    case 'boolean':
+      return typeof actualValue === 'boolean'
+        ? actualValue
+        : Boolean(actualValue);
+    case 'null':
+      return null;
+    case 'number':
+      return typeof actualValue === 'number'
+        ? actualValue
+        : Number(actualValue) || 0;
+    case 'object':
+      return typeof actualValue === 'object' && actualValue !== null
+        ? actualValue
+        : {};
+    case 'string':
+      if (typeof actualValue === 'string') {
+        return actualValue;
+      }
+      if (actualValue == null) {
+        return '';
+      }
+      if (typeof actualValue === 'object') {
+        return stringify(actualValue);
+      }
+      // For primitive types (number, boolean, etc.) - we know it's not an object here
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      return `${actualValue}`;
+    case 'undefined':
+      return undefined;
+    default:
+      return `<${expectedType}>`;
+  }
+};
+
+/**
+ * Custom deep clone implementation for values that structuredClone can't
+ * handle. Used as fallback when structuredClone fails.
+ *
+ * @function
+ */
+const customDeepClone = (value: unknown): unknown => {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (isArray(value)) {
+    return value.map(customDeepClone);
+  }
+  // For objects, create a new object and copy properties
+  const cloned: Record<string, unknown> = {};
+  for (const [key, val] of entries(value)) {
+    cloned[key] = customDeepClone(val);
+  }
+  return cloned;
+};
+
+/**
+ * Deep clone a value to avoid mutating the original. Uses the native
+ * structuredClone API which handles more types and circular references better
+ * than a custom implementation. Falls back to custom implementation for values
+ * containing functions.
+ *
+ * @function
+ */
+const deepClone = (value: unknown): unknown => {
+  try {
+    return structuredClone(value);
+  } catch (error) {
+    // Handle DataCloneError for values that can't be cloned (functions, symbols, etc.)
+    if (error instanceof Error && error.name === 'DataCloneError') {
+      return customDeepClone(value);
+    }
+    throw error;
+  }
+};
+
+/**
+ * Gets a value at a specific path in an object
+ *
+ * @function
+ */
+const getValueAtPath = (
+  obj: unknown,
+  path: readonly (number | string)[],
+): unknown => {
+  if (path.length === 0) {
+    return obj;
+  }
+
+  let current = obj;
+  for (const key of path) {
+    if (current == null) {
+      return undefined;
+    }
+    current = (current as Record<number | string, unknown>)[key];
+  }
+  return current;
+};
+
+/**
+ * Returns a new object with the value at the specified path set to the given
+ * value.
+ *
+ * @function
+ */
+const setValueAtPath = (
+  obj: unknown,
+  path: readonly (number | string)[],
+  value: unknown,
+): unknown => {
+  if (path.length === 0) {
+    return value;
+  }
+
+  if (obj == null) {
+    // Need to create the structure
+    obj = typeof path[0] === 'number' ? [] : {};
+  }
+
+  const result = isArray(obj)
+    ? [...(obj as unknown[])]
+    : { ...(obj as Record<string, unknown>) };
+  const [head, ...tail] = path;
+
+  if (head !== undefined) {
+    if (tail.length === 0) {
+      (result as Record<number | string, unknown>)[head] = value;
+    } else {
+      (result as Record<number | string, unknown>)[head] = setValueAtPath(
+        (result as Record<number | string, unknown>)[head],
+        tail,
+        value,
+      );
+    }
+  }
+
+  return result;
+};

package/src/error.ts

@@ -16,6 +16,23 @@ import {
 } from './constant.js';
 import { isA } from './guards.js';
 
+const { hasOwn } = Object;
+
+/**
+ * Options for {@link AssertionError}'s constructor
+ *
+ * @remarks
+ * Based on Node.js' {@link NodeAssertionError}'s constructor options, sans
+ * `operator`.
+ * @group Error Options
+ */
+export type AssertionErrorOptions = Partial<
+  Omit<
+    NonNullable<ConstructorParameters<typeof NodeAssertionError>[0]>,
+    'operator'
+  >
+>;
+
 /**
  * Options for {@link AssertionImplementationError}
  *
@@ -80,6 +97,10 @@ export class AssertionError extends NodeAssertionError {
 
   override name = 'AssertionError';
 
+  constructor(options?: AssertionErrorOptions) {
+    super(options);
+  }
+
   /**
    * Type guard for an instance of this error.
    *
@@ -88,10 +109,19 @@ export class AssertionError extends NodeAssertionError {
    */
   static isAssertionError(value: unknown): value is AssertionError {
     return (
-      isA(value, NodeAssertionError) &&
-      Object.hasOwn(value, kBupkisAssertionError)
+      isA(value, NodeAssertionError) && hasOwn(value, kBupkisAssertionError)
     );
   }
+
+  toJSON() {
+    return {
+      actual: this.actual,
+      expected: this.expected,
+      message: this.message,
+      name: this.name,
+      stack: this.stack,
+    };
+  }
 }
 
 /**
@@ -108,7 +138,7 @@ export class BupkisError extends Error {
   override name = 'BupkisError';
 
   static isBupkisError(err: unknown): err is BupkisError {
-    return isA(err, Error) && Object.hasOwn(err, kBupkisError);
+    return isA(err, Error) && hasOwn(err, kBupkisError);
   }
 }
 
@@ -151,8 +181,7 @@ export class FailAssertionError extends AssertionError {
 
   static isFailAssertionError(err: unknown): err is FailAssertionError {
     return (
-      isA(err, FailAssertionError) &&
-      Object.hasOwn(err, kBupkisFailAssertionError)
+      isA(err, FailAssertionError) && hasOwn(err, kBupkisFailAssertionError)
     );
   }
 }
@@ -211,8 +240,7 @@ export class NegatedAssertionError extends AssertionError {
 
   static isNegatedAssertionError(err: unknown): err is NegatedAssertionError {
     return (
-      isA(err, AssertionError) &&
-      Object.hasOwn(err, kBupkisNegatedAssertionError)
+      isA(err, AssertionError) && hasOwn(err, kBupkisNegatedAssertionError)
     );
   }
 }

package/src/expect.ts

@@ -181,6 +181,9 @@ export function createExpectAsyncFunction<
     expect?.assertions.length ?? 0,
     assertions.length + (expect?.assertions.length ?? 0),
   );
+  /**
+   * @function
+   */
   const expectAsyncFunction = async (...args: readonly unknown[]) => {
     await Promise.resolve();
     const [isNegated, processedArgs] = maybeProcessNegation(args);
@@ -359,6 +362,9 @@ export function createExpectSyncFunction<
     expect?.assertions.length ?? 0,
     assertions.length + (expect?.assertions.length ?? 0),
   );
+  /**
+   * @function
+   */
   const expectFunction = (...args: readonly unknown[]) => {
     const [isNegated, processedArgs] = maybeProcessNegation(args);
     const candidates: Array<{
@@ -406,6 +412,7 @@ export function createExpectSyncFunction<
  * @privateRemarks
  * This is here because `Assertion` doesn't know anything about negation and
  * probably shouldn't.
+ * @function
  * @param assertion - The assertion to execute
  * @param parsedValues - Parsed values for the assertion
  * @param args - Original arguments passed to expect
@@ -474,6 +481,7 @@ const execute = <
  * @privateRemarks
  * This is here because `Assertion` doesn't know anything about negation and
  * probably shouldn't.
+ * @function
  * @param assertion - The assertion to execute
  * @param parsedValues - Parsed values for the assertion
  * @param args - Original arguments passed to expectAsync
@@ -533,6 +541,7 @@ const executeAsync = async <
  * requested along with arguments stripped of the leading negation (to enable
  * assertion matching).
  *
+ * @function
  * @internal
  */
 const maybeProcessNegation = (
@@ -555,6 +564,7 @@ const maybeProcessNegation = (
  * Throws an error indicating that no valid assertion could be found for the
  * provided arguments.
  *
+ * @function
  * @param args The arguments that were passed to the expect function
  * @internal
  */
@@ -571,6 +581,7 @@ const throwInvalidParametersError = (args: readonly unknown[]): never => {
  * Detects if an assertion phrase starts with "not " and returns the cleaned
  * phrase.
  *
+ * @function
  * @param phrase - The assertion phrase to check
  * @returns Object with `isNegated` flag and `cleanedPhrase`
  */
@@ -595,6 +606,8 @@ const detectNegation = (
 
 /**
  * {@inheritdoc FailFn}
+ *
+ * @function
  */
 const fail: FailFn = (reason?: string): never => {
   throw new FailAssertionError({ message: reason });

package/src/guards.ts

@@ -16,7 +16,6 @@
  * @packageDocumentation
  */
 
-import { type Primitive } from 'type-fest';
 import { z } from 'zod/v4';
 
 import type {
@@ -28,6 +27,8 @@ import type { Constructor, ExpectItExecutor, ZodTypeMap } from './types.js';
 
 import { kExpectIt } from './constant.js';
 
+const { isArray } = Array;
+
 /**
  * Returns `true` if the given value looks like a Zod v4 schema, determined by
  * the presence of an internal {@link z.core.$ZodTypeDef} field.
@@ -43,6 +44,7 @@ export function isZodType<T extends keyof ZodTypeMap>(
   value: unknown,
   type: T,
 ): value is ZodTypeMap[T];
+
 /**
  * Returns `true` if the given value looks like a Zod v4 schema, determined by
  * the presence of an internal {@link z.core.$ZodTypeDef} field.
@@ -65,8 +67,12 @@ export function isZodType<T extends keyof ZodTypeMap>(
     typeof value.def === 'object' &&
     'type' in value.def;
 
-  if (!isValid) return false;
-  if (type === undefined) return true;
+  if (!isValid) {
+    return false;
+  }
+  if (type === undefined) {
+    return true;
+  }
 
   return (value as z.ZodType).def.type === type;
 }
@@ -74,16 +80,18 @@ export function isZodType<T extends keyof ZodTypeMap>(
 /**
  * Type guard for a plain object.
  *
+ * @function
  * @param value Value to test
  * @returns `true` if the value is a plain object, `false` otherwise
  */
 export const isObject = (value: unknown): value is NonNullable<object> => {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  return typeof value === 'object' && value !== null && !isArray(value);
 };
 
 /**
  * Returns `true` if the given value is a {@link z.ZodPromise} schema.
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is a `ZodPromise` schema; `false` otherwise
  */
@@ -93,6 +101,7 @@ export const isZodPromise = (value: unknown): value is z.ZodPromise =>
 /**
  * Checks if a value is "promise-like", meaning it is a "thenable" object.
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is promise-like, `false` otherwise
  */
@@ -114,6 +123,7 @@ export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
  * This may be the only way we can determine, at runtime, if a function is a
  * constructor without actually calling it. I am unsure if this only works for
  * classes.
+ * @function
  * @param fn - Function to test
  * @returns Whether the function is constructable
  */
@@ -123,7 +133,7 @@ export const isConstructible = (fn: unknown): fn is Constructor => {
   }
   try {
     // this will throw if there is no `[[construct]]` slot.. or so I've heard.
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, custom/require-function-tag-in-arrow-functions
     new new Proxy(fn as any, { construct: () => ({}) })();
     return true;
   } catch {
@@ -134,6 +144,7 @@ export const isConstructible = (fn: unknown): fn is Constructor => {
 /**
  * Type guard for a boolean value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a boolean, `false` otherwise
  */
@@ -143,6 +154,7 @@ export const isBoolean = (value: unknown): value is boolean =>
 /**
  * Type guard for a function value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a function, `false` otherwise
  */
@@ -169,6 +181,7 @@ const AssertionFailureSchema: z.ZodType<AssertionFailure> = z.object({
 /**
  * Type guard for a {@link AssertionFailure} object
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is an `AssertionFailure`, `false` otherwise
  * @internal
@@ -179,6 +192,7 @@ export const isAssertionFailure = (value: unknown): value is AssertionFailure =>
 /**
  * Type guard for a string value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a string, `false` otherwise
  */
@@ -188,27 +202,20 @@ export const isString = (value: unknown): value is string =>
 /**
  * Type guard for a non-null object value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is an object and not null, `false` otherwise
  */
 export const isNonNullObject = (value: unknown): value is object =>
   typeof value === 'object' && value !== null;
 
-/**
- * Type guard for a null or non-object value
- *
- * @param value Value to check
- * @returns `true` if the value is null or not an object, `false` otherwise
- */
-export const isNullOrNonObject = (value: unknown): value is null | Primitive =>
-  typeof value !== 'object' || value === null;
-
 /**
  * Type guard for a valid WeakKey (object, function, or symbol).
  *
  * WeakMaps and WeakSets can only use objects (including functions) or symbols
  * as keys, not primitives like strings, numbers, booleans, null, or undefined.
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a valid WeakKey (object, function, or
  *   symbol), `false` otherwise
@@ -221,6 +228,7 @@ export const isWeakKey = (value: unknown): value is WeakKey =>
 /**
  * Type guard for a {@link PhraseLiteralChoice}, which is a tuple of strings.
  *
+ * @function
  * @param value Assertion part to check
  * @returns `true` if the part is a `PhraseLiteralChoice`, `false` otherwise
  * @internal
@@ -228,12 +236,13 @@ export const isWeakKey = (value: unknown): value is WeakKey =>
 export const isPhraseLiteralChoice = (
   value: AssertionPart,
 ): value is PhraseLiteralChoice =>
-  Array.isArray(value) && value.every(isPhraseLiteral);
+  isArray(value) && value.every(isPhraseLiteral);
 
 /**
  * Type guard for a {@link PhraseLiteral}, which is just a string that does not
  * begin with `not `.
  *
+ * @function
  * @param value Assertion part to check
  * @returns `true` if the part is a `PhraseLiteral`, `false` otherwise
  * @internal
@@ -260,6 +269,7 @@ export const isPhraseLiteral = (value: AssertionPart): value is string =>
  * ```
  *
  * @template T - The constructor type to check against
+ * @function
  * @param value - Value to test
  * @param ctor - Constructor function to check instanceof
  * @returns `true` if the value is an instance of the constructor, `false`
@@ -292,6 +302,7 @@ export const isA = <T extends Constructor>(
  * }
  * ```
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is an Error instance, `false` otherwise
  */
@@ -318,6 +329,7 @@ export const isError = (value: unknown): value is Error => isA(value, Error);
  * ```
  *
  * @template Subject - The subject type that the executor function operates on
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is an ExpectItExecutor function, `false`
  *   otherwise

package/src/schema.ts

@@ -50,6 +50,8 @@ import {
   type MutableOrReadonly,
 } from './types.js';
 
+const { getPrototypeOf, prototype: objectPrototype } = Object;
+
 /**
  * A Zod schema that validates JavaScript constructible functions.
  *
@@ -386,7 +388,7 @@ export const WrappedPromiseLikeSchema = z
  */
 export const DictionarySchema = z
   .custom<Record<PropertyKey, unknown>>(
-    (value) => isNonNullObject(value) && Object.getPrototypeOf(value) === null,
+    (value) => isNonNullObject(value) && getPrototypeOf(value) === null,
   )
   .describe('Object with null prototype')
   .register(BupkisRegistry, { name: 'dictionary' });
@@ -450,7 +452,7 @@ export const NullProtoObjectSchema = DictionarySchema;
  * @group Schema
  */
 export const AsyncFunctionSchema = FunctionSchema.refine(
-  (value) => Object.prototype.toString.call(value) === '[object AsyncFunction]',
+  (value) => objectPrototype.toString.call(value) === '[object AsyncFunction]',
 )
   .describe('Function declared with the `async` keyword')
   .register(BupkisRegistry, { name: 'async-function' });