feat(typescript): refactor serialization pipeline

generators/typescript/express/cli/src/ExpressGeneratorCli.ts

@@ -2,7 +2,7 @@ import { Logger } from "@fern-api/logger";
 import { FernGeneratorExec } from "@fern-fern/generator-exec-sdk";
 import { IntermediateRepresentation } from "@fern-fern/ir-sdk/api";
 import { AbstractGeneratorCli } from "@fern-typescript/abstract-generator-cli";
-import { NpmPackage, PersistedTypescriptProject } from "@fern-typescript/commons";
+import { NpmPackage, PersistedTypescriptProject, SerializationPipeline } from "@fern-typescript/commons";
 import { GeneratorContext } from "@fern-typescript/contexts";
 import { ExpressGenerator } from "@fern-typescript/express-generator";
 import { camelCase, upperFirst } from "lodash-es";
@@ -12,7 +12,14 @@ import { ExpressCustomConfigSchema } from "./custom-config/schema/ExpressCustomC
 export class ExpressGeneratorCli extends AbstractGeneratorCli<ExpressCustomConfig> {
     protected parseCustomConfig(customConfig: unknown, logger: Logger): ExpressCustomConfig {
         const parsed = customConfig != null ? ExpressCustomConfigSchema.parse(customConfig) : undefined;
-        const noSerdeLayer = parsed?.noSerdeLayer ?? false;
+
+        // Resolve serialization format from new option or legacy noSerdeLayer
+        const serializationFormat = SerializationPipeline.resolveFormatType({
+            serializationFormat: parsed?.serializationFormat,
+            noSerdeLayer: parsed?.noSerdeLayer
+        });
+        const noSerdeLayer = serializationFormat === "none";
+
         const enableInlineTypes = false; // hardcode, not supported in Express
         const config = {
             useBrandedStringAliases: parsed?.useBrandedStringAliases ?? false,
@@ -22,6 +29,7 @@ export class ExpressGeneratorCli extends AbstractGeneratorCli<ExpressCustomConfi
             includeOtherInUnionTypes: parsed?.includeOtherInUnionTypes ?? false,
             treatUnknownAsAny: parsed?.treatUnknownAsAny ?? false,
             noSerdeLayer,
+            serializationFormat,
             requestValidationStatusCode: parsed?.requestValidationStatusCode ?? 422,
             outputEsm: parsed?.outputEsm ?? false,
             outputSourceFiles: parsed?.outputSourceFiles ?? true,
@@ -76,6 +84,7 @@ export class ExpressGeneratorCli extends AbstractGeneratorCli<ExpressCustomConfi
                 includeOtherInUnionTypes: customConfig.includeOtherInUnionTypes,
                 treatUnknownAsAny: customConfig.treatUnknownAsAny,
                 includeSerdeLayer: !customConfig.noSerdeLayer,
+                serializationFormat: customConfig.serializationFormat,
                 outputEsm: customConfig.outputEsm,
                 retainOriginalCasing: customConfig.retainOriginalCasing,
                 allowExtraFields: customConfig.allowExtraFields,

generators/typescript/express/cli/src/custom-config/ExpressCustomConfig.ts

@@ -1,3 +1,5 @@
+import { SerializationFormatType } from "@fern-typescript/commons";
+
 // this is the parsed config shape. to view the allowed options for generators.yml,
 // see ExpressCustomConfigSchema.ts
 export interface ExpressCustomConfig {
@@ -8,6 +10,7 @@ export interface ExpressCustomConfig {
     includeOtherInUnionTypes: boolean;
     treatUnknownAsAny: boolean;
     noSerdeLayer: boolean;
+    serializationFormat: SerializationFormatType;
     skipRequestValidation: boolean;
     skipResponseValidation: boolean;
     requestValidationStatusCode: number;

generators/typescript/express/cli/src/custom-config/schema/ExpressCustomConfigSchema.ts

@@ -1,11 +1,20 @@
 import { z } from "zod";
 
+/**
+ * Serialization format options:
+ * - "default": Use Zurg (bundled runtime) - same as legacy behavior
+ * - "zod": Use Zod as npm dependency
+ * - "none": No serialization layer - same as noSerdeLayer: true
+ */
+const SerializationFormatSchema = z.enum(["default", "zod", "none"]);
+
 export const ExpressCustomConfigSchema = z.strictObject({
     useBrandedStringAliases: z.optional(z.boolean()),
     optionalImplementations: z.optional(z.boolean()),
     doNotHandleUnrecognizedErrors: z.optional(z.boolean()),
     treatUnknownAsAny: z.optional(z.boolean()),
     noSerdeLayer: z.optional(z.boolean()),
+    serializationFormat: z.optional(SerializationFormatSchema),
     skipRequestValidation: z.optional(z.boolean()),
     skipResponseValidation: z.optional(z.boolean()),
     outputEsm: z.optional(z.boolean()),

generators/typescript/express/generator/src/ExpressGenerator.ts

@@ -59,6 +59,7 @@ export declare namespace ExpressGenerator {
         includeOtherInUnionTypes: boolean;
         treatUnknownAsAny: boolean;
         includeSerdeLayer: boolean;
+        serializationFormat: "default" | "zod" | "none";
         outputEsm: boolean;
         retainOriginalCasing: boolean;
         allowExtraFields: boolean;
@@ -134,7 +135,8 @@ export class ExpressGenerator {
             fetchSupport: "node-fetch",
             relativePackagePath: this.getRelativePackagePath(),
             relativeTestPath: this.getRelativeTestPath(),
-            generateEndpointMetadata: false
+            generateEndpointMetadata: false,
+            serializationFormat: config.serializationFormat
         });
         this.asIsManager = new AsIsManager({
             useBigInt: config.useBigInt,

generators/typescript/sdk/cli/src/SdkGeneratorCli.ts

@@ -9,6 +9,8 @@ import {
     fixImportsForEsm,
     NpmPackage,
     PersistedTypescriptProject,
+    SerializationFormatType,
+    SerializationPipeline,
     writeTemplateFiles
 } from "@fern-typescript/commons";
 import { GeneratorContext } from "@fern-typescript/contexts";
@@ -35,7 +37,19 @@ export class SdkGeneratorCli extends AbstractGeneratorCli<SdkCustomConfig> {
 
     protected parseCustomConfig(customConfig: unknown, logger: Logger): SdkCustomConfig {
         const parsed = customConfig != null ? SdkCustomConfigSchema.parse(customConfig) : undefined;
-        const noSerdeLayer = parsed?.noSerdeLayer ?? true;
+
+        // Resolve serialization format from new option or legacy noSerdeLayer
+        // Note: SDK defaults to noSerdeLayer: true (no serialization) for backward compatibility
+        // TODO: Add serializationFormat to TypescriptCustomConfigSchema in @fern-api/typescript-ast
+        const parsedWithFormat = parsed as
+            | (typeof parsed & { serializationFormat?: SerializationFormatType })
+            | undefined;
+        const serializationFormat = SerializationPipeline.resolveFormatType({
+            serializationFormat: parsedWithFormat?.serializationFormat,
+            noSerdeLayer: parsed?.noSerdeLayer ?? true
+        });
+        const noSerdeLayer = serializationFormat === "none";
+
         const config = {
             useBrandedStringAliases: parsed?.useBrandedStringAliases ?? false,
             outputSourceFiles: parsed?.outputSourceFiles ?? true,
@@ -58,6 +72,7 @@ export class SdkGeneratorCli extends AbstractGeneratorCli<SdkCustomConfig> {
             treatUnknownAsAny: parsed?.treatUnknownAsAny ?? false,
             includeContentHeadersOnFileDownloadResponse: parsed?.includeContentHeadersOnFileDownloadResponse ?? false,
             noSerdeLayer,
+            serializationFormat,
             extraPeerDependencies: parsed?.extraPeerDependencies ?? {},
             extraPeerDependenciesMeta: parsed?.extraPeerDependenciesMeta ?? {},
             noOptionalProperties: parsed?.noOptionalProperties ?? false,
@@ -207,6 +222,7 @@ export class SdkGeneratorCli extends AbstractGeneratorCli<SdkCustomConfig> {
                 treatUnknownAsAny: customConfig.treatUnknownAsAny,
                 includeContentHeadersOnFileDownloadResponse: customConfig.includeContentHeadersOnFileDownloadResponse,
                 includeSerdeLayer: !customConfig.noSerdeLayer,
+                serializationFormat: customConfig.serializationFormat,
                 retainOriginalCasing: customConfig.retainOriginalCasing ?? false,
                 parameterNaming: customConfig.parameterNaming ?? "default",
                 noOptionalProperties: customConfig.noOptionalProperties,

generators/typescript/sdk/cli/src/custom-config/SdkCustomConfig.ts

@@ -1,3 +1,5 @@
+import { SerializationFormatType } from "@fern-typescript/commons";
+
 // this is the parsed config shape. to view the allowed options for generators.yml,
 // see SdkCustomConfigSchema.ts
 export interface SdkCustomConfig {
@@ -24,6 +26,7 @@ export interface SdkCustomConfig {
     treatUnknownAsAny: boolean;
     includeContentHeadersOnFileDownloadResponse: boolean;
     noSerdeLayer: boolean;
+    serializationFormat: SerializationFormatType;
     noOptionalProperties: boolean;
     includeApiReference: boolean | undefined;
     tolerateRepublish: boolean;

generators/typescript/sdk/generator/src/SdkGenerator.ts

@@ -124,6 +124,7 @@ export declare namespace SdkGenerator {
         treatUnknownAsAny: boolean;
         includeContentHeadersOnFileDownloadResponse: boolean;
         includeSerdeLayer: boolean;
+        serializationFormat: "default" | "zod" | "none";
         noOptionalProperties: boolean;
         tolerateRepublish: boolean;
         retainOriginalCasing: boolean;
@@ -289,7 +290,8 @@ export class SdkGenerator {
             fetchSupport: this.config.fetchSupport,
             relativePackagePath: this.relativePackagePath,
             relativeTestPath: this.relativeTestPath,
-            generateEndpointMetadata: this.config.generateEndpointMetadata
+            generateEndpointMetadata: this.config.generateEndpointMetadata,
+            serializationFormat: this.config.serializationFormat
         });
 
         const apiDirectory: ExportedDirectory[] = [

generators/typescript/utils/commons/src/core-utilities/CoreUtilitiesManager.ts

@@ -8,6 +8,14 @@ import { DependencyManager } from "../dependency-manager/DependencyManager";
 import { ExportsManager } from "../exports-manager";
 import { ImportsManager } from "../imports-manager";
 import { getReferenceToExportViaNamespaceImport } from "../referencing";
+import {
+    NoneFormat,
+    SerializationFormatType,
+    SerializationPipeline,
+    ZodFormat,
+    ZURG_MANIFEST,
+    ZurgFormat
+} from "../serialization-pipeline";
 import { AuthImpl } from "./Auth";
 import { CallbackQueueImpl } from "./CallbackQueue";
 import { CoreUtilities } from "./CoreUtilities";
@@ -22,7 +30,6 @@ import { StreamImpl } from "./Stream";
 import { UrlUtilsImpl } from "./UrlUtils";
 import { UtilsImpl } from "./Utils";
 import { WebsocketImpl } from "./Websocket";
-import { ZurgImpl } from "./Zurg";
 
 export declare namespace CoreUtilitiesManager {
     namespace getCoreUtilities {
@@ -51,28 +58,32 @@ export class CoreUtilitiesManager {
     private readonly relativePackagePath: string;
     private readonly relativeTestPath: string;
     private readonly generateEndpointMetadata: boolean;
+    private readonly serializationFormat: SerializationFormatType;
 
     constructor({
         streamType,
         formDataSupport,
         fetchSupport,
         relativePackagePath = DEFAULT_PACKAGE_PATH,
         relativeTestPath = DEFAULT_TEST_PATH,
-        generateEndpointMetadata
+        generateEndpointMetadata,
+        serializationFormat = "default"
     }: {
         streamType: "wrapper" | "web";
         formDataSupport: "Node16" | "Node18";
         fetchSupport: "node-fetch" | "native";
         relativePackagePath?: string;
         relativeTestPath?: string;
         generateEndpointMetadata: boolean;
+        serializationFormat?: SerializationFormatType;
     }) {
         this.streamType = streamType;
         this.formDataSupport = formDataSupport;
         this.fetchSupport = fetchSupport;
         this.relativePackagePath = relativePackagePath;
         this.relativeTestPath = relativeTestPath;
         this.generateEndpointMetadata = generateEndpointMetadata;
+        this.serializationFormat = serializationFormat;
     }
 
     public getCoreUtilities({
@@ -90,8 +101,11 @@ export class CoreUtilitiesManager {
             relativeTestPath
         });
 
+        // Create the serialization format based on configuration
+        const serializationFormat = this.createSerializationFormat(getReferenceToExport);
+
         return {
-            zurg: new ZurgImpl({ getReferenceToExport, generateEndpointMetadata: this.generateEndpointMetadata }),
+            zurg: serializationFormat,
             fetcher: new FetcherImpl({ getReferenceToExport, generateEndpointMetadata: this.generateEndpointMetadata }),
             stream: new StreamImpl({ getReferenceToExport, generateEndpointMetadata: this.generateEndpointMetadata }),
             auth: new AuthImpl({ getReferenceToExport, generateEndpointMetadata: this.generateEndpointMetadata }),
@@ -128,6 +142,34 @@ export class CoreUtilitiesManager {
         };
     }
 
+    private createSerializationFormat(
+        getReferenceToExport: (args: {
+            manifest: CoreUtility.Manifest;
+            exportedName: string;
+        }) => ReturnType<typeof getReferenceToExportViaNamespaceImport>
+    ) {
+        const config = {
+            getReferenceToExport,
+            generateEndpointMetadata: this.generateEndpointMetadata
+        };
+
+        switch (this.serializationFormat) {
+            case "default":
+                // Add Zurg manifest to referenced utilities so it gets copied
+                this.addManifestAndDependencies(ZURG_MANIFEST);
+                return new ZurgFormat(config);
+
+            case "zod":
+                return new ZodFormat(config);
+
+            case "none":
+                return new NoneFormat(config);
+
+            default:
+                throw new Error(`Unknown serialization format: ${this.serializationFormat}`);
+        }
+    }
+
     public finalize(exportsManager: ExportsManager, dependencyManager: DependencyManager): void {
         for (const utility of Object.values(this.referencedCoreUtilities)) {
             exportsManager.addExportsForDirectories(
@@ -145,6 +187,20 @@ export class CoreUtilitiesManager {
                 fetchSupport: this.fetchSupport
             });
         }
+
+        // Add runtime dependencies for serialization format
+        this.addSerializationDependencies(dependencyManager);
+    }
+
+    /**
+     * Add npm dependencies required by the active serialization format
+     */
+    private addSerializationDependencies(dependencyManager: DependencyManager): void {
+        if (this.serializationFormat === "zod") {
+            // Zod uses an npm dependency instead of bundled runtime files
+            dependencyManager.addDependency("zod", "^3.23.0");
+        }
+        // Zurg and None formats don't require external npm dependencies
     }
 
     public async copyCoreUtilities({