feat: support zod infer type and complex generic types for decorators and responses

[mathfalcon]

All Submissions:

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you written unit tests?
• Have you written unit tests that cover the negative cases (i.e.: if bad data is submitted, does the library respond properly)?
• This PR is associated with an existing issue?

Closing issues

This closesissue #1256 which specifically mentions Zod's z.infer type support.

If this is a new feature submission:

• Has the issue had a maintainer respond to the issue and clarify that the feature is something that aligns with the goals and philosophy of the project?

Test plan

WIP

---

Problem

TSOA fails to process complex types like Zod's z.infer types and other generic type references, causing errors during route generation. This affects:

1. Return types: TypeError: Cannot read properties of undefined (reading 'kind') when processing generic return types
2. Query parameters: @Queries() only support 'refObject' or 'nestedObjectLiteral' types when using Zod inferred types

Related Issue: This addresses issue #1256 which specifically mentions Zod's z.infer type support.

Root Cause

The TypeResolver class was not properly handling cases where:

• Built-in types (like Date) don't have declarations in user code
• Inline object types in generic type arguments don't have named declarations
• Complex type references (like z.infer<typeof Schema>) aren't resolved to their underlying object structure

Solution

I implemented a two-part fix:

1. Enhanced TypeResolver (typeResolver.ts)

• Fixed getModelTypeDeclarations: Added graceful handling for built-in types that don't have user code declarations
• Improved calcRefTypeName: Added proper handling for inline object types in generic type arguments
• Enhanced typeArgumentsToContext: Added error handling for cases where type declarations are empty

2. Enhanced ParameterGenerator (parameterGenerator.ts)

• Improved getQueriesParameters: Added fallback resolution for complex types that don't initially resolve to refObject or nestedObjectLiteral
• Added type resolution retry: When initial resolution fails, attempts deeper type resolution for TypeReferenceNode types
• Maintained validation: Still enforces the same type requirements, just with better resolution

Testing

• ✅ All existing functionality continues to work
• ✅ Zod z.infer types now work with @Queries() decorator
• ✅ Generic return types (like PaginatedResponse<T>) now work
• ✅ Built-in types like Date are handled gracefully
• ✅ Backward compatibility maintained
• WIP: will create unit/integration tests for these changes

Use Case Context

This fix was developed to support a specific but common use case:

My Setup: Kysely (auto-generates TypeScript types from DB queries) → Repository methods (strongly typed) → Services → Controllers → TSOA → OpenAPI spec → Frontend TypeScript types

The Problem: Kysely generates complex generic types that TSOA couldn't process (same issue as zod), breaking the type safety chain from database to frontend.

The Solution: This fix enables TSOA to properly resolve complex types, completing the full-stack type safety circle.

Important Notes

• AI-Assisted Development: This fix was primarily developed using AI assistance. Please review carefully and request changes if needed.
• Conservative Approach: The fix maintains all existing validation and only enhances type resolution where it was failing
• Graceful Fallback: If enhanced resolution fails, the system falls back to original behavior with helpful logging
• Limited Scope: Only affects TypeReferenceNode types that weren't resolving properly

Potential Side Effects

• Positive: May help other type libraries that use similar patterns to Zod
• Neutral: All existing valid use cases continue to work exactly as before
• Monitoring: Added logging to help debug any resolution failures (I didn't found any specific logging mechanism in the repo so let me know what's the right approach here)

Files Changed

• packages/cli/src/metadataGeneration/typeResolver.ts
• packages/cli/src/metadataGeneration/parameterGenerator.ts

Impact

This fix enables TSOA to work seamlessly with modern TypeScript patterns and popular libraries like Zod, making it more robust for real-world applications that rely on complex type systems.

---

Note: Even if this PR isn't approved, the fix works for my specific use case and maintains backward compatibility, so it can be applied locally if needed.

Screenshots

Notice how PaginationQuery is a zod infered type, and the return type of the service is a Kysely autogenerated type.

🎉 The swagger docs work properly

[github-actions]

Hello there mathfalcon 👋

Thank you and congrats 🎉 for opening your first PR on this project.✨

We will review the following PR soon! 👀

[SpinBoxx]

Hello
How can we test this ?

[WoH]

I'd love to see this in a test as well. So we can't accidentally break this in the future

[mathfalcon]

hey all, just came back from vacation, will work on tests as soon as I can

[lobabob]

@mathfalcon Were you able to get those tests working? This PR looks awesome, would love for it to go in soon.

[mathfalcon]

@SpinBoxx @WoH @lobabob Sorry for the delay. I had an unexpected trip, but the tests are finally done. I tried to follow the same pattern as the other test files, but let me know if my approach is incorrect. I also had to modify the files related to type generation due to other edge cases that I found while writing the tests. FYI I have one failing test when running tests locally but does not seem related to my code changes, it happens on this file express-server-custom-multer.spec.ts:39:20.

What This Commit Fixes

• Fixed TypeError: Resolved Cannot read properties of undefined (reading 'refName') error in MetadataGenerator.AddReferenceType
• Improved Error Handling: Added proper validation for empty reference type arrays in ReferenceTransformer.merge()
• Enhanced Type Resolution: Better error messages when types cannot be resolved

Test Files Overview

tests/fixtures/controllers/complexTypeController.ts

Purpose: Test controller with various complex TypeScript types to validate TSOA's type resolution capabilities.

Test Scenarios:

• Zod z.infer types: UserSchema, ProductSchema, OrderSchema with @Body decorators
• Generic types: GenericWrapper<T> with primitive and interface types
• Pagination queries: PaginationQuery with @Queries decorator (proper use case)
• Discriminated unions: UserEvent with multiple event types (user_created, user_updated, user_deleted)
• Simple query parameters: Primitive types with @Query decorators
• Union/Enum types: Status, Priority types for query parameters

tests/integration/complex-type-resolution.spec.ts

Purpose: Integration tests ensuring OpenAPI spec generation works correctly for complex types.

Test Coverage:

• Schema validation: Verifies proper OpenAPI 3 schema generation
• Parameter validation: Ensures query parameters are correctly mapped
• Request body validation: Validates complex body schemas with proper references
• Discriminated union handling: Tests oneOf schemas with discriminator properties
• Error handling: Confirms no crashes during metadata generation

Key Improvements

1. Proper API Design: Uses @Queries for simple query parameters, @Body for complex types
2. Real-world Examples: Pagination, event handling, and discriminated unions
3. Comprehensive Coverage: 16 passing tests covering edge cases and common patterns
4. Zod Integration: Demonstrates TSOA working with Zod schemas including transforms and validation
5. Dependencies: Added Zod as dev dependency for testing complex type resolution scenarios

This ensures TSOA can handle complex TypeScript types while maintaining proper OpenAPI specification generation. I didn't touch any of the existing tests.

[WoH]

It smells a bit brittle, but seems worth a shot.

[pclements12]

@WoH can we get this into a release ASAP? This is a heavily requested feature that a lot of people would find benefit from

[WoH]

no

[mathfalcon]

@WoH Thanks for getting this in. Is there anything else I can do to speed up the release process, or can you consider publishing a release candidate so that I can stop using my local link to this package? It would be really useful.

[WoH]

We need to drop node 18, that only makes sense in a major version. For that, I want to tackle the OpenAPI 3.1 support and possibly koa 3 / express 5, although these 2 could be a minor version later, too. So review the PR I guess 😅

It won't be take a week, but not today.

[laurilarjo]

just pitching in to say great work @mathfalcon for bringing this in! We'll also greatly benefit from this and can remove our own workaround of type generations at build-time.

We can wait a week, no problem. Just glad to hear its coming along.