feat(typescript): refactor serialization pipeline

generators/typescript-v2/ast/src/custom-config/TypescriptCustomConfigSchema.ts

@@ -51,6 +51,7 @@ export const TypescriptCustomConfigSchema = z.strictObject({
     inlinePathParameters: z.optional(z.boolean()),
     namespaceExport: z.optional(z.string()),
     noSerdeLayer: z.optional(z.boolean()),
+    serializationFormat: z.optional(z.enum(["zurg", "zod", "none"])),
     private: z.optional(z.boolean()),
     requireDefaultEnvironment: z.optional(z.boolean()),
     retainOriginalCasing: z.optional(z.boolean()),

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:
+ * - "zurg": 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(["zurg", "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

@@ -11,6 +11,7 @@ import {
     ImportsManager,
     NpmPackage,
     PackageId,
+    SerializationFormatType,
     SimpleTypescriptProject,
     TypescriptProject
 } from "@fern-typescript/commons";
@@ -59,6 +60,7 @@ export declare namespace ExpressGenerator {
         includeOtherInUnionTypes: boolean;
         treatUnknownAsAny: boolean;
         includeSerdeLayer: boolean;
+        serializationFormat: SerializationFormatType;
         outputEsm: boolean;
         retainOriginalCasing: boolean;
         allowExtraFields: boolean;
@@ -134,7 +136,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,
@@ -525,7 +528,7 @@ export class ExpressGenerator {
         this.context.logger.debug(`Generating ${filepathStr}`);
 
         const sourceFile = this.rootDirectory.createSourceFile(filepathStr);
-        const importsManager = new ImportsManager({ packagePath: this.config.packagePath });
+        const importsManager = new ImportsManager({ packagePath: this.getRelativePackagePath() });
 
         run({ sourceFile, importsManager });
 

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

@@ -9,6 +9,7 @@ import {
     fixImportsForEsm,
     NpmPackage,
     PersistedTypescriptProject,
+    SerializationPipeline,
     writeTemplateFiles
 } from "@fern-typescript/commons";
 import { GeneratorContext } from "@fern-typescript/contexts";
@@ -35,7 +36,15 @@ 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
+        const serializationFormat = SerializationPipeline.resolveFormatType({
+            serializationFormat: parsed?.serializationFormat,
+            noSerdeLayer: parsed?.noSerdeLayer ?? true
+        });
+        const noSerdeLayer = serializationFormat === "none";
+
         const config = {
             useBrandedStringAliases: parsed?.useBrandedStringAliases ?? false,
             outputSourceFiles: parsed?.outputSourceFiles ?? true,
@@ -58,6 +67,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 +217,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

@@ -27,6 +27,7 @@ import {
     NpmPackage,
     PackageId,
     PublicExportsManager,
+    SerializationFormatType,
     SimpleTypescriptProject,
     TypescriptProject
 } from "@fern-typescript/commons";
@@ -124,6 +125,7 @@ export declare namespace SdkGenerator {
         treatUnknownAsAny: boolean;
         includeContentHeadersOnFileDownloadResponse: boolean;
         includeSerdeLayer: boolean;
+        serializationFormat: SerializationFormatType;
         noOptionalProperties: boolean;
         tolerateRepublish: boolean;
         retainOriginalCasing: boolean;
@@ -289,7 +291,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/abstract-schema-generator/src/AbstractGeneratedSchema.ts

@@ -18,23 +18,136 @@ export abstract class AbstractGeneratedSchema<Context extends BaseContext> {
     }
 
     public writeSchemaToFile(context: Context): void {
-        context.sourceFile.addVariableStatement({
-            isExported: true,
-            declarationKind: VariableDeclarationKind.Const,
-            declarations: [
-                {
-                    name: this.typeName,
-                    type: getTextOfTsNode(
-                        this.getReferenceToSchemaType({
-                            context,
-                            rawShape: this.getReferenceToRawShape(context),
-                            parsedShape: this.getReferenceToParsedShape(context)
-                        })
+        const schema = this.buildSchema(context);
+        const schemaExpression = schema.toExpression();
+        const toJsonExpression = schema.toJsonExpression;
+
+        // For Zod format, always generate a wrapper object with parse and json methods
+        // This is needed because Zod schemas don't have built-in bidirectional serialization
+        if (context.coreUtilities.zurg.name === "zod") {
+            // Generate:
+            //   const _<typeName>_Schema = <zodSchema>;
+            //   export const <typeName> = { _schema: _<typeName>_Schema, parse: ..., json: ... };
+            const internalSchemaName = `_${this.typeName}_Schema`;
+            const parsedParam = ts.factory.createIdentifier("parsed");
+            const rawParam = ts.factory.createIdentifier("raw");
+            const schemaRef = ts.factory.createIdentifier(internalSchemaName);
+
+            // First, add the internal schema variable
+            context.sourceFile.addVariableStatement({
+                isExported: false,
+                declarationKind: VariableDeclarationKind.Const,
+                declarations: [
+                    {
+                        name: internalSchemaName,
+                        initializer: getTextOfTsNode(schemaExpression)
+                    }
+                ]
+            });
+
+            // If no toJsonExpression, use identity function: (parsed) => parsed
+            const jsonBody = toJsonExpression ? toJsonExpression(parsedParam) : parsedParam;
+
+            // Get the type nodes for parameter annotations
+            const parsedTypeNode = this.getReferenceToParsedShape(context);
+
+            // Get the raw type node for json return type cast
+            const rawTypeNode = this.getReferenceToRawShape(context);
+
+            const wrapperObject = ts.factory.createObjectLiteralExpression(
+                [
+                    ts.factory.createPropertyAssignment("_schema", schemaRef),
+                    ts.factory.createPropertyAssignment(
+                        "parse",
+                        ts.factory.createArrowFunction(
+                            undefined,
+                            undefined,
+                            [
+                                ts.factory.createParameterDeclaration(
+                                    undefined,
+                                    undefined,
+                                    undefined,
+                                    rawParam,
+                                    undefined,
+                                    ts.factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword)
+                                )
+                            ],
+                            undefined,
+                            ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                            // Cast the parse result to the expected Parsed type to fix Zod's loose inference
+                            ts.factory.createAsExpression(
+                                ts.factory.createCallExpression(
+                                    ts.factory.createPropertyAccessExpression(schemaRef, "parse"),
+                                    undefined,
+                                    [rawParam]
+                                ),
+                                parsedTypeNode
+                            )
+                        )
                     ),
-                    initializer: getTextOfTsNode(this.buildSchema(context).toExpression())
-                }
-            ]
-        });
+                    ts.factory.createPropertyAssignment(
+                        "json",
+                        ts.factory.createArrowFunction(
+                            undefined,
+                            undefined,
+                            [
+                                ts.factory.createParameterDeclaration(
+                                    undefined,
+                                    undefined,
+                                    undefined,
+                                    parsedParam,
+                                    undefined,
+                                    parsedTypeNode
+                                )
+                            ],
+                            undefined,
+                            ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                            // Cast the json result to the expected Raw type
+                            ts.factory.createAsExpression(jsonBody, rawTypeNode)
+                        )
+                    )
+                ],
+                true
+            );
+
+            // Then add the exported wrapper
+            context.sourceFile.addVariableStatement({
+                isExported: true,
+                declarationKind: VariableDeclarationKind.Const,
+                declarations: [
+                    {
+                        name: this.typeName,
+                        type: getTextOfTsNode(
+                            this.getReferenceToSchemaType({
+                                context,
+                                rawShape: this.getReferenceToRawShape(context),
+                                parsedShape: this.getReferenceToParsedShape(context)
+                            })
+                        ),
+                        initializer: getTextOfTsNode(wrapperObject)
+                    }
+                ]
+            });
+        } else {
+            // Original behavior for Zurg format
+            context.sourceFile.addVariableStatement({
+                isExported: true,
+                declarationKind: VariableDeclarationKind.Const,
+                declarations: [
+                    {
+                        name: this.typeName,
+                        type: getTextOfTsNode(
+                            this.getReferenceToSchemaType({
+                                context,
+                                rawShape: this.getReferenceToRawShape(context),
+                                parsedShape: this.getReferenceToParsedShape(context)
+                            })
+                        ),
+                        initializer: getTextOfTsNode(schemaExpression)
+                    }
+                ]
+            });
+        }
 
         this.generateModule(context);
     }