Changes to optionality (#2633)

- address replaced `optionaility` with `optin` and `optout`
- that also fixed question marks on optional schemas with
transformations
  - colinhacks/zod#4322
- new bug: colinhacks/zod#4407
- also, it appears to change the way `.meta()` works: now it seems to
merge the metadata

Author: RobinTail

express-zod-api/package.json

@@ -76,7 +76,7 @@
     "express-fileupload": "^1.5.0",
     "http-errors": "^2.0.0",
     "typescript": "^5.1.3",
-    "zod": "3.25.0-beta.20250518T002810"
+    "zod": "3.25.0-beta.20250519T051133"
   },
   "peerDependenciesMeta": {
     "@types/compression": {

express-zod-api/src/common-helpers.ts

@@ -1,9 +1,4 @@
-import type {
-  $ZodObject,
-  $ZodTransform,
-  $ZodType,
-  $ZodTypeInternals,
-} from "zod/v4/core";
+import type { $ZodObject, $ZodTransform, $ZodType } from "zod/v4/core";
 import { Request } from "express";
 import * as R from "ramda";
 import { globalRegistry, z } from "zod/v4";
@@ -175,17 +170,10 @@ export const getTransformedType = R.tryCatch(
   R.always(undefined),
 );
 
-const requestOptionality: Array<$ZodTypeInternals["optionality"]> = [
-  "optional",
-  "defaulted",
-];
 export const isOptional = (
-  { _zod: { optionality } }: $ZodType,
+  { _zod: { optin, optout } }: $ZodType,
   { isResponse }: { isResponse: boolean },
-) =>
-  isResponse
-    ? optionality === "optional"
-    : optionality && requestOptionality.includes(optionality);
+) => (isResponse ? optout : optin) === "optional";
 
 /** @desc can still be an array, use Array.isArray() or rather R.type() to exclude that case */
 export const isObject = (subject: unknown) =>

express-zod-api/src/zod-plugin.ts

@@ -93,7 +93,7 @@ const brandSetter = function (
   const { [metaSymbol]: internal = { examples: [] }, ...rest } =
     this.meta() || {};
   return this.meta({
-    ...rest,
+    ...rest, // @todo this may no longer be required since it seems that .meta() merges now, not just overrides
     [metaSymbol]: { ...internal, brand },
   });
 };

express-zod-api/tests/__snapshots__/env.spec.ts.snap

@@ -249,19 +249,23 @@ exports[`Environment checks > Zod imperfections > circular object schema has no
 }
 `;
 
-exports[`Environment checks > Zod imperfections > meta overrides, does not merge 1`] = `
+exports[`Environment checks > Zod new features > input examples of transformations 1`] = `
 {
-  "title": "last",
+  "$schema": "https://json-schema.org/draft-2020-12/schema",
+  "examples": [
+    "test",
+  ],
+  "type": "string",
 }
 `;
 
-exports[`Environment checks > Zod new features > input examples of transformations 1`] = `
+exports[`Environment checks > Zod new features > meta() merge, not just overrides 1`] = `
 {
-  "$schema": "https://json-schema.org/draft-2020-12/schema",
+  "description": "some",
   "examples": [
     "test",
   ],
-  "type": "string",
+  "title": "last",
 }
 `;
 

express-zod-api/tests/__snapshots__/zts.spec.ts.snap

@@ -274,7 +274,7 @@ exports[`zod-to-ts > z.optional() > Zod 4: should add question mark only to opti
 "{
     optional?: string | undefined;
     required: string;
-    transform: number;
+    transform?: number | undefined;
     or: number | string;
     tuple?: [
         string,

express-zod-api/tests/documentation-helpers.spec.ts

@@ -177,7 +177,7 @@ describe("Documentation helpers", () => {
 
   describe("depictUnion()", () => {
     test("should set discriminator prop for such union", () => {
-      const zodSchema = z.discriminatedUnion([
+      const zodSchema = z.discriminatedUnion("status", [
         z.object({ status: z.literal("success"), data: z.any() }),
         z.object({
           status: z.literal("error"),

express-zod-api/tests/env.spec.ts

@@ -34,7 +34,7 @@ describe("Environment checks", () => {
     test("discriminated unions are not depicted well", () => {
       expect(
         z.toJSONSchema(
-          z.discriminatedUnion([
+          z.discriminatedUnion("status", [
             z.object({ status: z.literal("success"), data: z.any() }),
             z.object({
               status: z.literal("error"),
@@ -50,15 +50,6 @@ describe("Environment checks", () => {
       expect(R.omit(["$schema"], json)).toEqual({});
     });
 
-    test("meta overrides, does not merge", () => {
-      const schema = z
-        .string()
-        .meta({ examples: ["test"] })
-        .meta({ description: "some" })
-        .meta({ title: "last" });
-      expect(schema.meta()).toMatchSnapshot();
-    });
-
     test("circular object schema has no sign of getter in its shape", () => {
       const schema = z.object({
         name: z.string(),
@@ -88,6 +79,15 @@ describe("Environment checks", () => {
   });
 
   describe("Zod new features", () => {
+    test("meta() merge, not just overrides", () => {
+      const schema = z
+        .string()
+        .meta({ examples: ["test"] })
+        .meta({ description: "some" })
+        .meta({ title: "last" });
+      expect(schema.meta()).toMatchSnapshot();
+    });
+
     test("object shape conveys the keys optionality", () => {
       const schema = z.object({
         one: z.boolean(),
@@ -104,16 +104,19 @@ describe("Environment checks", () => {
         "three",
         "four",
       ]);
-      expect(schema._zod.def.shape.one._zod.optionality).toBeUndefined();
-      expect(schema._zod.def.shape.two._zod.optionality).toBe("optional");
-      expect(schema._zod.def.shape.three._zod.optionality).toBe("defaulted");
-      /** @link https://github.com/colinhacks/zod/issues/4322 */
-      expect(schema._zod.def.shape.four._zod.optionality).not.toBe("optional"); // <— undefined
+      expect(schema._zod.def.shape.one._zod.optin).toBeUndefined();
+      expect(schema._zod.def.shape.one._zod.optout).toBeUndefined();
+      expect(schema._zod.def.shape.two._zod.optin).toBe("optional");
+      expect(schema._zod.def.shape.two._zod.optout).toBe("optional");
+      expect(schema._zod.def.shape.three._zod.optin).toBe("optional");
+      expect(schema._zod.def.shape.three._zod.optout).toBe(undefined);
+      expect(schema._zod.def.shape.four._zod.optin).toBe("optional");
+      expect(schema._zod.def.shape.four._zod.optout).toBe(undefined);
       expectTypeOf<z.input<typeof schema>>().toEqualTypeOf<{
         one: boolean;
         two?: boolean | undefined;
         three?: boolean | undefined;
-        four: boolean | undefined;
+        four?: boolean | undefined;
       }>();
       expectTypeOf<z.output<typeof schema>>().toEqualTypeOf<{
         one: boolean;

express-zod-api/tests/zts.spec.ts

@@ -207,10 +207,6 @@ describe("zod-to-ts", () => {
       expect(printNodeTest(node)).toMatchSnapshot();
     });
 
-    /**
-     * @todo revisit when optional+transform fixed
-     * @link https://github.com/colinhacks/zod/issues/4322
-     * */
     test("Zod 4: should add question mark only to optional props", () => {
       const node = zodToTs(objectWithOptionals, { ctx });
       expect(printNodeTest(node)).toMatchSnapshot();

package.json

@@ -48,7 +48,7 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.32.1",
     "vitest": "^3.1.3",
-    "zod": "3.25.0-beta.20250518T002810"
+    "zod": "3.25.0-beta.20250519T051133"
   },
   "resolutions": {
     "**/@scarf/scarf": "npm:[email protected]"

yarn.lock

@@ -3123,7 +3123,7 @@ yocto-queue@^0.1.0:
   resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-0.1.0.tgz#0294eb3dee05028d31ee1a5fa2c556a6aaf10a1b"
   integrity sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==
 
-[email protected].20250518T002810:
-  version "3.25.0-beta.20250518T002810"
-  resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.0-beta.20250518T002810.tgz#9ac105aea4b6e0d072a382893c3e6556670048c8"
-  integrity sha512-3/aIqMbUXG9EjTelJkDcWd+izJP5MxFgQEMSYI8n41pwYhRDYYxy2dnbkgfNcnLbFZ9uByZn9XXqHTh05QHqSQ==
+[email protected].20250519T051133:
+  version "3.25.0-beta.20250519T051133"
+  resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.0-beta.20250519T051133.tgz#e2bf36f81255419f761f591ca983b792beb5ac0a"
+  integrity sha512-kiLlHJfDDF2JJ2RcCvxhysRDnrSEHtOuHMLtG+PESvLEScEujB8ccvZ6KgvBxS1ifwpjlL/hkjqwvDzKKoryjQ==