Merge pull request #5743 from NomicFoundation/zod-conditionalUnionType

Introduce the Zod `conditionalUnionType` helper

config-v-next/eslint.cjs

@@ -261,7 +261,7 @@ function createConfig(
           selector:
             "CallExpression[callee.object.name='z'][callee.property.name=union]",
           message:
-            "Use the unionType helper from the zod utils package instead, as it provides better error messages.",
+            "Use the conditionalUnionType or unionType helpers from the zod utils package instead, as it provides better error messages.",
         },
       ],
       "@typescript-eslint/restrict-plus-operands": "error",
@@ -398,7 +398,7 @@ function createConfig(
               name: "zod",
               importNames: ["union"],
               message:
-                "Use the unionType helper from the zod utils package instead, as it provides better error messages.",
+                "Use the conditionalUnionType or unionType helpers from the zod utils package instead, as it provides better error messages.",
             },
           ],
         },

v-next/hardhat-mocha-test-runner/src/hookHandlers/config.ts

@@ -1,7 +1,9 @@
 import type { ConfigHooks } from "@ignored/hardhat-vnext/types/hooks";
 
+import { isObject } from "@ignored/hardhat-vnext-utils/lang";
 import { resolveFromRoot } from "@ignored/hardhat-vnext-utils/path";
 import {
+  conditionalUnionType,
   unionType,
   validateUserConfigZodType,
 } from "@ignored/hardhat-vnext-zod-utils";
@@ -72,10 +74,17 @@ const mochaConfigType = z.object({
 
 const userConfigType = z.object({
   mocha: z.optional(mochaConfigType),
-  test: unionType(
-    [z.object({ mocha: z.string().optional() }), z.string()],
-    "Expected a string or an object with an optional 'mocha' property",
-  ).optional(),
+  paths: z
+    .object({
+      test: conditionalUnionType(
+        [
+          [(data) => typeof data === "string", z.string()],
+          [isObject, z.object({ mocha: z.string().optional() })],
+        ],
+        "Expected a string or an object with an optional 'mocha' property",
+      ).optional(),
+    })
+    .optional(),
 });
 
 export default async (): Promise<Partial<ConfigHooks>> => {

v-next/hardhat-node-test-runner/src/hookHandlers/config.ts

@@ -1,17 +1,25 @@
 import type { ConfigHooks } from "@ignored/hardhat-vnext/types/hooks";
 
+import { isObject } from "@ignored/hardhat-vnext-utils/lang";
 import { resolveFromRoot } from "@ignored/hardhat-vnext-utils/path";
 import {
-  unionType,
+  conditionalUnionType,
   validateUserConfigZodType,
 } from "@ignored/hardhat-vnext-zod-utils";
 import { z } from "zod";
 
 const userConfigType = z.object({
-  test: unionType(
-    [z.object({ nodeTest: z.string().optional() }), z.string()],
-    "Expected a string or an object with an optional 'nodeTest' property",
-  ).optional(),
+  paths: z
+    .object({
+      test: conditionalUnionType(
+        [
+          [isObject, z.object({ nodeTest: z.string().optional() })],
+          [(data) => typeof data === "string", z.string()],
+        ],
+        "Expected a string or an object with an optional 'nodeTest' property",
+      ).optional(),
+    })
+    .optional(),
 });
 
 export default async (): Promise<Partial<ConfigHooks>> => {

v-next/hardhat-zod-utils/package.json

@@ -59,6 +59,9 @@
     "typescript-eslint": "7.7.1",
     "zod": "^3.23.8"
   },
+  "dependencies": {
+    "@ignored/hardhat-vnext-utils": "workspace:^3.0.0-next.2"
+  },
   "peerDependencies": {
     "zod": "^3.23.8"
   }

v-next/hardhat-zod-utils/src/index.ts

@@ -1,5 +1,6 @@
 import type { ZodTypeDef, ZodType } from "zod";
 
+import { isObject } from "@ignored/hardhat-vnext-utils/lang";
 import { z } from "zod";
 
 /**
@@ -19,6 +20,14 @@ export interface HardhatUserConfigValidationError {
 /**
  * A Zod untagged union type that returns a custom error message if the value
  * is missing or invalid.
+ *
+ * WARNING: In most cases you should use {@link conditionalUnionType} instead.
+ *
+ * This union type is valid for simple cases, where the union is made of
+ * primitive or simple types.
+ *
+ * If you have a type that's complex, like an object or array, you must use
+ * {@link conditionalUnionType}.
  */
 export const unionType = (
   types: Parameters<typeof z.union>[0],
@@ -31,6 +40,101 @@ export const unionType = (
     }),
   });
 
+/**
+ * A Zod union type that allows you to provide hints to Zod about which of the
+ * type variant it should use.
+ *
+ * It receives an array of tuples, where each tuple contains a predicate
+ * function and a ZodType. The predicate function takes the data to be parsed
+ * and returns a boolean. If the predicate function returns true, the ZodType
+ * is used to parse the data.
+ *
+ * If none of the predicates returns true, an error is added to the context
+ * with the noMatchMessage message.
+ *
+ * For example, you can use this to conditionally validate a union type based
+ * on the values `typeof` and its fields:
+ *
+ * @example
+ * ```ts
+ * const fooType = conditionalUnionType(
+ *   [
+ *     [(data) => typeof data === "string", z.string()],
+ *     [(data) => Array.isArray(data), z.array(z.string()).nonempty()],
+ *     [(data) => isObject(data), z.object({foo: z.string().optional()})]
+ *   ],
+ *   "Expected a string, an array of strings, or an object with an optional 'foo' property",
+ * );
+ * ```
+ *
+ * @param cases An array of tuples of a predicate function and a ZodType.
+ * @param noMatchMessage THe error message to return if none of the predicates
+ * returns true.
+ * @returns The conditional union ZodType.
+ */
+export const conditionalUnionType = (
+  cases: Array<[predicate: (data: unknown) => boolean, zodType: ZodType<any>]>,
+  noMatchMessage: string,
+) =>
+  z.any().superRefine((data, ctx) => {
+    const matchingCase = cases.find(([predicate]) => predicate(data));
+    if (matchingCase === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: noMatchMessage,
+      });
+      return;
+    }
+
+    const zodeType = matchingCase[1];
+
+    const parsedData = zodeType.safeParse(data);
+    if (parsedData.error !== undefined) {
+      for (const issue of parsedData.error.issues) {
+        ctx.addIssue(issue);
+      }
+    }
+  });
+
+/**
+ * Creates a Zod type to validate that a field of an object doesn't exist.
+ *
+ * This is useful when you have a {@link conditionalUnionType} that represents
+ * a union of object types with incompatible fields between each other.
+ *
+ * @example
+ * ```ts
+ * const typeWithFoo = z.object({
+ *   foo: z.string(),
+ *   bar: unexpectedFieldType("This field is incompatible with `foo`"),
+ * });
+ *
+ * const typeWithBar = z.object({
+ *   bar: z.string(),
+ *   foo: unexpectedFieldType("This field is incompatible with `bar`"),
+ * });
+ *
+ * const union = conditionalUnionType(
+ *   [
+ *     [(data) => isObject(data) && "foo" in data, typeWithFoo],
+ *     [(data) => isObject(data) && "bar" in data, typeWithBar],
+ *   ],
+ *   "Expected an object with either a `foo` or a `bar` field",
+ * );
+ * ```
+ *
+ * @param errorMessage The error message to display if the field is present.
+ * @returns A Zod type that validates that a field of an object doesn't exist.
+ */
+export const incompatibleFieldType = (errorMessage = "Unexpected field") =>
+  z
+    .never({
+      errorMap: () => ({
+        message: errorMessage,
+      }),
+    })
+    .optional();
+
 /**
  * A Zod type to validate Hardhat's ConfigurationVariable objects.
  */
@@ -42,16 +146,22 @@ export const configurationVariableType = z.object({
 /**
  * A Zod type to validate Hardhat's SensitiveString values.
  */
-export const sensitiveStringType = unionType(
-  [z.string(), configurationVariableType],
+export const sensitiveStringType = conditionalUnionType(
+  [
+    [(data) => typeof data === "string", z.string()],
+    [isObject, configurationVariableType],
+  ],
   "Expected a string or a Configuration Variable",
 );
 
 /**
  * A Zod type to validate Hardhat's SensitiveString values that expect a URL.
  */
-export const sensitiveUrlType = unionType(
-  [z.string().url(), configurationVariableType],
+export const sensitiveUrlType = conditionalUnionType(
+  [
+    [(data) => typeof data === "string", z.string().url()],
+    [isObject, configurationVariableType],
+  ],
   "Expected a URL or a Configuration Variable",
 );
 
@@ -64,15 +174,15 @@ export const sensitiveUrlType = unionType(
  * from the root of the config object, so that they are correctly reported to
  * the user.
  */
-export async function validateUserConfigZodType<
+export function validateUserConfigZodType<
   Output,
   Def extends ZodTypeDef = ZodTypeDef,
   Input = Output,
 >(
   hardhatUserConfig: HardhatUserConfigToValidate,
   configType: ZodType<Output, Def, Input>,
-): Promise<HardhatUserConfigValidationError[]> {
-  const result = await configType.safeParseAsync(hardhatUserConfig);
+): HardhatUserConfigValidationError[] {
+  const result = configType.safeParse(hardhatUserConfig);
 
   if (result.success) {
     return [];