improve cross-version zod support

Author: carderne

.changeset/zod-4-support.md

@@ -9,6 +9,6 @@
 "@trigger.dev/schema-to-json": minor
 ---
 
-Add zod v4 support. You can now use zod 3.25+ or zod 4 (the minimum zod 3 version is now 3.25.0). `zod` is now a peer dependency of `@trigger.dev/core`, `@trigger.dev/sdk`, `@trigger.dev/redis-worker`, and `@trigger.dev/schema-to-json`, so it shares a single copy with your project; if you depend on `@trigger.dev/core` directly, add `zod` to your own dependencies.
+Add Zod 4 support. You can now use Zod 3.25.76+ or Zod 4.
 
-The published type declarations are built against zod 4. If you are still on zod 3, keep `skipLibCheck: true` in your tsconfig (the default in Trigger.dev's templates).
+Zod remains a runtime dependency of packages that execute schemas, so existing and new installations continue to receive it automatically. The matching peer dependency range allows package managers to reuse either a compatible Zod 3 or Zod 4 installation from your project.

packages/build/package.json

@@ -96,13 +96,11 @@
     "tsx": "4.17.0",
     "typescript": "6.0.3",
     "typescript5": "npm:typescript@5.9.3",
-    "typescript7": "npm:typescript@7.0.2",
-    "zod": "4.4.3"
+    "typescript7": "npm:typescript@7.0.2"
   },
   "peerDependencies": {
     "@typescript/typescript6": "^6.0.0",
-    "typescript": ">=5.0.0",
-    "zod": "^3.25.0 || ^4.0.0"
+    "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "@typescript/typescript6": {

packages/core/package.json

@@ -229,6 +229,7 @@
     "std-env": "^3.8.1",
     "tinyexec": "^0.3.2",
     "uncrypto": "^0.1.3",
+    "zod": "^3.25.76 || ^4.0.0",
     "zod-validation-error": "^5.0.0"
   },
   "devDependencies": {
@@ -245,8 +246,7 @@
     "superjson": "^2.2.1",
     "ts-essentials": "10.0.1",
     "tshy": "^4.1.3",
-    "tsx": "4.17.0",
-    "zod": "4.4.3"
+    "tsx": "4.17.0"
   },
   "engines": {
     "node": ">=18.20.0"
@@ -677,6 +677,6 @@
   "types": "./dist/commonjs/index.d.ts",
   "module": "./dist/esm/index.js",
   "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
+    "zod": "^3.25.76 || ^4.0.0"
   }
 }

packages/core/src/schemas/eventFilter.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const stringPatternMatchers = [
   z.object({

packages/core/src/schemas/json.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 const LiteralSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 type Literal = z.infer<typeof LiteralSchema>;

packages/core/src/v3/apiClient/core.ts

@@ -1,5 +1,6 @@
-import { z } from "zod";
-import { fromZodError } from "zod-validation-error";
+import { z as z3 } from "zod/v3";
+import { z } from "zod/v4";
+import { fromZodError, ValidationError } from "zod-validation-error/v4";
 import type { RetryOptions } from "../schemas/index.js";
 import { calculateNextRetryDelay } from "../utils/retries.js";
 import { ApiConnectionError, ApiError, ApiSchemaValidationError } from "./errors.js";
@@ -12,6 +13,10 @@ import { SemanticInternalAttributes } from "../semanticInternalAttributes.js";
 import type { TriggerTracer } from "../tracer.js";
 import { randomUUID } from "../utils/crypto.js";
 import { accessoryAttributes } from "../utils/styleAttributes.js";
+import type {
+  AnyZodSchema,
+  inferZodSchemaOutput,
+} from "../types/schemas.js";
 import type {
   CursorPageParams,
   CursorPageResponse,
@@ -71,16 +76,16 @@ interface FetchOffsetLimitPageParams extends OffsetLimitPageParams {
   query?: URLSearchParams;
 }
 
-export function zodfetch<TResponseBodySchema extends z.ZodTypeAny>(
+export function zodfetch<TResponseBodySchema extends AnyZodSchema>(
   schema: TResponseBodySchema,
   url: string,
   requestInit?: RequestInit,
-  options?: ZodFetchOptions<z.output<TResponseBodySchema>>
-): ApiPromise<z.output<TResponseBodySchema>> {
+  options?: ZodFetchOptions<inferZodSchemaOutput<TResponseBodySchema>>
+): ApiPromise<inferZodSchemaOutput<TResponseBodySchema>> {
   return new ApiPromise(_doZodFetch(schema, url, requestInit, options));
 }
 
-export function zodfetchCursorPage<TItemSchema extends z.ZodTypeAny>(
+export function zodfetchCursorPage<TItemSchema extends AnyZodSchema>(
   schema: TItemSchema,
   url: string,
   params: FetchCursorPageParams,
@@ -101,13 +106,21 @@ export function zodfetchCursorPage<TItemSchema extends z.ZodTypeAny>(
     query.set("page[before]", params.before);
   }
 
-  const cursorPageSchema = z.object({
-    data: z.array(schema),
-    pagination: z.object({
-      next: z.string().optional(),
-      previous: z.string().optional(),
-    }),
-  });
+  const cursorPageSchema = "_zod" in schema
+    ? z.object({
+        data: z.array(schema as any),
+        pagination: z.object({
+          next: z.string().optional(),
+          previous: z.string().optional(),
+        }),
+      })
+    : z3.object({
+        data: z3.array(schema as any),
+        pagination: z3.object({
+          next: z3.string().optional(),
+          previous: z3.string().optional(),
+        }),
+      });
 
   const $url = new URL(url);
   $url.search = query.toString();
@@ -117,7 +130,7 @@ export function zodfetchCursorPage<TItemSchema extends z.ZodTypeAny>(
   return new CursorPagePromise(fetchResult, schema, url, params, requestInit, options);
 }
 
-export function zodfetchOffsetLimitPage<TItemSchema extends z.ZodTypeAny>(
+export function zodfetchOffsetLimitPage<TItemSchema extends AnyZodSchema>(
   schema: TItemSchema,
   url: string,
   params: FetchOffsetLimitPageParams,
@@ -134,22 +147,33 @@ export function zodfetchOffsetLimitPage<TItemSchema extends z.ZodTypeAny>(
     query.set("page", String(params.page));
   }
 
-  const offsetLimitPageSchema = z.object({
-    data: z.array(schema),
-    pagination: z.object({
-      currentPage: z.coerce.number(),
-      totalPages: z.coerce.number(),
-      count: z.coerce.number(),
-    }),
-  });
+  const offsetLimitPageSchema = "_zod" in schema
+    ? z.object({
+        data: z.array(schema as any),
+        pagination: z.object({
+          currentPage: z.coerce.number(),
+          totalPages: z.coerce.number(),
+          count: z.coerce.number(),
+        }),
+      })
+    : z3.object({
+        data: z3.array(schema as any),
+        pagination: z3.object({
+          currentPage: z3.coerce.number(),
+          totalPages: z3.coerce.number(),
+          count: z3.coerce.number(),
+        }),
+      });
 
   const $url = new URL(url);
   $url.search = query.toString();
 
   const fetchResult = _doZodFetch(offsetLimitPageSchema, $url.href, requestInit, options);
 
   return new OffsetLimitPagePromise(
-    fetchResult as Promise<ZodFetchResult<OffsetLimitPageResponse<z.output<TItemSchema>>>>,
+    fetchResult as Promise<
+      ZodFetchResult<OffsetLimitPageResponse<inferZodSchemaOutput<TItemSchema>>>
+    >,
     schema,
     url,
     params,
@@ -195,12 +219,12 @@ async function traceZodFetch<T>(
   );
 }
 
-async function _doZodFetch<TResponseBodySchema extends z.ZodTypeAny>(
+async function _doZodFetch<TResponseBodySchema extends AnyZodSchema>(
   schema: TResponseBodySchema,
   url: string,
   requestInit?: PromiseOrValue<RequestInit>,
-  options?: ZodFetchOptions<z.output<TResponseBodySchema>>
-): Promise<ZodFetchResult<z.output<TResponseBodySchema>>> {
+  options?: ZodFetchOptions<inferZodSchemaOutput<TResponseBodySchema>>
+): Promise<ZodFetchResult<inferZodSchemaOutput<TResponseBodySchema>>> {
   let $requestInit = await requestInit;
 
   return traceZodFetch({ url, requestInit: $requestInit, options }, async (span) => {
@@ -223,13 +247,13 @@ async function _doZodFetch<TResponseBodySchema extends z.ZodTypeAny>(
   });
 }
 
-async function _doZodFetchWithRetries<TResponseBodySchema extends z.ZodTypeAny>(
+async function _doZodFetchWithRetries<TResponseBodySchema extends AnyZodSchema>(
   schema: TResponseBodySchema,
   url: string,
   requestInit?: RequestInit,
   options?: ZodFetchOptions,
   attempt = 1
-): Promise<ZodFetchResult<z.output<TResponseBodySchema>>> {
+): Promise<ZodFetchResult<inferZodSchemaOutput<TResponseBodySchema>>> {
   try {
     const response = await context.with(suppressTracing(context.active()), () =>
       fetch(url, requestInitWithCache(requestInit))
@@ -467,12 +491,12 @@ export class ApiPromise<T> extends Promise<T> {
   }
 }
 
-export class CursorPagePromise<TItemSchema extends z.ZodTypeAny>
-  extends ApiPromise<CursorPage<z.output<TItemSchema>>>
-  implements AsyncIterable<z.output<TItemSchema>>
+export class CursorPagePromise<TItemSchema extends AnyZodSchema>
+  extends ApiPromise<CursorPage<inferZodSchemaOutput<TItemSchema>>>
+  implements AsyncIterable<inferZodSchemaOutput<TItemSchema>>
 {
   constructor(
-    result: Promise<ZodFetchResult<CursorPageResponse<z.output<TItemSchema>>>>,
+    result: Promise<ZodFetchResult<CursorPageResponse<inferZodSchemaOutput<TItemSchema>>>>,
     private schema: TItemSchema,
     private url: string,
     private params: FetchCursorPageParams,
@@ -487,7 +511,9 @@ export class CursorPagePromise<TItemSchema extends z.ZodTypeAny>
     );
   }
 
-  #fetchPage(params: Omit<CursorPageParams, "limit">): Promise<CursorPage<z.output<TItemSchema>>> {
+  #fetchPage(
+    params: Omit<CursorPageParams, "limit">
+  ): Promise<CursorPage<inferZodSchemaOutput<TItemSchema>>> {
     return zodfetchCursorPage(
       this.schema,
       this.url,
@@ -512,12 +538,12 @@ export class CursorPagePromise<TItemSchema extends z.ZodTypeAny>
   }
 }
 
-export class OffsetLimitPagePromise<TItemSchema extends z.ZodTypeAny>
-  extends ApiPromise<OffsetLimitPage<z.output<TItemSchema>>>
-  implements AsyncIterable<z.output<TItemSchema>>
+export class OffsetLimitPagePromise<TItemSchema extends AnyZodSchema>
+  extends ApiPromise<OffsetLimitPage<inferZodSchemaOutput<TItemSchema>>>
+  implements AsyncIterable<inferZodSchemaOutput<TItemSchema>>
 {
   constructor(
-    result: Promise<ZodFetchResult<OffsetLimitPageResponse<z.output<TItemSchema>>>>,
+    result: Promise<ZodFetchResult<OffsetLimitPageResponse<inferZodSchemaOutput<TItemSchema>>>>,
     private schema: TItemSchema,
     private url: string,
     private params: FetchOffsetLimitPageParams,
@@ -538,7 +564,7 @@ export class OffsetLimitPagePromise<TItemSchema extends z.ZodTypeAny>
 
   #fetchPage(
     params: Omit<FetchOffsetLimitPageParams, "limit">
-  ): Promise<OffsetLimitPage<z.output<TItemSchema>>> {
+  ): Promise<OffsetLimitPage<inferZodSchemaOutput<TItemSchema>>> {
     return zodfetchOffsetLimitPage(
       this.schema,
       this.url,
@@ -643,17 +669,18 @@ function injectRequestIdempotencyKey(
   };
 }
 
-export type ZodFetchSSEMessageValueSchema<
-  TDiscriminatedUnion extends z.ZodDiscriminatedUnion<any, any>,
-> = z.ZodFirstPartySchemaTypes | TDiscriminatedUnion;
+export type ZodFetchSSEMessageValueSchema<TSchema extends AnyZodSchema = AnyZodSchema> =
+  TSchema;
 
 export interface ZodFetchSSEMessageCatalogSchema {
-  [key: string]: ZodFetchSSEMessageValueSchema<any>;
+  [key: string]: AnyZodSchema;
 }
 
 export type ZodFetchSSEMessageHandlers<TCatalogSchema extends ZodFetchSSEMessageCatalogSchema> =
   Partial<{
-    [K in keyof TCatalogSchema]: (payload: z.infer<TCatalogSchema[K]>) => Promise<void> | void;
+    [K in keyof TCatalogSchema]: (
+      payload: inferZodSchemaOutput<TCatalogSchema[K]>
+    ) => Promise<void> | void;
   }>;
 
 export type ZodFetchSSEOptions<TMessageCatalog extends ZodFetchSSEMessageCatalogSchema> = {
@@ -698,6 +725,10 @@ export class ZodFetchSSEResult<TMessageCatalog extends ZodFetchSSEMessageCatalog
 
       const schema = this.options.messages[type];
 
+      if (!schema) {
+        return;
+      }
+
       const result = schema.safeParse(payload);
 
       if (result.success) {
@@ -733,12 +764,12 @@ export type ApiResult<TSuccessResult> =
       statusCode?: number;
     };
 
-export async function wrapZodFetch<T extends z.ZodTypeAny>(
+export async function wrapZodFetch<T extends AnyZodSchema>(
   schema: T,
   url: string,
   requestInit?: RequestInit,
-  options?: ZodFetchOptions<z.output<T>>
-): Promise<ApiResult<z.infer<T>>> {
+  options?: ZodFetchOptions<inferZodSchemaOutput<T>>
+): Promise<ApiResult<inferZodSchemaOutput<T>>> {
   try {
     const response = await zodfetch(schema, url, requestInit, {
       retry: {

packages/core/src/v3/apiClient/index.ts

@@ -1,5 +1,5 @@
 import { nanoid } from "nanoid";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { VERSION } from "../../version.js";
 import { isAdditionalApiKey } from "../apiKeys.js";
 import type { ApiClientConfiguration } from "../apiClientManager-api.js";

packages/core/src/v3/apiClient/stream.ts

@@ -1,4 +1,7 @@
-import type { z } from "zod";
+import type {
+  AnyZodSchema,
+  inferZodSchemaOutput,
+} from "../types/schemas.js";
 import {
   type Offset,
   FetchError,
@@ -22,12 +25,12 @@ export type ZodShapeStreamOptions = {
   onError?: (e: Error) => void;
 };
 
-export type ZodShapeStreamInstance<TShapeSchema extends z.ZodTypeAny> = {
-  stream: AsyncIterableStream<z.output<TShapeSchema>>;
+export type ZodShapeStreamInstance<TShapeSchema extends AnyZodSchema> = {
+  stream: AsyncIterableStream<inferZodSchemaOutput<TShapeSchema>>;
   stop: (delay?: number) => void;
 };
 
-export function zodShapeStream<TShapeSchema extends z.ZodTypeAny>(
+export function zodShapeStream<TShapeSchema extends AnyZodSchema>(
   schema: TShapeSchema,
   url: string,
   options?: ZodShapeStreamOptions
@@ -59,7 +62,7 @@ export function zodShapeStream<TShapeSchema extends z.ZodTypeAny>(
   const readableShape = new ReadableShapeStream(shapeStream);
 
   const stream = readableShape.stream.pipeThrough(
-    new TransformStream<unknown, z.output<TShapeSchema>>({
+    new TransformStream<unknown, inferZodSchemaOutput<TShapeSchema>>({
       async transform(chunk, controller) {
         const result = schema.safeParse(chunk);
 
@@ -73,7 +76,7 @@ export function zodShapeStream<TShapeSchema extends z.ZodTypeAny>(
   );
 
   return {
-    stream: stream as AsyncIterableStream<z.output<TShapeSchema>>,
+    stream: stream as AsyncIterableStream<inferZodSchemaOutput<TShapeSchema>>,
     stop: (delay?: number) => {
       if (delay) {
         setTimeout(() => {