Converters

Language Converters

typeDiagram includes converters for Typeshed, TypeScript, Python, Rust, Go, C#, F#, Dart, PHP, and Protobuf. The nine data-language converters losslessly round-trip the canonical home-page sample; Typeshed additionally imports module functions and overloads. See Typeshed to typeDiagram.

How it works

TypeScript source  ──→  Model  ──→  SVG diagram
                          ↕
Python source      ←──  Model  ←──  typeDiagram source
 

Converters target the Model layer (Layer 2 of the framework). They don't round-trip through DSL text — they work directly with the resolved type graph.

Semantic scalars

Beyond Bool/Int/Float/String/Bytes/Unit, three semantic scalars — DateTime, Uuid, and Decimal — map to the native date / UUID / decimal type of each language in both directions. A timestamp stays a datetime.datetime / DateTimeOffset / time.Time, an id stays a uuid.UUID / Guid / uuid::Uuid — never a bare string. The emitters also pull in the required imports automatically (Python import datetime, Go import "time", Protobuf import "google/protobuf/timestamp.proto").

typeDiagram Python C# / F# TypeScript Rust Go Dart Protobuf PHP
DateTime datetime.datetime DateTimeOffset string (ISO) chrono::DateTime<chrono::Utc> time.Time DateTime google.protobuf.Timestamp \DateTimeImmutable
Uuid uuid.UUID Guid string uuid::Uuid string String string string
Decimal decimal.Decimal decimal string rust_decimal::Decimal string String string string

Unknown types fail generation

When you emit to a language (--to), every referenced type must resolve to a primitive, a generic built-in (List, Map, Option, Any), a declared type, or a generic parameter. A name that resolves to none of these — a typo or an unsupported type like Timestamp or Instant — is rejected with a non-zero exit code and a diagnostic, instead of being passed through verbatim into source that won't compile. (Rendering a diagram still treats unknown names as opaque external references — only code generation is strict.)

TypeScript

What maps

TypeScript typeDiagram
interface User { ... } type User { ... }
type Shape = Circle | Square union Shape { Circle, Square }
type Email = string alias Email = String
string String
number Int
boolean Bool
Array<T> List<T>
Map<K,V> Map<K,V>

From TypeScript

// Input
export interface User {
  id: string;
  name: string;
  email: string | undefined;
}
typediagram --from typescript types.ts > diagram.svg

To TypeScript

Emits export interface for records, discriminated unions with a kind field for unions, export type X = Y for aliases.

Python

What maps

Python typeDiagram
@dataclass class User type User { ... }
class Color(str, Enum) union Color { ... }
class Config(TypedDict) type Config { ... }
str String
int Int
float Float
bool Bool
list[T] / List[T] List<T>
dict[K,V] / Dict[K,V] Map<K,V>
Optional[T] Option<T>

To Python

Emits @dataclass for records, str, Enum for unions with no payloads, separate dataclass per variant + type alias for unions with payloads.

Typeshed

The dedicated typeshed converter parses .pyi syntax with a Python concrete syntax tree. It imports ordinary classes, protocols, dataclasses, TypedDicts, NamedTuples, enums, aliases, top-level functions, async functions, conditional declarations, and overloads. Class methods are intentionally excluded. Use typediagram-typeshed to mirror a complete checkout into .td files.

Rust

What maps

Rust typeDiagram
pub struct User { ... } type User { ... }
pub enum Shape { ... } union Shape { ... }
pub type Email = String alias Email = String
String / &str String
i32 / i64 / u64 Int
f64 Float
bool Bool
Vec<T> List<T>
HashMap<K,V> Map<K,V>
Option<T> Option<T>

Supports struct variants, tuple variants, and unit variants in enums. Generic bounds (e.g. T: Clone) are parsed but bounds are dropped (only the type parameter name is kept).

Lint-clean output [CONV-RUST-IDIOM]

--to rust output compiles under cargo clippy -- -D warnings:

Go

What maps

Go typeDiagram
type User struct { ... } type User { ... }
type Shape interface { ... } union Shape { ... }
type Email = string alias Email = String
string String
int64 Int
float64 Float
bool Bool
[]T List<T>
map[K]V Map<K,V>
*T Option<T>

Go doesn't have native sum types. Interfaces are mapped to unions; exported field names are lowercased in the typeDiagram output.

C#

What maps

C# typeDiagram
record User(...) type User { ... }
abstract record + nested sealed record union Shape { ... }
enum Color { ... } union Color { ... }
using Email = string; alias Email = String

Tagged unions emit as a closed hierarchy (abstract record + nested sealed records, RestClient.Net / Outcome style). Primary-constructor records preserve the original field names. Aliases emit as using Email = string;.

F#

What maps

F# typeDiagram
type User = { ... } type User { ... }
type Shape = Circle | Square union Shape { ... }
type Email = string alias Email = String

F# discriminated unions map directly. Record syntax is used for struct types.

Dart

What maps

Dart typeDiagram
final class User { ... } type User { ... }
sealed class Shape + extends/implements variants union Shape { ... }
typedef Email = String alias Email = String
T? Option<T>
List<T> List<T>
Map<K,V> Map<K,V>

Uses Dart 3 sealed class for tagged unions. First-class generics are preserved.

Record typedefs [CONV-DART-RECORD]

typedef SessionData = ({String draft, String phase}); imports as type SessionData { draft: String phase: String }. Generic and nullable fields keep their types (Map<String, SessionData>, Set<T> → List<T>, int? → Option<Int>). Function types (void Function(String)) and positional record fields ((int, int)) have no typeDiagram equivalent, so the import fails, listing every offending declaration, instead of emitting invalid .td.

PHP

What maps

PHP typeDiagram
final readonly class User { ... } type User { ... }
sealed interface + implementing classes union Shape { ... }
@typediagram-kind alias docblock alias Email = String
?string Option<String>
@param list<T> List<T>
@param array<K,V> Map<K,V>

Emits final readonly class DTOs with constructor-promoted public params, declare(strict_types=1), and PHPStan docblocks for generics. Tagged unions use a sealed interface with implementing classes and @var 'Kind' tags. Note: Option<Unit> is not round-trippable because both collapse to PHP null on parse.

Protobuf

What maps

Protobuf typeDiagram
message User { ... } type User { ... }
enum Color { ... } union Color { Red, Green, Blue }
oneof + nested message variants union Shape { ... }
optional T Option<T>
repeated T List<T>
map<K,V> Map<K,V>

Uses proto3 syntax. Because proto3 can't natively express generics, Option<List<T>>, or type aliases, the converter encodes these via comment directives: // @td-generics:, // @td-type:, // @td-alias:. Unit-only unions emit as enum; struct-variant unions emit as oneof with nested message types.

Programmatic API

import { converters } from "typediagram-core";

// Parse TypeScript source into a Model
const result = converters.typescript.fromSource(tsCode);
if (result.ok) {
  const model = result.value;

  // Convert to Rust
  const rustCode = converters.rust.toSource(model);

  // Convert to Python
  const pyCode = converters.python.toSource(model);

  // Render to SVG (via typeDiagram DSL)
  const { model: modelLayer } = await import("typediagram");
  const tdSource = modelLayer.printSource(model);
  const svg = await renderToString(tdSource);
}

// Available converters
converters.typescript;
converters.python;
converters.typeshed;
converters.rust;
converters.go;
converters.csharp;
converters.fsharp;
converters.dart;
converters.php;
converters.protobuf;

Each converter implements the Converter interface:

interface Converter {
  readonly language: Language;
  fromSource(source: string): Result<Model, Diagnostic[]>;
  toSource(model: Model): string;
}