Dekiru.TypeScriptClientBuilder 6.2.3

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.

The alternative way to identify that the streaming is done is by awaiting the promise returned by the method. The promise will resolve once the stream is complete, so you can use it like this:

await getStream(count, (data) => {
    if (!data.done) {
        console.log(data.data);
    }
});

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