feat(type-aliases): add support for generic type aliases (#15)

The changes in this commit add support for parsing and generating code for generic type aliases in the validation schema codegen tool.

The main changes are:

1. Modify the `index.ts` file to check if any interfaces or type aliases have generic type parameters.
2. Implement the `parseGenericTypeAlias` method in the `TypeAliasParser` class to handle the parsing and code generation for generic type aliases.
3. Add a new method `createGenericTypeAliasFunction` to generate the TypeBox function definition for the generic type alias.
4. Implement the `addGenericTypeAlias` method to add the generic type alias declaration to the output file.

These changes allow the validation schema codegen tool to properly handle and generate code for generic type aliases, which is an important feature for users who need to define complex schema types.

Author: DaxServer

ARCHITECTURE.md

@@ -24,9 +24,9 @@
 ### Supported TypeScript Constructs
 
 - **Type Definitions**: Type aliases, interfaces, enums, and function declarations
-- **Generic Types**: Generic interfaces and type parameters with proper constraint handling
+- **Generic Types**: Generic interfaces and type aliases with type parameters and proper constraint handling
 - **Complex Types**: Union and intersection types, nested object structures, template literal types
-- **Utility Types**: Built-in support for Pick, Omit, Partial, Required, Record, and other TypeScript utility types
+- **Utility Types**: Built-in support for Pick, Omit, Partial, Required, Record, Readonly, and other TypeScript utility types
 - **Advanced Features**: Conditional types, mapped types, keyof operators, indexed access types
 - **Import Resolution**: Cross-file type dependencies with qualified naming and circular dependency handling
 
@@ -39,7 +39,7 @@ The main logic for code generation resides in the <mcfile name="index.ts" path="
 The `generateCode` function in <mcfile name="index.ts" path="src/index.ts"></mcfile> orchestrates the entire code generation process:
 
 1.  **Input Processing**: Creates a `SourceFile` from input using `createSourceFileFromInput`
-2.  **Generic Interface Detection**: Checks for generic interfaces to determine required TypeBox imports
+2.  **Generic Type Detection**: Checks for generic interfaces and type aliases to determine required TypeBox imports (including `TSchema`)
 3.  **Output File Creation**: Creates a new output file with necessary `@sinclair/typebox` imports using `createOutputFile`
 4.  **Dependency Traversal**: Uses `DependencyTraversal` to analyze and sort all type dependencies
 5.  **Code Generation**: Processes sorted nodes using `TypeBoxPrinter` in `printSortedNodes`
@@ -113,8 +113,8 @@ The <mcfile name="base-parser.ts" path="src/parsers/base-parser.ts"></mcfile> pr
 
 #### Specialized Parsers
 
-1. **InterfaceParser**: <mcfile name="parse-interfaces.ts" path="src/parsers/parse-interfaces.ts"></mcfile> - Handles both regular and generic interfaces
-2. **TypeAliasParser**: <mcfile name="parse-type-aliases.ts" path="src/parsers/parse-type-aliases.ts"></mcfile> - Processes type alias declarations
+1. **InterfaceParser**: <mcfile name="parse-interfaces.ts" path="src/parsers/parse-interfaces.ts"></mcfile> - Handles both regular and generic interfaces using the unified `GenericTypeUtils` flow for consistency with type aliases
+2. **TypeAliasParser**: <mcfile name="parse-type-aliases.ts" path="src/parsers/parse-type-aliases.ts"></mcfile> - Processes both regular and generic type alias declarations using `GenericTypeUtils.createGenericArrowFunction`
 3. **EnumParser**: <mcfile name="parse-enums.ts" path="src/parsers/parse-enums.ts"></mcfile> - Handles enum declarations
 4. **FunctionParser**: <mcfile name="parse-function-declarations.ts" path="src/parsers/parse-function-declarations.ts"></mcfile> - Processes function declarations
 5. **ImportParser**: <mcfile name="parse-imports.ts" path="src/parsers/parse-imports.ts"></mcfile> - Handles import resolution
@@ -127,20 +127,42 @@ The handler system in <mcfile name="handlers/typebox" path="src/handlers/typebox
 
 1. **Base Handlers**: Foundation classes including <mcfile name="base-type-handler.ts" path="src/handlers/typebox/base-type-handler.ts"></mcfile> and specialized base classes
 2. **Collection Handlers**: <mcfile name="array-type-handler.ts" path="src/handlers/typebox/collection/array-type-handler.ts"></mcfile>, <mcfile name="intersection-type-handler.ts" path="src/handlers/typebox/collection/intersection-type-handler.ts"></mcfile>, <mcfile name="tuple-type-handler.ts" path="src/handlers/typebox/collection/tuple-type-handler.ts"></mcfile>, <mcfile name="union-type-handler.ts" path="src/handlers/typebox/collection/union-type-handler.ts"></mcfile>
-3. **Object Handlers**: <mcfile name="interface-type-handler.ts" path="src/handlers/typebox/object/interface-type-handler.ts"></mcfile>, <mcfile name="object-type-handler.ts" path="src/handlers/typebox/object/object-type-handler.ts"></mcfile>
+3. **Object Handlers**: <mcfile name="interface-type-handler.ts" path="src/handlers/typebox/object/interface-type-handler.ts"></mcfile> (returns raw TypeBox expressions for generic interfaces, allowing parser-level arrow function wrapping), <mcfile name="object-type-handler.ts" path="src/handlers/typebox/object/object-type-handler.ts"></mcfile>
 4. **Reference Handlers**: <mcfile name="omit-type-handler.ts" path="src/handlers/typebox/reference/omit-type-handler.ts"></mcfile>, <mcfile name="partial-type-handler.ts" path="src/handlers/typebox/reference/partial-type-handler.ts"></mcfile>, <mcfile name="pick-type-handler.ts" path="src/handlers/typebox/reference/pick-type-handler.ts"></mcfile>, <mcfile name="record-type-handler.ts" path="src/handlers/typebox/reference/record-type-handler.ts"></mcfile>, <mcfile name="required-type-handler.ts" path="src/handlers/typebox/reference/required-type-handler.ts"></mcfile>
-5. **Simple Handlers**: <mcfile name="simple-type-handler.ts" path="src/handlers/typebox/simple-type-handler.ts"></mcfile>, <mcfile name="literal-type-handler.ts" path="src/handlers/typebox/literal-type-handler.ts"></mcfile>
-6. **Advanced Handlers**: <mcfile name="template-literal-type-handler.ts" path="src/handlers/typebox/template-literal-type-handler.ts"></mcfile>, <mcfile name="type-operator-handler.ts" path="src/handlers/typebox/type-operator-handler.ts"></mcfile>, <mcfile name="keyof-type-handler.ts" path="src/handlers/typebox/keyof-type-handler.ts"></mcfile>, <mcfile name="readonly-type-handler.ts" path="src/handlers/typebox/readonly-type-handler.ts"></mcfile>
-7. **Function Handlers**: <mcfile name="function-type-handler.ts" path="src/handlers/typebox/function-type-handler.ts"></mcfile>
-8. **Type Query Handlers**: <mcfile name="type-query-handler.ts" path="src/handlers/typebox/type-query-handler.ts"></mcfile>, <mcfile name="typeof-type-handler.ts" path="src/handlers/typebox/typeof-type-handler.ts"></mcfile>
-9. **Access Handlers**: <mcfile name="indexed-access-type-handler.ts" path="src/handlers/typebox/indexed-access-type-handler.ts"></mcfile>, <mcfile name="type-reference-handler.ts" path="src/handlers/typebox/type-reference-handler.ts"></mcfile>
+5. **Readonly Handlers**: <mcfile name="readonly-type-handler.ts" path="src/handlers/typebox/readonly-type-handler.ts"></mcfile>, <mcfile name="readonly-array-type-handler.ts" path="src/handlers/typebox/readonly-array-type-handler.ts"></mcfile>
+6. **Simple Handlers**: <mcfile name="simple-type-handler.ts" path="src/handlers/typebox/simple-type-handler.ts"></mcfile>, <mcfile name="literal-type-handler.ts" path="src/handlers/typebox/literal-type-handler.ts"></mcfile>
+7. **Advanced Handlers**: <mcfile name="template-literal-type-handler.ts" path="src/handlers/typebox/template-literal-type-handler.ts"></mcfile>, <mcfile name="type-operator-handler.ts" path="src/handlers/typebox/type-operator-handler.ts"></mcfile>, <mcfile name="keyof-type-handler.ts" path="src/handlers/typebox/keyof-type-handler.ts"></mcfile>
+8. **Function Handlers**: <mcfile name="function-type-handler.ts" path="src/handlers/typebox/function-type-handler.ts"></mcfile>
+9. **Type Query Handlers**: <mcfile name="type-query-handler.ts" path="src/handlers/typebox/type-query-handler.ts"></mcfile>, <mcfile name="typeof-type-handler.ts" path="src/handlers/typebox/typeof-type-handler.ts"></mcfile>
+10. **Access Handlers**: <mcfile name="indexed-access-type-handler.ts" path="src/handlers/typebox/indexed-access-type-handler.ts"></mcfile>, <mcfile name="type-reference-handler.ts" path="src/handlers/typebox/type-reference-handler.ts"></mcfile>
+
+#### Readonly Type Handling
+
+The system provides comprehensive support for TypeScript's two distinct readonly constructs through a dual-handler approach:
+
+1. **Readonly Utility Type**: `Readonly<T>` - Handled by <mcfile name="readonly-type-handler.ts" path="src/handlers/typebox/readonly-type-handler.ts"></mcfile>
+   - Registered as a type reference handler for `Readonly` type references
+   - Processes `TypeReferenceNode` with identifier "Readonly"
+   - Generates `Type.Readonly(innerType)` for utility type syntax
+
+2. **Readonly Array Modifier**: `readonly T[]` - Handled by <mcfile name="readonly-array-type-handler.ts" path="src/handlers/typebox/readonly-array-type-handler.ts"></mcfile>
+   - Extends `TypeOperatorBaseHandler` for `ReadonlyKeyword` operator
+   - Processes `TypeOperatorTypeNode` with `SyntaxKind.ReadonlyKeyword`
+   - Generates `Type.Readonly(innerType)` for array modifier syntax
+   - Registered as a fallback handler to handle complex readonly patterns
+
+This dual approach ensures proper handling of both TypeScript readonly constructs:
+
+- `type ReadonlyUser = Readonly<User>` (utility type)
+- `type ReadonlyArray = readonly string[]` (array modifier)
+- `type ReadonlyTuple = readonly [string, number]` (tuple modifier)
 
 #### Handler Management
 
 The <mcfile name="typebox-type-handlers.ts" path="src/handlers/typebox/typebox-type-handlers.ts"></mcfile> class orchestrates all handlers through:
 
 - **Handler Caching**: Caches handler instances for performance optimization
-- **Fallback System**: Provides fallback handlers for complex cases
+- **Fallback System**: Provides fallback handlers for complex cases including readonly array modifiers
 
 ### Import Resolution
 
@@ -181,6 +203,39 @@ export interface InputOptions {
 - **Source Code Input**: Processes TypeScript code directly from strings with validation
 - **Project Context**: Enables proper relative import resolution when working with in-memory source files
 
+### Generic Type Support
+
+The codebase provides comprehensive support for both generic interfaces and generic type aliases, enabling complex type transformations and reusable type definitions.
+
+#### Generic Type Aliases
+
+The `TypeAliasParser` handles both regular and generic type aliases through specialized processing:
+
+1. **Type Parameter Detection**: Automatically detects type parameters using `typeAlias.getTypeParameters()`
+2. **Function Generation**: Creates TypeBox functions for generic type aliases with proper parameter constraints
+3. **TSchema Constraints**: Applies `TSchema` constraints to all type parameters for TypeBox compatibility
+4. **Static Type Generation**: Generates corresponding TypeScript type aliases using `Static<ReturnType<typeof TypeName<T>>>`
+
+#### Generic Interface Support
+
+Generic interfaces are processed through the `InterfaceParser` using a consistent architectural pattern that mirrors the type alias flow:
+
+1. **Unified Generic Processing**: The interface parser now uses the same `GenericTypeUtils.createGenericArrowFunction` flow as type aliases for consistency
+2. **Raw Expression Handling**: The `InterfaceTypeHandler` returns raw TypeBox expressions for generic interfaces, allowing the parser to handle arrow function wrapping
+3. **Parameter Constraint Handling**: Converts TypeScript type parameter constraints to `TSchema` constraints using shared utilities
+4. **Function-Based Schema Generation**: Creates TypeBox schema functions that accept type parameters through the standardized generic arrow function pattern
+5. **Type Safety Preservation**: Maintains full TypeScript type safety through proper static type aliases using `Static<ReturnType<typeof TypeName<T>>>`
+6. **Architectural Consistency**: Both generic interfaces and type aliases now follow the same code generation pattern, improving maintainability and reducing duplication
+
+#### Complex Generic Scenarios
+
+The system supports advanced generic patterns including:
+
+- **Multiple Type Parameters**: Functions with multiple generic parameters (e.g., `ApiResponse<T, E>`)
+- **Nested Generic Types**: Generic types that reference other generic types
+- **Utility Type Combinations**: Complex combinations like `Partial<Readonly<Record<K, V>>>`
+- **Type Parameter Propagation**: Proper handling of type parameters across nested type references
+
 ### Interface Inheritance
 
 The codebase provides comprehensive support for TypeScript interface inheritance through a sophisticated dependency resolution and code generation system:
@@ -234,6 +289,16 @@ The <mcfile name="utils" path="src/utils"></mcfile> directory provides essential
 - **TypeBox Expression Generation**: Converts extracted keys into appropriate TypeBox array expressions
 - **Shared Utilities**: Provides reusable key extraction logic for Pick, Omit, and other utility type handlers to avoid code duplication
 
+#### Generic Type Utilities
+
+The <mcfile name="generic-type-utils.ts" path="src/utils/generic-type-utils.ts"></mcfile> module provides shared utilities for consistent generic type handling across parsers:
+
+- **Generic Arrow Function Creation**: `createGenericArrowFunction` creates standardized arrow functions for generic types with proper type parameter constraints
+- **Type Parameter Processing**: Converts TypeScript type parameters to TypeBox-compatible function parameters with `TSchema` constraints
+- **Variable Statement Generation**: `addTypeBoxVariableStatement` creates consistent variable declarations for TypeBox schemas
+- **Generic Type Alias Generation**: `addGenericTypeAlias` creates standardized static type aliases using `Static<ReturnType<typeof TypeName<T>>>`
+- **Architectural Consistency**: Ensures both interface and type alias parsers follow the same generic type processing pattern
+
 ## Process Overview
 
 1.  **Input**: A TypeScript source file containing `enum`, `type alias`, `interface`, and `function` declarations.

src/handlers/typebox/object/interface-type-handler.ts

@@ -1,6 +1,6 @@
 import { ObjectLikeBaseHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/object/object-like-base-handler'
 import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
-import { HeritageClause, InterfaceDeclaration, Node, ts, TypeParameterDeclaration } from 'ts-morph'
+import { HeritageClause, InterfaceDeclaration, Node, ts } from 'ts-morph'
 
 export class InterfaceTypeHandler extends ObjectLikeBaseHandler {
   canHandle(node: Node): boolean {
@@ -12,11 +12,26 @@ export class InterfaceTypeHandler extends ObjectLikeBaseHandler {
     const heritageClauses = node.getHeritageClauses()
     const baseObjectType = this.createObjectType(this.processProperties(node.getProperties()))
 
-    // If interface has type parameters, generate a function
+    // For generic interfaces, return raw TypeBox expression
+    // The parser will handle wrapping it in an arrow function using GenericTypeUtils
     if (typeParameters.length > 0) {
-      return this.createGenericInterfaceFunction(typeParameters, baseObjectType, heritageClauses)
+      // For generic interfaces, handle inheritance here and return raw expression
+      if (heritageClauses.length === 0) {
+        return baseObjectType
+      }
+
+      const extendedTypes = this.collectExtendedTypes(heritageClauses)
+
+      if (extendedTypes.length === 0) {
+        return baseObjectType
+      }
+
+      // Create composite with extended types first, then the current interface
+      const allTypes = [...extendedTypes, baseObjectType]
+      return makeTypeCall('Composite', [ts.factory.createArrayLiteralExpression(allTypes, true)])
     }
 
+    // For non-generic interfaces, handle as before
     if (heritageClauses.length === 0) {
       return baseObjectType
     }
@@ -33,64 +48,6 @@ export class InterfaceTypeHandler extends ObjectLikeBaseHandler {
     return makeTypeCall('Composite', [ts.factory.createArrayLiteralExpression(allTypes, true)])
   }
 
-  private createGenericInterfaceFunction(
-    typeParameters: TypeParameterDeclaration[],
-    baseObjectType: ts.Expression,
-    heritageClauses: HeritageClause[],
-  ): ts.Expression {
-    // Create function parameters for each type parameter
-    const functionParams = typeParameters.map((typeParam) => {
-      const paramName = typeParam.getName()
-
-      return ts.factory.createParameterDeclaration(
-        undefined,
-        undefined,
-        ts.factory.createIdentifier(paramName),
-        undefined,
-        ts.factory.createTypeReferenceNode(paramName, undefined),
-        undefined,
-      )
-    })
-
-    // Create function body
-    let functionBody: ts.Expression = baseObjectType
-
-    // Handle heritage clauses for generic interfaces
-    const extendedTypes = this.collectExtendedTypes(heritageClauses)
-
-    if (extendedTypes.length > 0) {
-      const allTypes = [...extendedTypes, baseObjectType]
-      functionBody = makeTypeCall('Composite', [
-        ts.factory.createArrayLiteralExpression(allTypes, true),
-      ])
-    }
-
-    // Create type parameters for the function
-    const functionTypeParams = typeParameters.map((typeParam) => {
-      const paramName = typeParam.getName()
-
-      // Use TSchema as the constraint for TypeBox compatibility
-      const constraintNode = ts.factory.createTypeReferenceNode('TSchema', undefined)
-
-      return ts.factory.createTypeParameterDeclaration(
-        undefined,
-        ts.factory.createIdentifier(paramName),
-        constraintNode,
-        undefined,
-      )
-    })
-
-    // Create arrow function
-    return ts.factory.createArrowFunction(
-      undefined,
-      ts.factory.createNodeArray(functionTypeParams),
-      functionParams,
-      undefined,
-      ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-      functionBody,
-    )
-  }
-
   private parseGenericTypeCall(typeText: string): ts.Expression | null {
     const match = typeText.match(/^([^<]+)<([^>]+)>$/)
 

src/handlers/typebox/readonly-array-type-handler.ts

@@ -0,0 +1,12 @@
+import { TypeOperatorBaseHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/type-operator-base-handler'
+import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
+import { SyntaxKind, ts } from 'ts-morph'
+
+export class ReadonlyArrayTypeHandler extends TypeOperatorBaseHandler {
+  protected readonly operatorKind = SyntaxKind.ReadonlyKeyword
+  protected readonly typeBoxMethod = 'Readonly'
+
+  protected createTypeBoxCall(innerType: ts.Expression): ts.Expression {
+    return makeTypeCall('Readonly', [innerType])
+  }
+}

src/handlers/typebox/readonly-type-handler.ts

@@ -1,12 +1,16 @@
-import { TypeOperatorBaseHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/type-operator-base-handler'
+import { TypeReferenceBaseHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/reference/type-reference-base-handler'
+import { getTypeBoxType } from '@daxserver/validation-schema-codegen/utils/typebox-call'
 import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
-import { SyntaxKind, ts } from 'ts-morph'
+import { Node, ts } from 'ts-morph'
 
-export class ReadonlyTypeHandler extends TypeOperatorBaseHandler {
-  protected readonly operatorKind = SyntaxKind.ReadonlyKeyword
-  protected readonly typeBoxMethod = 'Readonly'
+export class ReadonlyTypeHandler extends TypeReferenceBaseHandler {
+  protected readonly supportedTypeNames = ['Readonly']
+  protected readonly expectedArgumentCount = 1
 
-  protected createTypeBoxCall(innerType: ts.Expression): ts.Expression {
-    return makeTypeCall('Readonly', [innerType])
+  handle(node: Node): ts.Expression {
+    const typeRef = this.validateTypeReference(node)
+    const [innerType] = this.extractTypeArguments(typeRef)
+
+    return makeTypeCall('Readonly', [getTypeBoxType(innerType)])
   }
 }