feat(v4): allow passing extra args to apply() (#6337)

Closes #5909.

Author: Deepshekhar Das

packages/docs/content/api.mdx

@@ -3340,3 +3340,16 @@ z.parse(schema, null); // => null
 ```
 </Tab>
 </Tabs>
+
+Additional arguments are passed through to the function:
+
+```ts
+function withDefault<T extends z.ZodType>(schema: T, value: z.output<T>) {
+  return schema.nullish().transform((val) => val ?? value);
+}
+
+const schema = z.string().apply(withDefault, "anonymous");
+
+schema.parse(undefined); // => "anonymous"
+schema.parse("sandwich"); // => "sandwich"
+```

packages/zod/src/v4/classic/schemas.ts

@@ -159,7 +159,7 @@ export interface ZodType<
    * ```
    */
   isNullable(): boolean;
-  apply<T>(fn: (schema: this) => T): T;
+  apply<T, TArgs extends unknown[] = []>(fn: (schema: this, ...args: TArgs) => T, ...args: TArgs): T;
 }
 
 export interface _ZodType<out Internals extends core.$ZodTypeInternals = core.$ZodTypeInternals>
@@ -292,8 +292,8 @@ function _zodTypeMethods(): _LazyMethodsOf<ZodType> {
     isNullable() {
       return this.safeParse(null).success;
     },
-    apply(fn) {
-      return fn(this);
+    apply(fn, ...args) {
+      return args.length === 0 ? fn(this) : fn(this, ...args);
     },
   };
 }

packages/zod/src/v4/classic/tests/apply.test.ts

@@ -57,3 +57,30 @@ test("The callback's return value becomes the apply's return value.", () => {
   expect(result).toBe(symbol);
   expectTypeOf<typeof result>().toEqualTypeOf<symbol>();
 });
+
+test("apply forwards extra args to the callback", () => {
+  const withDefault = <TSchema extends z.ZodType>(schema: TSchema, defaultValue: z.output<TSchema>) => {
+    return schema.nullish().transform((x) => x ?? defaultValue);
+  };
+
+  const schema = z.string().apply(withDefault, "default-id");
+
+  expect(schema.parse(undefined)).toBe("default-id");
+  expect(schema.parse(null)).toBe("default-id");
+  expect(schema.parse("value")).toBe("value");
+  expectTypeOf<z.infer<typeof schema>>().toEqualTypeOf<string>();
+});
+
+test("apply type-checks the extra args", () => {
+  const withMin = (schema: z.ZodString, n: number) => schema.min(n);
+
+  expect(z.string().apply(withMin, 3).parse("abcd")).toBe("abcd");
+  expectTypeOf(z.number().apply<z.ZodNumber>((schema) => schema.min(0))).toEqualTypeOf<z.ZodNumber>();
+
+  // @ts-expect-error wrong arg type
+  z.string().apply(withMin, "3");
+  // @ts-expect-error missing arg
+  z.string().apply(withMin);
+  // @ts-expect-error extra arg for a single-parameter callback
+  z.string().apply((schema: z.ZodString) => schema, 3);
+});

packages/zod/src/v4/mini/schemas.ts

@@ -34,7 +34,7 @@ export interface ZodMiniType<
     data: unknown,
     params?: core.ParseContext<core.$ZodIssue>
   ): Promise<util.SafeParseResult<core.output<this>>>;
-  apply<T>(fn: (schema: this) => T): T;
+  apply<T, TArgs extends unknown[] = []>(fn: (schema: this, ...args: TArgs) => T, ...args: TArgs): T;
 }
 
 interface _ZodMiniType<out Internals extends core.$ZodTypeInternals = core.$ZodTypeInternals>
@@ -95,8 +95,8 @@ function _zodMiniTypeMethods(): util.LazyMethodsOf<ZodMiniType> {
       reg.add(this, meta);
       return this;
     },
-    apply(fn) {
-      return fn(this);
+    apply(fn, ...args) {
+      return args.length === 0 ? fn(this) : fn(this, ...args);
     },
   };
 }

packages/zod/src/v4/mini/tests/apply.test.ts

@@ -22,3 +22,36 @@ test("The callback's return value becomes the apply's return value.", () => {
   expect(result).toBe(symbol);
   expectTypeOf<typeof result>().toEqualTypeOf<symbol>();
 });
+
+test("apply forwards extra args to the callback", () => {
+  const calls: unknown[] = [];
+  const capture = (schema: z.ZodMiniString, ...args: unknown[]) => {
+    calls.push(schema, ...args);
+    return schema;
+  };
+
+  const schema = z.string();
+  const result = schema.apply(capture, "id", 42);
+
+  expect(calls[0]).toBe(schema);
+  expect(calls[1]).toBe("id");
+  expect(calls[2]).toBe(42);
+  expect(z.parse(result, "value")).toBe("value");
+  expectTypeOf<z.infer<typeof result>>().toEqualTypeOf<string>();
+});
+
+test("apply type-checks the extra args", () => {
+  const withMin = (schema: z.ZodMiniString, n: number) => schema.check(z.minLength(n));
+
+  expect(z.parse(z.string().apply(withMin, 3), "abcd")).toBe("abcd");
+  expectTypeOf(
+    z.number().apply<z.ZodMiniNumber>((schema) => schema.check(z.minimum(0)))
+  ).toEqualTypeOf<z.ZodMiniNumber>();
+
+  // @ts-expect-error wrong arg type
+  z.string().apply(withMin, "3");
+  // @ts-expect-error missing arg
+  z.string().apply(withMin);
+  // @ts-expect-error extra arg for a single-parameter callback
+  z.string().apply((schema: z.ZodMiniString) => schema, 3);
+});