Dekiru.TypeScriptClientBuilder 6.2.2

TypeScript Client Builder

A .NET library that automatically generates TypeScript client code and DTOs from ASP.NET Core controllers. Reduce boilerplate and keep your frontend and backend in sync.

Features

• Automatic Client Generation: Generates TypeScript HTTP client methods from your ASP.NET Core controllers
• DTO Export: Automatically exports C# DTOs to TypeScript interfaces
• Enum Support: Multiple enum export options (numbers, strings, unions, const enums)
• Type Safety: Full type safety between your C# API and TypeScript client
• Inheritance Support: Optional support for inheritance chains in generated types
• Record Type Support: C# records are automatically converted to TypeScript interfaces
• NDJSON Streaming: Server-sent streaming with automatic callback generation
• Customizable: Extensive configuration options for indentation, naming, and behavior
• Checksum Optimization: Skip regeneration when nothing has changed
• XML Documentation: Import your XML documentation comments into TypeScript
• Flexible Parameters: Support for named parameters, headers, event callbacks, and more

Installation

Install via NuGet:

dotnet add package Dekiru.TypeScriptClientBuilder

Or via Package Manager Console:

Install-Package Dekiru.TypeScriptClientBuilder

Quick Start

Basic Usage

Add the following to your ASP.NET Core application (typically in Program.cs):

using TypeScriptClientBuilder;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();
app.MapControllers();

// Generate TypeScript client
ClientBuilder.Build(new ClientConfiguration
{
    Output = "ClientOutput"
});

app.Run();

This will scan all your controllers and generate TypeScript files in the ClientOutput directory.

Example Controller

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get(CancellationToken cancellationToken)
    {
        // Your implementation
    }
}

This generates a TypeScript client with type-safe methods to call your API.

Helpful for LLMs

Library Architecture & Namespaces

The TypeScriptClientBuilder library uses the following main namespaces:

• TypeScriptClientBuilder - Root namespace for the library
• TypeScriptClientBuilder.Attributes - Custom attributes for controlling generation (ClientBuilderAttribute, UnionTypeAttribute, etc.)
• TypeScriptClientBuilder.Primitives - Core data models representing parsed controller structure (Controller, Method, Parameter, TsType)
• TypeScriptClientBuilder.Utils - Utility classes for code generation (TypeNameResolver, TypeScriptWriter, TypeExporter)
• TypeScriptClientBuilder.Streaming - Streaming result types (NdJsonResult)

Entry Points & Configuration

Main Entry Point:

TypeScriptClientBuilder.ClientBuilder.Build(ClientConfiguration configuration)

Configuration Object: The ClientConfiguration class contains all library settings for customization:

• Output directory, file cleaning, checksum validation
• Type generation preferences (inheritance, partials, nullability)
• Method signature options (named parameters, generic methods, event callbacks)
• Enum export strategies (strings, union types, const enums)
• Advanced options (XML documentation, includes, custom type formatters)

Core Components Deep Dive

1. Controller Parsing (ExportService.CreateModel())

• Scans assemblies for [ApiController] decorated classes
• Extracts HTTP verb information (HttpGet, HttpPost, etc.)
• Parses route templates from controller and method attributes
• Collects method parameters and metadata

2. Type Export Pipeline (TypeExporter.Export)

• Recursively processes all types used in returned values and parameters
• Handles type relationships: DTOs, enums, generic types, arrays, dictionaries
• Tracks exported types to prevent duplication
• Applies nullable type transformations

3. Type Resolution Engine (TypeNameResolver.Resolve)

This component converts C# types to TypeScript types with intelligent handling:

System.String → string
int? → { [key]?: T };
MyNamespace.UserDto → { name: string; id: number; };
List<Item> → Item[];
Dictionary<string, User> → { [key: string]: User };
Task<T> → Promise<T>;
IEnumerable<T> → T[];
NdJsonResult<T> → T (with streaming callbacks)

4. TypeScript Code Generation (TypeScriptWriter)

Handles code generation for different export types:

• BeginInterface() - Defines TypeScript interfaces with appropriate properties
• BeginEnum() - Creates enum definitions based on EnumTypes configuration
• WriteStartTSDoc() - Generates JSDoc comments from XML documentation
• Block nesting with automatic indentation management

Type System Documentation

Primitives Namespace Classes:

• Controller - Represents a parsed controller with methods collection
• Method - Represents a controller action with HTTP verb, route, and type info
• Parameter - Represents a method parameter with binding type and TypeScript type
• TsType - Core CLR type representation with type system operations (IsArray, IsEnum, IsDto, GenericTypeArguments)
• Description - XML documentation wrapper for methods and properties

Utils Namespace Classes:

• TypeNameResolver - Complex type mapping from C# to TypeScript with context-aware transformations
• TypeExporter - Type management, export tracking, and registration
• TypeScriptWriter - Low-level TypeScript code generation with block management
• TypeNameResolver - Type name resolution and transformation for proper output

Streaming Namespace:

• NdJsonResult - Server-sent streaming result type for large data handling

Attribute System:

• ClientBuilderAttribute (with ClientBuilderSettings flags) - Controls generation behavior at controller/method level
• ClientBuilderMethodNameAttribute - Customizes generated method names
• ClientBuilderReturnsUrlAttribute / ClientBuilderRedirectAttribute - Controls file download behavior
• AddQueryParameterAttribute - Adds implicit query parameters
• UnionTypeAttribute - Generates string union types like "value1" | "value2" | "value3"
• TypedIdOfAttribute - Overrides property types for custom type transformations
• PartialAttribute - Creates Partial<T> types for partial data
• KeyOfAttribute - Generates keyof T types
• NullableAttribute / OptionalAttribute - Explicit property nullability/optional markers

Generation Workflow

1. Controller Discovery - Assemblies scanned for controllers with [ApiController] attribute
2. Method Extraction - HTTP verb attributes (HttpGet, HttpPost, etc.) trigger method discovery
3. Type Analysis - TypeScript type resolution for return types and parameters
4. Export Registration - Controllers and DTOs registered for code generation
5. Type Normalization - Enums, nullable types, and generic types processed
6. Code Writing - TypeScript interfaces, enums, and client methods written to Output directory
7. File Structure

Generated output directory contains:

Output/
├── HttpClient.ts           # Base client implementation
├── Enums.ts                # All enum definitions
├── Dto.ts                  # All DTO interfaces
└── <ControllerName>.ts     # Controller-specific methods

Programmatic Usage Patterns

Custom Type Formatting:

TypeFormatter = type => type.Name + "Dto"

Wildcard Includes:

Includes = new HashSet<string> 
{
    "MyApi.Types.*",         // Include all types in namespace
    "MyApi.Controllers.*"    // Include all controller exports
}

Custom Logging:

LoggingCallback = message => Logger.Info($"[ClientBuilder] {message}")

Complete API Reference Summary

Key Enums:

• ExportType - (Controller, DTO, Enum) Export category
• FileResultBehavior - (Redirect, Uri) File download return strategy
• EnumTypes (Flags) - (None, Strings, Union, Const) Enum export options
• ClientBuilderSettings (Flags) - (AddHeader, AddEventCallback, AddReturnXhrFlag, OmitHeader, OmitEventCallback, OmitReturnXhrFlag)

Core Classes:

• ClientBuilder.Build(ClientConfiguration config) - Initializes and runs generation
• TypeExporter.GetDTOs() - Returns collected DTO types
• TypeExporter.GetEnums() - Returns collected enum types

Common TypeScript Types Generated:

• Interfaces for C# classes and records
• Type-safe method signatures with parameter objects
• Enum translations based on EnumTypes configuration
• nullability handling with ? suffix or optional<T>

This architecture enables the library to provide end-to-end TypeScript client generation while maintaining flexibility for advanced use cases and customizations.

Configuration Options

ClientConfiguration

Example Configuration

ClientBuilder.Build(new ClientConfiguration
{
    Output = "wwwroot/api",
    CleanOutput = true,
    UseChecksum = true,
    XmlDocumentationFile = "bin/Debug/net8.0/MyApi.xml",
    EnumType = EnumTypes.Strings | EnumTypes.Union,
    ConvertNullablePropsToOptional = true,
    UseNamedParameters = true,
    Indentation = new Indentation 
    { 
        Character = ' ', 
        Size = 2 
    },
    LoggingCallback = message => Console.WriteLine($"[ClientBuilder] {message}")
});

Attributes

Controller & Method Attributes

[ClientBuilderAttribute]

Configure client generation at controller or method level using ClientBuilderSettings flags:

[ClientBuilder(ClientBuilderSettings.AddHeader | ClientBuilderSettings.AddEventCallback)]
public class MyController : ControllerBase
{
    [ClientBuilder(ClientBuilderSettings.OmitHeader)]
    public IActionResult MyMethod() { }
}

[ClientBuilderIgnore]

Exclude controllers, methods, properties, or parameters from generation:

[ClientBuilderIgnore]
public class InternalController : ControllerBase { }

[ClientBuilderMethodName]

Override the generated method name:

[ClientBuilderMethodName("fetchWeather")]
public IActionResult GetWeather() { }

[ClientBuilderReturnsUrl] / [ClientBuilderRedirect]

Control file download behavior (GET requests only):

[ClientBuilderReturnsUrl]
public FileResult DownloadFile() { }

[AddQueryParameter]

Add query parameters without declaring them in the method:

[AddQueryParameter("version", typeof(int))]
public IActionResult Get() { }

Type Attributes

[UnionType]

Generate string union types:

public class Model
{
    [UnionType("success", "error", "pending")]
    public string Status { get; set; }
}

Generates: status: "success" | "error" | "pending"

[KeyOf]

Generate keyof types:

public class Model
{
    [KeyOf(typeof(User))]
    public string Field { get; set; }
}

Generates: field: keyof User

[TypedIdOf]

Override property type:

public class Model
{
    [TypedIdOf(typeof(User))]
    public int UserId { get; set; }
}

[Partial]

Generate Partial<T> types. You can optionally specify a type override:

public IActionResult Update([Partial] User user) { }

// With explicit type
public IActionResult Patch([Partial(typeof(UserDto))] User user) { }

[Nullable] / [Optional]

Mark properties as nullable or optional:

public class Model
{
    [Nullable]
    public string Name { get; set; }
    
    [Optional]
    public int? Age { get; set; }
}

NDJSON Streaming

Return NdJsonResult<T> from a controller action to stream data as newline-delimited JSON. The generator automatically produces a TypeScript method with an onData callback instead of a regular return value.

[HttpGet("stream")]
public NdJsonResult<WeatherForecast> GetStream(int count)
{
    return new NdJsonResult<WeatherForecast>(GetForecasts(count));
}

private async static IAsyncEnumerable<WeatherForecast> GetForecasts(int count)
{
    for (var i = 0; i < count; i++)
    {
        await Task.Delay(500);
        yield return new WeatherForecast { /* ... */ };
    }
}

Alternatively, you can use the factory method:

return NdJsonResult.Create(GetForecasts(count));

The generated TypeScript method will look like:

getStream(count: number, onData: (data: StreamedResponse<WeatherForecast>) => void): Promise<void>

StreamedResponse<T> includes properties for the streamed data and completion status. The final chunk will have done: true to indicate the end of the stream.

Supported Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

Development

Building

dotnet build

Running Sample

The Sample project demonstrates the library's features:

cd Sample
dotnet run

Check the Output directory for generated TypeScript files.

Publishing to NuGet (Internal use only)

1. Update version in Source/TypeScriptClientBuilder.csproj:

   <BaseVersion>6.2.0</BaseVersion>
   <PreviewVersion>-preview.1</PreviewVersion>
   

   Preview versions will have -preview.x suffix, while stable releases will leave the PreviewVersion empty.

2. Commit and push changes

3. Run the DevOps pipeline

4. Package will appear on nuget.org within a few minutes

License

MIT

Authors

Dekiru Solutions