Bug: routes.ts generates undefined module-prefixed enum types instead of OpenAPI schema names

[kyle-ames-dev]

Description

When using StrEnum types in query parameter structs, the generated routes.ts file references type names with Python module path prefixes (e.g., app_domain_insight_schemas__base_Granularity), but these types are not defined anywhere. The actual types in types.gen.ts (generated by hey-api) use simple names from the OpenAPI schema (e.g., Granularity).

This causes TypeScript compilation errors:

src/lib/generated/routes.ts:361:15 - error TS2304: Cannot find name 'app_domain_insight_schemas__base_GroupByField'.
src/lib/generated/routes.ts:409:19 - error TS2304: Cannot find name 'app_domain_insight_schemas__base_Granularity'.
src/lib/generated/routes.ts:467:15 - error TS2304: Cannot find name 'app_domain_insight_schemas__base_SortField'.
src/lib/generated/routes.ts:468:18 - error TS2304: Cannot find name 'app_domain_insight_schemas__base_SortOrder'.

Reproduction Steps

1. ·Define enum types using Python StrEnum:

# app/domain/insight/schemas/_base.py
from enum import StrEnum

class Granularity(StrEnum):
    HOUR = "hour"
    DAY = "day"
    MONTH = "month"

class GroupByField(StrEnum):
    CLIENT_ID = "client_id"
    USER_ID = "user_id"

2. Use these enums in a query parameter struct:

# app/domain/insight/schemas/_query.py
from app.domain.insight.schemas._base import Granularity, GroupByField
from app.lib.schema import CamelizedBaseStruct

class TrendQueryParams(CamelizedBaseStruct):
    granularity: Granularity = Granularity.DAY

class GroupQueryParams(CamelizedBaseStruct):
    group_by: GroupByField

3. Run litestar assets generate-types
4. Check the generated routes.json - it contains module-prefixed type names:

{
  "granularity": "app_domain_insight_schemas__base_Granularity | undefined",
  "group_by": "app_domain_insight_schemas__base_GroupByField"
}

5. The generated routes.ts uses these undefined types, causing TS compilation errors.

Expected Behavior

The generated routes.ts should either:

1. Use simple type names that match the OpenAPI schema (Granularity, GroupByField), OR
2. Define/import the types with the prefixed names, OR
3. Inline the enum values directly (e.g., "hour" | "day" | "month")

Actual Behavior

• openapi.json correctly defines enums with simple names (Granularity, GroupByField)
• types.gen.ts (hey-api) generates types with simple names
• routes.json and routes.ts use Python module path prefixed names that don't exist

Environment

• Python: 3.13.7
• Litestar: 2.19.0
• litestar-vite: 0.18.1
• OS: macOS

Workaround

Manually add type aliases to routes.ts after generation:

// Add after existing type aliases
type app_domain_insight_schemas__base_Granularity = "hour" | "day" | "month";
type app_domain_insight_schemas__base_GroupByField = "client_id" | "user_id";
type app_domain_insight_schemas__base_SortField =
  | "request_timestamp"
  | "total_tokens"
  | "prompt_tokens"
  | "completion_tokens"
  | "created_at";
type app_domain_insight_schemas__base_SortOrder = "asc" | "desc";

Suggested Fix

The issue appears to originate in the route metadata export logic. When serializing type information for query parameters, the code uses Python's fully qualified type name instead of the OpenAPI schema reference name.

Potential fixes:

1. Map Python enum types to their OpenAPI schema names when generating routes.json
2. Generate type aliases in routes.ts for any module-prefixed enum types
3. Inline enum literal types directly in the route type definitions

URL to code causing the issue

No response

MCVE

# Your MCVE code here

Steps to reproduce

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Screenshots

"In the format of: ![SCREENSHOT_DESCRIPTION](SCREENSHOT_LINK.png)"

Logs

Package Version

0.18.1

Platform

• Linux
• Mac
• Windows
• Other (Please specify in the description above)