bupkis 0.2.0 → 0.4.0

package/dist/esm/value-to-schema.js

@@ -0,0 +1,325 @@
+import { z } from 'zod/v4';
+import { isExpectItExecutor, isNonNullObject, isObject, isPromiseLike, isString, isZodType, } from './guards.js';
+import { RegExpSchema, StrongMapSchema, StrongSetSchema, WrappedPromiseLikeSchema, } from './schema.js';
+/**
+ * Recursively converts an arbitrary value to a Zod v4 schema that would
+ * validate values with the same structure.
+ *
+ * This function analyzes the runtime value and generates a corresponding Zod
+ * schema that captures the value's structure and type information. It handles
+ * primitives, objects, arrays, functions, and various built-in types, with
+ * support for circular reference detection.
+ *
+ * @example
+ *
+ * ```typescript
+ * // Primitive types
+ * valueToSchema('hello'); // z.string()
+ * valueToSchema(42); // z.number()
+ * valueToSchema(true); // z.boolean()
+ *
+ * // Objects
+ * valueToSchema({ name: 'John', age: 30 });
+ * // z.object({ name: z.string(), age: z.number() })
+ *
+ * // Arrays
+ * valueToSchema(['a', 'b', 'c']); // z.array(z.string())
+ * valueToSchema([1, 'mixed']); // z.array(z.union([z.number(), z.string()]))
+ *
+ * // Nested structures
+ * valueToSchema({ users: [{ name: 'John' }] });
+ * // z.object({ users: z.array(z.object({ name: z.string() })) })
+ * ```
+ *
+ * @param value - The value to convert to a schema
+ * @param options - Configuration options for schema generation
+ * @param visited - Internal WeakSet for circular reference detection
+ * @returns A Zod schema that validates values matching the input's structure.
+ *   This value is unfortunately untyped due to the complexity involved. But the
+ *   schema works!
+ */
+export const valueToSchema = (value, options = {}, visited = new WeakSet()) => {
+    const { _currentDepth = 0, literalEmptyObjects = false, literalPrimitives = false, literalRegExp = false, literalTuples = false, maxDepth = 10, noMixedArrays = false, strict = false, } = options;
+    // Prevent infinite recursion
+    if (_currentDepth >= maxDepth) {
+        return z.unknown();
+    }
+    // Handle primitives
+    if (value === null) {
+        return z.null();
+    }
+    if (value === undefined) {
+        return literalPrimitives
+            ? z.custom((val) => val === undefined, {
+                message: 'Expected undefined',
+            })
+            : z.undefined();
+    }
+    if (Number.isNaN(value)) {
+        return z.nan();
+    }
+    if (value === Infinity || value === -Infinity) {
+        return z.literal(value);
+    }
+    const valueType = typeof value;
+    switch (valueType) {
+        case 'bigint':
+            return literalPrimitives ? z.literal(value) : z.bigint();
+        case 'boolean':
+            return literalPrimitives ? z.literal(value) : z.boolean();
+        case 'function':
+            // Check if this is an ExpectItExecutor
+            if (isExpectItExecutor(value)) {
+                // Only allow nested assertions when strict is false (e.g., "to satisfy" semantics)
+                if (strict) {
+                    throw new TypeError('ExpectItExecutor (expect.it) functions are not allowed in strict mode. ' +
+                        'Use "to satisfy" assertions for nested expectations.');
+                }
+                // Return a schema that executes the ExpectItExecutor when validated
+                return z.custom((subject) => {
+                    try {
+                        value(subject);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                }, {
+                    message: 'Failed expect.it assertion',
+                });
+            }
+            return z.function();
+        case 'number':
+            return literalPrimitives ? z.literal(value) : z.number();
+        case 'string':
+            return literalPrimitives ? z.literal(value) : z.string();
+        case 'symbol':
+            return z.symbol();
+    }
+    // Handle objects
+    if (typeof value === 'object' && value !== null) {
+        // Check for circular references
+        if (visited.has(value)) {
+            // Return a recursive schema reference or unknown for circular refs
+            return z.unknown();
+        }
+        visited.add(value);
+        try {
+            // Check for objects with own __proto__ property - these can cause unexpected behavior
+            if (Object.hasOwn(value, '__proto__')) {
+                throw new TypeError('Objects with an own "__proto__" property are not supported by valueToSchema');
+            }
+            // Handle built-in object types
+            if (value instanceof Date) {
+                // Check if it's a valid date
+                if (isNaN(value.getTime())) {
+                    // For invalid dates, use a literal or custom validator
+                    return z.custom((val) => val instanceof Date && isNaN(val.getTime()), {
+                        message: 'Expected an invalid Date',
+                    });
+                }
+                return z.date();
+            }
+            if (value instanceof RegExp) {
+                if (literalRegExp) {
+                    return RegExpSchema;
+                }
+                return z.coerce.string().regex(value);
+            }
+            if (value instanceof Map) {
+                return StrongMapSchema;
+            }
+            if (value instanceof Set) {
+                return StrongSetSchema;
+            }
+            if (value instanceof WeakMap) {
+                return z.instanceof(WeakMap);
+            }
+            if (value instanceof WeakSet) {
+                return z.instanceof(WeakSet);
+            }
+            if (value instanceof Error) {
+                return z.instanceof(Error);
+            }
+            if (isPromiseLike(value)) {
+                return WrappedPromiseLikeSchema;
+            }
+            // Handle arrays
+            if (Array.isArray(value)) {
+                // For arrays, we need to preserve undefined values while allowing
+                // other elements to use the original literalPrimitives setting
+                const filteredValue = value; // Always process all elements
+                if (filteredValue.length === 0) {
+                    // For empty arrays, use z.tuple() if literalTuples is enabled
+                    if (literalTuples) {
+                        return z.tuple([]);
+                    }
+                    return z.array(z.never());
+                }
+                const elementSchemas = filteredValue.map((item) => {
+                    // Use literal mode for undefined values to preserve them exactly,
+                    // but use the original setting for other values
+                    const itemLiteralPrimitives = item === undefined ? true : literalPrimitives;
+                    return valueToSchema(item, {
+                        ...options,
+                        _currentDepth: _currentDepth + 1,
+                        literalPrimitives: itemLiteralPrimitives,
+                    }, visited);
+                });
+                // Use z.tuple() if literalTuples is enabled
+                if (literalTuples) {
+                    return z.tuple(elementSchemas);
+                }
+                if (!noMixedArrays) {
+                    // Helper function to generate structural keys for schemas
+                    const getSchemaKey = (zodType) => {
+                        const schema = zodType;
+                        if (isZodType(schema, 'literal')) {
+                            return `${schema.constructor.name}:${String(schema.def.values)}`;
+                        }
+                        if (isZodType(schema, 'array')) {
+                            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                            const elementKey = getSchemaKey(schema.def.element);
+                            return `ZodArray<${elementKey}>`;
+                        }
+                        if (isZodType(schema, 'object')) {
+                            // For objects, create a key based on the property keys and their types
+                            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                            const shape = schema.def.shape;
+                            const shapeKeys = Object.keys(shape)
+                                .sort()
+                                .map((key) => {
+                                const propSchema = shape[key];
+                                return `${key}:${getSchemaKey(propSchema)}`;
+                            });
+                            return `ZodObject<{${shapeKeys.join(',')}}>`;
+                        }
+                        if (isZodType(schema, 'union')) {
+                            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                            const optionKeys = schema.def.options
+                                .map((option) => getSchemaKey(option))
+                                .sort();
+                            return `ZodUnion<[${optionKeys.join(',')}]>`;
+                        }
+                        // For other types, use the constructor name
+                        return schema.constructor.name;
+                    };
+                    const seenSchemaKeys = new Set();
+                    const uniqueSchemas = [];
+                    for (const schema of elementSchemas) {
+                        const schemaKey = getSchemaKey(schema);
+                        if (!seenSchemaKeys.has(schemaKey)) {
+                            seenSchemaKeys.add(schemaKey);
+                            uniqueSchemas.push(schema);
+                        }
+                    }
+                    if (uniqueSchemas.length === 1) {
+                        return z.array(uniqueSchemas[0]);
+                    }
+                    else {
+                        return z.array(z.union(uniqueSchemas));
+                    }
+                }
+                else {
+                    // Use the first element's schema for all elements
+                    return z.array(elementSchemas[0]);
+                }
+            }
+            // Handle plain objects
+            if (isNonNullObject(value)) {
+                const schemaShape = {};
+                const undefinedKeys = [];
+                for (const [key, val] of Object.entries(value)) {
+                    if (isString(key)) {
+                        // Skip undefined values unless we're in literalPrimitives mode
+                        // This prevents objects with only undefined values from matching any object
+                        if (val === undefined && !literalPrimitives) {
+                            continue;
+                        }
+                        if (val === undefined && literalPrimitives) {
+                            // Track keys that should have undefined values
+                            undefinedKeys.push(key);
+                            schemaShape[key] = z.undefined();
+                        }
+                        else {
+                            schemaShape[key] = valueToSchema(val, {
+                                ...options,
+                                _currentDepth: _currentDepth + 1,
+                            }, visited);
+                        }
+                    }
+                }
+                // Create the base object schema
+                const baseSchema = strict
+                    ? z.strictObject(schemaShape)
+                    : z.looseObject(schemaShape);
+                // If we have undefined keys in literalPrimitives mode, add validation to ensure they exist
+                if (undefinedKeys.length > 0 && literalPrimitives) {
+                    return baseSchema.superRefine((data, ctx) => {
+                        if (typeof data !== 'object' || data === null) {
+                            ctx.addIssue({
+                                code: z.ZodIssueCode.custom,
+                                message: 'Expected an object',
+                            });
+                            return;
+                        }
+                        const obj = data;
+                        for (const key of undefinedKeys) {
+                            if (!Object.hasOwn(obj, key)) {
+                                ctx.addIssue({
+                                    code: z.ZodIssueCode.custom,
+                                    message: `Expected property "${key}" to exist with value undefined`,
+                                    path: [key],
+                                });
+                            }
+                        }
+                    });
+                }
+                // Check if this is an empty object and literalEmptyObjects is enabled
+                if (Object.keys(schemaShape).length === 0 && literalEmptyObjects) {
+                    // Create a schema that only matches empty objects
+                    return z.custom((val) => isObject(val) && Object.keys(val).length === 0, {
+                        message: 'Expected an empty object with no own properties',
+                    });
+                }
+                return baseSchema;
+            }
+            // Handle other object types (ArrayBuffer, etc.)
+            return z.custom((val) => typeof val === 'object' && val !== null, { message: 'Expected an object' });
+        }
+        finally {
+            visited.delete(value);
+        }
+    }
+    // Fallback for unknown types
+    return z.unknown();
+};
+/**
+ * Predefined options for {@link valueToSchema} optimized for object satisfaction
+ * checks.
+ *
+ * Uses literal primitives and tuples for exact matching while allowing extra
+ * properties.
+ */
+export const valueToSchemaOptionsForSatisfies = Object.freeze({
+    literalEmptyObjects: true,
+    literalPrimitives: true,
+    literalRegExp: false,
+    literalTuples: true,
+    strict: false,
+});
+/**
+ * Predefined options for {@link valueToSchema} optimized for deep equality
+ * checks.
+ *
+ * Uses literal primitives, regexp, and tuples with strict validation for exact
+ * matching.
+ */
+export const valueToSchemaOptionsForDeepEqual = Object.freeze({
+    literalEmptyObjects: true,
+    literalPrimitives: true,
+    literalRegExp: true,
+    literalTuples: true,
+    strict: true,
+});
+//# sourceMappingURL=value-to-schema.js.map

package/dist/esm/value-to-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-to-schema.js","sourceRoot":"","sources":["../../src/value-to-schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bupkis",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Uncommonly extensible assertions for the beautiful people",
   "repository": {
@@ -111,24 +111,26 @@
     "build:docs": "typedoc --cleanOutputDir --treatWarningsAsErrors",
     "build:docs:dev": "run-s \"build:docs -- --watch\"",
     "docs:dev": "run-p build:docs:dev serve",
-    "lint": "run-p lint:eslint lint:types lint:knip lint:markdown",
+    "lint": "run-p lint:eslint lint:types lint:knip lint:markdown lint:spelling",
     "lint:commit": "commitlint",
     "lint:eslint": "eslint .",
     "lint:fix": "run-s \"lint:eslint -- --fix\"",
     "lint:knip": "knip",
     "lint:markdown": "markdownlint-cli2 \"**/*.md\"",
+    "lint:spelling": "cspell \"**\"",
     "lint:staged": "lint-staged",
     "lint:types": "tsc -b .config/tsconfig.eslint.json",
     "lint:types:dev": "run-s \"lint:types -- --watch\"",
     "prepare": "husky; run-s build",
     "prepublishOnly": "run-s build",
     "serve": "serve docs",
-    "test": "node $npm_package_testConfig_test_flags \"$npm_package_testConfig_test_pattern_all\"",
+    "test": "run-s \"test:base -- test/**/*.test.ts\"",
+    "test:base": "node --test --test-reporter=spec --import tsx",
     "test:coverage": "c8 --reporter=lcov --reporter=text npm test",
-    "test:dev": "node $npm_package_testConfig_test_flags --watch \"$npm_package_testConfig_test_pattern_all\"",
-    "test:profile": "node --cpu-prof --cpu-prof-dir=.profiles $npm_package_testConfig_test_flags \"$npm_package_testConfig_test_pattern_all\"",
-    "test:property": "node $npm_package_testConfig_test_flags \"$npm_package_testConfig_test_pattern_property\"",
-    "test:property:dev": "node $npm_package_testConfig_test_flags --watch \"$npm_package_testConfig_test_pattern_property\""
+    "test:dev": "node --test --import tsx --watch --test-reporter=spec \"test/**/*.test.ts\"",
+    "test:profile": "node --cpu-prof --cpu-prof-dir=.profiles --test --import tsx --test-reporter=spec \"test/**/*.test.ts\"",
+    "test:property": "node --test --import tsx --test-reporter=spec \"test/property/*.test.ts\"",
+    "test:property:dev": "node --test --import tsx --test-reporter=spec --watch \"test/property/*.test.ts\""
   },
   "peerDependencies": {
     "zod": "^4.1.5"
@@ -149,6 +151,7 @@
     "@types/slug": "5.0.9",
     "@types/wallabyjs": "0.0.15",
     "c8": "10.1.3",
+    "cspell": "9.2.1",
     "eslint": "9.35.0",
     "eslint-plugin-jsonc": "2.20.1",
     "eslint-plugin-perfectionist": "4.15.0",
@@ -176,7 +179,7 @@
     "typedoc-plugin-redirect": "1.2.0",
     "typedoc-plugin-zod": "1.4.2",
     "typescript": "5.9.2",
-    "typescript-eslint": "8.42.0"
+    "typescript-eslint": "8.43.0"
   },
   "publishConfig": {
     "access": "public",
@@ -185,9 +188,7 @@
   "knip": {
     "ignoreDependencies": [
       "@types/wallabyjs",
-      "markdownlint-cli2-formatter-pretty",
-      "expect-type",
-      "tsx"
+      "markdownlint-cli2-formatter-pretty"
     ],
     "ignore": [
       ".wallaby.js",
@@ -215,10 +216,12 @@
   "lint-staged": {
     "*.{ts,cts,js,json,yml,json5}": [
       "eslint --fix",
-      "prettier --write"
+      "prettier --write",
+      "cspell"
     ],
     "**/!(.github/prompts)/*.md": [
-      "prettier --write"
+      "prettier --write",
+      "cspell"
     ]
   },
   "prettier": {

package/src/assertion/assertion-async.ts

@@ -4,7 +4,13 @@ import z from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
 import { AssertionError } from '../error.js';
-import { isA, isAssertionFailure, isBoolean, isZodType } from '../guards.js';
+import {
+  isA,
+  isAssertionFailure,
+  isBoolean,
+  isError,
+  isZodType,
+} from '../guards.js';
 import { BupkisRegistry } from '../metadata.js';
 import {
   type AssertionAsync,
@@ -16,6 +22,7 @@ import {
   type AssertionSchemaAsync,
   type AssertionSlots,
   type ParsedResult,
+  type ParsedResultSuccess,
   type ParsedValues,
 } from './assertion-types.js';
 import { BupkisAssertion } from './assertion.js';
@@ -133,6 +140,8 @@ export class BupkisAssertionFunctionAsync<
         expected: result.expected,
         message: result.message ?? `Assertion ${this} failed`,
       });
+    } else if (isError(result) && result instanceof z.ZodError) {
+      throw this.translateZodError(stackStartFn, result, ...parsedValues);
     } else if (result as unknown) {
       throw new TypeError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
@@ -166,9 +175,31 @@ export class BupkisAssertionSchemaAsync<
     parsedValues: ParsedValues<Parts>,
     _args: unknown[],
     stackStartFn: (...args: any[]) => any,
-    _parseResult?: ParsedResult<Parts>,
+    parseResult?: ParsedResult<Parts>,
   ): Promise<void> {
-    // For async, fall back to standard implementation for now
+    // Check if we have cached validation result from parseValuesAsync
+    const cachedValidation = parseResult?.success
+      ? parseResult.subjectValidationResult
+      : undefined;
+
+    if (cachedValidation) {
+      debug(
+        'Using cached subject validation result from parseValuesAsync for %s',
+        this,
+      );
+      if (!cachedValidation.success) {
+        // Subject validation failed during parseValuesAsync, throw the cached error
+        throw this.translateZodError(
+          stackStartFn,
+          cachedValidation.error,
+          ...parsedValues,
+        );
+      }
+      // Subject validation passed, nothing more to do
+      return;
+    }
+
+    // Fall back to standard validation if no cached result
     const [subject] = parsedValues;
     try {
       await this.impl.parseAsync(subject);
@@ -180,6 +211,85 @@ export class BupkisAssertionSchemaAsync<
     }
   }
 
+  override async parseValuesAsync<Args extends readonly unknown[]>(
+    args: Args,
+  ): Promise<ParsedResult<Parts>> {
+    const { slots } = this;
+    const parsedValues: any[] = [];
+    const mismatch = this.maybeParseValuesArgMismatch(args);
+    if (mismatch) {
+      return mismatch;
+    }
+
+    let exactMatch = true;
+    let subjectValidationResult:
+      | undefined
+      | { data: any; success: true }
+      | { error: z.ZodError; success: false };
+
+    for (let i = 0; i < slots.length; i++) {
+      const slot = slots[i]!;
+      const arg = args[i];
+      const parsedLiteralResult = this.parseSlotForLiteral(slot, i, arg);
+      if (parsedLiteralResult === true) {
+        continue;
+      } else if (parsedLiteralResult !== false) {
+        return parsedLiteralResult;
+      }
+
+      // For the subject slot (first slot if it's unknown/any), try optimized validation
+      if (
+        i === 0 &&
+        (slot.def.type === 'unknown' || slot.def.type === 'any') &&
+        this.isSimpleSchemaAssertion()
+      ) {
+        try {
+          const result = await this.impl.parseAsync(arg);
+          subjectValidationResult = { data: result, success: true };
+          parsedValues.push(result); // Use validated data
+        } catch (error) {
+          if (isA(error, z.ZodError)) {
+            subjectValidationResult = { error, success: false };
+            parsedValues.push(arg); // Keep original for error reporting
+          } else {
+            throw error; // Re-throw non-Zod errors
+          }
+        }
+        exactMatch = false; // Subject was validated, so we know the exact type
+        continue;
+      }
+
+      // 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;
+      }
+
+      const result = await slot.safeParseAsync(arg);
+      if (!result.success) {
+        return {
+          success: false,
+        };
+      }
+      parsedValues.push(result.data);
+    }
+
+    const result: ParsedResultSuccess<Parts> = {
+      exactMatch,
+      parsedValues: parsedValues as unknown as ParsedValues<Parts>,
+      success: true,
+    };
+
+    // Add cached validation result if we performed optimization
+    if (subjectValidationResult) {
+      result.subjectValidationResult = subjectValidationResult;
+    }
+
+    return result;
+  }
+
   /**
    * Determines if this assertion can be optimized (simple single-subject
    * schema). Only simple assertions like ['to be a string'] with z.string()

package/src/assertion/assertion-sync.ts

@@ -8,13 +8,14 @@
 
 import Debug from 'debug';
 import { inspect } from 'util';
-import { type z } from 'zod/v4';
+import { z } from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
 import { AssertionError } from '../error.js';
 import {
   isAssertionFailure,
   isBoolean,
+  isError,
   isPromiseLike,
   isZodPromise,
   isZodType,
@@ -183,6 +184,8 @@ export class BupkisAssertionFunctionSync<
         expected: result.expected,
         message: result.message ?? `Assertion ${this} failed`,
       });
+    } else if (isError(result) && result instanceof z.ZodError) {
+      throw this.translateZodError(stackStartFn, result, ...parsedValues);
     } else if (result as unknown) {
       throw new TypeError(
         `Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`,
@@ -214,7 +217,7 @@ export class BupkisAssertionSchemaSync<
 {
   override execute(
     parsedValues: ParsedValues<Parts>,
-    args: unknown[],
+    _args: unknown[],
     stackStartFn: (...args: any[]) => any,
     parseResult?: ParsedResult<Parts>,
   ): void {

package/src/assertion/assertion-types.ts

@@ -227,9 +227,19 @@ export type AssertionImplAsync<Parts extends AssertionParts> =
  */
 export type AssertionImplFnAsync<Parts extends AssertionParts> = (
   ...values: ParsedValues<Parts>
-) => Promise<
-  AssertionFailure | boolean | void | z.ZodType<ParsedSubject<Parts>>
->;
+) =>
+  | AssertionImplFnReturnType<Parts>
+  | Promise<AssertionImplFnReturnType<Parts>>;
+
+/**
+ * The return type of an assertion implementation function.
+ */
+export type AssertionImplFnReturnType<Parts extends AssertionParts> =
+  | AssertionFailure
+  | boolean
+  | void
+  | z.ZodError
+  | z.ZodType<ParsedSubject<Parts>>;
 
 /**
  * The implementation of an assertion as a sync function.
@@ -248,7 +258,7 @@ export type AssertionImplFnAsync<Parts extends AssertionParts> = (
  */
 export type AssertionImplFnSync<Parts extends AssertionParts> = (
   ...values: ParsedValues<Parts>
-) => AssertionFailure | boolean | void | z.ZodType<ParsedSubject<Parts>>;
+) => AssertionImplFnReturnType<Parts>;
 
 /**
  * Maps an {@link AssertionPart} to a parameter to an {@link AssertionImpl}.

package/src/assertion/assertion.ts

@@ -13,7 +13,7 @@ import Debug from 'debug';
 import slug from 'slug';
 import { type ArrayValues } from 'type-fest';
 import { inspect } from 'util';
-import { z } from 'zod/v4';
+import { type z } from 'zod/v4';
 
 import { kStringLiteral } from '../constant.js';
 import { AssertionError } from '../error.js';
@@ -186,22 +186,7 @@ export abstract class BupkisAssertion<
     zodError: z.ZodError,
     ...values: ParsedValues<Parts>
   ): AssertionError {
-    const flat = z.flattenError(zodError);
-
-    let pretty = flat.formErrors.join('; ');
-    for (const [keypath, errors] of Object.entries(flat.fieldErrors)) {
-      pretty += `; ${keypath}: ${(errors as unknown[]).join('; ')}`;
-    }
-
-    const [actual, ...expected] = values as unknown as [unknown, ...unknown[]];
-
-    return new AssertionError({
-      actual,
-      expected: expected.length === 1 ? expected[0] : expected,
-      message: `Assertion ${this} failed: ${pretty}`,
-      operator: `${this}`,
-      stackStartFn,
-    });
+    return AssertionError.fromZodError(zodError, stackStartFn, values);
   }
 
   /**