Typescript Model Flattening Incorrectly

[Oddlaceguy49]

When transforming an interface that includes nested objects (I have flattened it here for convenience, but even this flattened version does not work):

 * @see https://partner.steamgames.com/doc/webapi/ISteamUserAuth#AuthenticateUserTicket
 * @description Response from authenticating a user ticket.
 */
export interface AuthenticateUserTicketResponse {
	response: AuthenticateUserTicketResponse_properties_response;
}

export interface AuthenticateUserTicketResponse_properties_response {
    /**
     * @pattern ^[0-9]{17}$
     * @description The user's 64-bit SteamID if the ticket is valid.
     */
    steamid?: string;
    error?: AuthenticateUserTicketResponse_properties_response_properties_error;
}

export interface AuthenticateUserTicketResponse_properties_response_properties_error {
    /** @description Error code if authentication fails. */
    errorcode: number;
    /**
     * @minLength 1
     * @description Error description if authentication fails.
     */
    errordesc: string;
}

into a model, and then to anything else, in this case zod, typebox-codegen will strip it from the results. The results will only include types that do not contain custom types or objects:

import { z } from 'zod'

export type AuthenticateUserTicketResponse_properties_response_properties_error =
  z.infer<
    typeof AuthenticateUserTicketResponse_properties_response_properties_error
  >
export const AuthenticateUserTicketResponse_properties_response_properties_error =
  z.object({
    errorcode: z.number(),
    errordesc: z.string().min(1)
  })

If you were wondering what the interface looked like before flattening:

/*** The response from the ISteamUserAuth/AuthenticateUserTicket/v1 endpoint.
 * @see https://partner.steamgames.com/doc/webapi/ISteamUserAuth#AuthenticateUserTicket
 * @description Response from authenticating a user ticket.
 */
export interface AuthenticateUserTicketResponse {
	response: {
		/**
		 * @pattern ^[0-9]{17}$
		 * @description The user's 64-bit SteamID if the ticket is valid.
		 */
		steamid?: string;
		error?: {
			/**
			 * @description Error code if authentication fails.
			 */
			errorcode: number;
			/**
			 * @minLength 1
			 * @description Error description if authentication fails.
			 */
			errordesc: string;
		};
	};
}

[sinclairzx81]

@Oddlaceguy49 Hello,

You can fix this by manually ordering definitions in sequence of use (topological ordering). The codegen project will emit structures as linear JavaScript variables; so you need to make sure the variables are defined before use (codegen does not automatically topologically sort the definitions for you).

The other fix was to ensure regular expressions and descriptions are quoted.

Workbench Example

export interface AuthenticateUserTicketResponse_properties_response_properties_error {
    /** 
     * @description "Error code if authentication fails."
     */
    errorcode: number;
    /**
     * @minLength 1
     * @description "Error description if authentication fails."
     */
    errordesc: string;
}

export interface AuthenticateUserTicketResponse_properties_response {
    /**
     * @pattern "^[0-9]{17}$"
     * @description "The user's 64-bit SteamID if the ticket is valid."
     */
    steamid?: string;
    error?: AuthenticateUserTicketResponse_properties_response_properties_error;
}

export interface AuthenticateUserTicketResponse {
    response: AuthenticateUserTicketResponse_properties_response;
}

---

There isn't much I can do to solve automatic topological sorting at this stage (libraries need constructs to handle mutual recursive types) for that to happen. But the JSDoc parsing could use a better implementation. The above should get definitions correctly generating based on the current implementation. For better JSDoc parsing, this project is open to community contribution via PR.

Hope this helps
S

[Oddlaceguy49]

So I must manually (or programmatically) flatten it with ordered interfaces before I parse it?

[sinclairzx81]

@Oddlaceguy49

So I must manually (or programmatically) flatten it with ordered interfaces before I parse it?

Yes. This is a general limitation with runtime types where the order of definition is important. Consider

type C = A | B

type A = number

type B = string

// would naively translate into

const C = Type.Union([A, B]) // error: A and B used before definition

const A = Type.Number()

const B = Type.String()

While some libraries can handle out of order definitions ...

const M = Type.Module({

   C: Type.Union([Type.Ref('A'), Type.Ref('B')]),

   A: Type.Number(),

   B: Type.String()
})

const C = M.Import('C') // ok: can dereference A and B after the fact
const A = M.Import('A')
const B = M.Import('B')

... there isn't a general consensus across libraries how non-order dependent types should work. TypeBox has some capabilities for this (above) as does Zod 4 and ArkType, the problem is they all work differently, which means there is no consistent emit target. It's for this reason that this project pushes back on the type implementation itself, requiring type authors to ensure types are ordered correctly.

This project may introduce basic topological sorting down the road (which is technically feasible), but isn't planned until TypeBox 1.0 (which is aiming to include better facilities for topological sort + mutual recursion detection).

Hope this brings some insight

[Oddlaceguy49]

Well I was able to flatten it with ordered types and pass that into Codegen.TypescriptToModel() and it worked, so would it be possible for Codegen.TypescriptToModel() to flatten all the interfaces before actually converting it to a model?

The code in question:

for (const inputFile of inputFiles) {
		const relativePath = path.relative(inputDir, inputFile);
		const outputFile = path.join(schemaOutputDir, relativePath);
		console.log(`- Processing ${inputFile} -> ${outputFile}`);
		await fs.mkdir(path.dirname(outputFile), { recursive: true });

		const sourceText = await fs.readFile(inputFile, "utf-8");
		let generatedCode: string = "";

		const selectedGenerator = generators[targetPackage.toLowerCase()];
		const transformedSourceText = await transformSourceText(
			sourceText,
			inputFile,
		);

		if (targetPackage.toLowerCase() === "typebox") {
			generatedCode = Codegen.TypeScriptToTypeBox.Generate(
				transformedSourceText,
			);
		} else if (targetPackage.toLowerCase() === "types") {
			// "types" is just the flattened version anyway
			generatedCode = transformedSourceText;
		} else {
			const model = Codegen.TypeScriptToModel.Generate(transformedSourceText);
			generatedCode = selectedGenerator.Generate(model);

			if (targetPackage.toLowerCase() === "yup") {
				console.log("\n🔧 Fixing up generated Yup code...");
				generatedCode = generatedCode.replace(
					"import y from 'yup'",
					"import * as y from 'yup'",
				);
			}

			// Currently broken, will fix later maybe?
			if (targetPackage.toLowerCase() === "arktype") {
				console.log("\n🔧 Fixing up generated ArkType code...");

				// Add // @ts-expect-error above every 'SomeType[]' property value
				generatedCode = generatedCode.replace(
					/^(\s*\w+\s*:\s*)('(?:\w+)'|\w+)\[\](,?)/gm,
					"// @ts-expect-error\n$1'$2[]'$3",
				);
				// Also handle cases like games: 'RecentlyPlayedGame[]'
				generatedCode = generatedCode.replace(
					/^(\s*\w+\s*:\s*)'(\w+\[\])'(,?)/gm,
					"// @ts-expect-error\n$1'$2'$3",
				);
			}
		}

		const combinedOutput = `// THIS FILE IS AUTO-GENERATED FOR ${targetPackage.toUpperCase()}. DO NOT EDIT.\n\n${generatedCode}`;
		await fs.writeFile(outputFile, combinedOutput);
	}

Transform Source Text:

async function transformSourceText(
	sourceText: string,
	inputFile: string,
): Promise<string> {
	const project = new Project();

	const sourceFile = project.createSourceFile(
		inputFile, // Provide a path for context
		sourceText, // Provide the file content
		{ overwrite: true }, // Good practice
	);

	const interfacesToProcess: InterfaceDeclaration[] =
		sourceFile.getInterfaces();

	while (interfacesToProcess.length > 0) {
		const currentInterface = interfacesToProcess.shift();

		if (!currentInterface) continue;

		const parentInterfaceName = currentInterface.getName();

		for (const prop of currentInterface.getProperties()) {
			const propName = prop.getName();
			const typeNode = prop.getTypeNode();

			if (typeNode && Node.isTypeLiteral(typeNode)) {
				const newInterfaceName = `${parentInterfaceName}_properties_${propName}`;

				const newInterface = sourceFile.insertInterface(
					currentInterface.getChildIndex(),
					{
						name: newInterfaceName,
						isExported: true,
						properties: typeNode
							.getMembers()
							.filter(Node.isPropertySignature)
							.map((member) => member.getStructure()),
					},
				);

				interfacesToProcess.push(newInterface);

				prop.setType(newInterfaceName);
			}
		}
	}

	return sourceFile.getFullText();
}