SimpleTypeScript.TypeGeneration 1.1.0

SimpleTypeScript.TypeGeneration 📘

Generate TypeScript from C# types: give it roots, and it follows what their members reach — an interface per shape, a string union per enum — written through SimpleTypeScript.

var module = new TsModule();

new TypeWalker(new TypeWalkerOptions
    {
        Documentation = new XmlDocumentationSource(),
        Mappings = new Dictionary<Type, TsType> { [typeof(Money)] = TsType.String },
    })
    .Add(typeof(Order), typeof(Customer))
    .Declare(module);

File.WriteAllText(path, module.Render());

Given this C#:

/// <summary>One order, as the API returns it.</summary>
public sealed class Order
{
    /// <summary>Assigned when the order is placed.</summary>
    public Guid Id { get; init; }

    [JsonPropertyName("ref")]
    public string Reference { get; init; } = string.Empty;

    [JsonIgnore]
    public string InternalNote { get; init; } = string.Empty;

    public DateTimeOffset? ShippedAt { get; init; }

    public OrderStatus Status { get; init; }

    public IReadOnlyList<Line> Lines { get; init; } = [];
}

it writes this:

/** One order, as the API returns it. */
export interface Order {
  /** Assigned when the order is placed. */
  id: string;
  ref: string;
  shippedAt: string | null;
  status: OrderStatus;
  lines: Line[];
}

export type OrderStatus = "Open" | "Shipped";

It reads the shape that is serialized, not only the shape that is declared. [JsonIgnore] drops a member — or makes it optional, where its condition says the producer merely omits it sometimes — [JsonPropertyName] renames it, [JsonExtensionData] is not a member at all, and everything else takes the naming policy: camel case by default, matching what a JSON API is usually configured with. A generator that reads the C# alone spells every member wrong the moment a policy is set, and nothing says so until a field is undefined.

What it decides, and how to overrule it

A mapped type is a leaf: nothing behind it is reached, which makes mapping the fix for a framework type dragging its own graph into the output, and the way to say a type is carried as something other than its shape. Declarations are emitted in name order and members in declaration order, so the file is byte-stable across runs and machines.

Absent and null are two questions

? says the key may not be there; | null says what may be in it. They are independent, and which you get follows the producer rather than TypeScript convention — a JSON.stringify payload omits undefined, but System.Text.Json writes "note":null unless it is configured not to.

var options = new TypeWalkerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };

There is no | undefined: JSON has no such literal, so a parsed payload cannot hold one. undefined only ever arrives as a missing key, which is what ? already says.

readonly is opt-in, and shallow

ReadOnlyMembers writes readonly on every member. It is off by default — which is what a generated type looks like in the generators that offer this at all: --immutable in openapi-typescript, immutableTypes in graphql-codegen, [TsReadonly] per member in TypeGen. None of them makes it the default.

It is an option rather than an attribute on purpose. Nothing here declares an attribute: the walk reads System.Text.Json's, the compiler's own required, and DataAnnotations' [Required], all of which are in the shared framework — so the assembly holding your contracts is generated from without referencing this one. Per-member marking would buy granularity by putting a codegen package in the dependency graph of the types it describes.

Worth knowing what you get before asking for it:

readonly lines: Line[];   // order.lines = []      refused
                          // order.lines.push(x)   allowed

TypeScript's readonly stops at the member. Meaning it would need the elements to be readonly too — readonly lines: readonly Line[] — which nothing here can spell yet. So this is the shallow half: useful where that is what you wanted, misleading if you expected the payload to be frozen.

Enums

EnumStyle picks between three. The first two are decided by what the producer serializes; the third is a preference about what a consumer wants beside the type.

var options = new TypeWalkerOptions { EnumStyle = EnumStyle.ConstObject };

// StringUnion (default) — JsonStringEnumConverter
export type Status = "Open" | "Shipped";

// NumberUnion — an enum serialized by value; the member names cannot survive
export type Status = 0 | 1;

// ConstObject — a value to iterate, and the type read off it
export const Status = {
  "Open": "Open",
  "Shipped": "Shipped",
} as const;

export type Status = typeof Status[keyof typeof Status];

The const object's key is what a consumer writes and its value is what the wire carries, so EnumNamingPolicy moves only the second: Status.Open === "open" still reads as the C# does. Object.values(Status) is what a union alone cannot give you — a union has no run-time existence, so nothing can enumerate it.

export enum is deliberately absent. It is the one form with runtime semantics of its own, which makes it the form a type-stripping loader — erasableSyntaxOnly, Node's own — refuses to run. An enum that should not be generated at all is a mapping like any other type.

Generators with more than one file

A build-time tool usually writes several — the types, a vocabulary, a palette. A module says what it is, and the pipeline owns the banner, the directories and the writing:

internal sealed class ApiTypesModule : TypeModule
{
    public override string FileName => "api/generated/index.ts";

    public override string Source => "the wire contracts";

    public override bool OwnsDirectory => true;

    protected override IEnumerable<Type> Roots => [typeof(Order), typeof(Customer)];

    protected override TypeWalkerOptions Options => new() { Documentation = new XmlDocumentationSource() };
}

var writer = new ModuleWriter(outputDirectory);

foreach (var module in ModuleCatalog.From())
{
    var file = writer.Write(module);
    Console.WriteLine($"{file.Summary} -> {file.FileName}");
}

• ModuleCatalog discovers rather than listing — adding a generator is one class and no edit to a registry. Internal types count, and modules come back ordered by file name so a run reports the same way every time. Two modules claiming one path is a refusal, not a silent overwrite.
• ModuleWriter creates the directory a module names, and empties it first for a module that OwnsDirectory — a file the generator has stopped producing otherwise stays importable, and a stale shape is the one nobody notices.
• GeneratedHeader writes the do-not-edit banner. The default names the entry assembly, so a project renamed or moved takes its header with it; GeneratedHeader.None writes none.
• Everything the pipeline can refuse is a GenerationException, including what the emitter refuses underneath it — one thing for a host to catch and one sentence to print. Which half refused stays on InnerException.

A module that builds its declarations by hand implements IGeneratedModule directly; TypeModule is for the common case where a module is a set of roots.

What it does not read

Named rather than discovered, because each is a shape that would otherwise generate and be quietly wrong:

• Polymorphism. [JsonDerivedType] writes a discriminator and the derived members; the walk describes the base shape it was given and nothing else.
• Fields. Only properties are read, so IncludeFields and [JsonInclude] on a field do not reach the output.
• [JsonPropertyOrder]. Members follow declaration order, which changes the order of keys in the file and never the shape.
• Imports. One module holds every declaration it needs, so nothing imports anything. A generator wanting one type per file needs a declaration kind and a file graph that are not here.
• Direction. A shape describes what the producer serializes. The two ignore conditions naming a direction — WhenWriting and WhenReading — are read that way round, which is backwards for a payload the consumer builds rather than receives.
• 64-bit precision. long, ulong and decimal are number, which is what the serializer writes by default and what a JSON number is. Above 2^53 that is lossy on the other side; a producer carrying such a value as a string says so with a Mappings entry.

Installing

dotnet add package SimpleTypeScript.TypeGeneration

net8.0 and net10.0. This half reflects, which is why it is a package of its own: the emitter reflects over nothing, and a consumer publishing NativeAOT keeps that by taking only the emitter.

The two ignore conditions naming a direction — WhenWriting and WhenReading — arrived in .NET 10, and so did the serializer that honours them, so on net8.0 there is no producer configured that way for a shape to describe. Nothing else differs between the two.

License

MIT. See LICENSE.txt.