tygo

Tygo supports Go generic types (Go 1.18+) out of the box, translating them into TypeScript generic interfaces/types.

type UnionType interface {
	uint64 | string
} 

type ABCD[A, B string, C UnionType, D int64 | bool] struct {
	A A `json:"a"` 
	B B `json:"b"` 
	C C `json:"c"` 
	D D `json:"d"` 
}

Tygo supports interface inheritance using the tstype:",extends" tag on struct fields. Only struct types can be extended.

• Standard Structs: Use tstype:",extends".
• Struct Pointers: These are extended using Partial<MyType>. To make them required, use tstype:",extends,required".
• Named Fields: You can extend named struct fields.
• External Structs: You can extend structs from other packages.

type Other[T int] struct {
	*Base                  `       tstype:",extends,required"` 
	Base2[T]               `       tstype:",extends"` 
	*OptionalPtr           `       tstype:",extends"` 
	external.AnotherStruct `       tstype:",extends"` 
	OtherValue             string `                  json:"other_value"` 
}

For types that cannot be directly represented in Go (like complex tuples), use the //tygo:emit directive.

Emit before a struct

A directive placed above a struct will emit the text following it before the struct definition.

//tygo:emit export type Genre = "novel" | "crime" | "fantasy"
type Book struct {
	Title    string    `json:"title"` 
	Genre    string    `json:"genre" tstype:"Genre"` 
}

Emit multi-line content

A directive on a string variable will emit the contents of that variable.

//tygo:emit
var _ = `export type StructAsTuple=[
  a:number,
  b:number,
  c:string,
]
` 

type CustomMarshalled struct {
  Content []StructAsTuple `json:"content"` 
}

Install the tygo CLI tool using go install to generate TypeScript typings from Go source files.

go install github.com/gzuidhof/tygo@latest

The recommended way to use tygo is via the CLI. Create a tygo.yaml configuration file to specify the Go packages to convert and any custom type mappings. Then run the generate command.

Example tygo.yaml:

packages:
  - path: "github.com/gzuidhof/tygo/examples/bookstore"
    type_mappings:
      time.Time: "string /* RFC3339 */"
      null.String: "null | string"
      null.Bool: "null | boolean"
      uuid.UUID: "string /* uuid */"
      uuid.NullUUID: "null | string /* uuid */"

Run the generation:

tygo generate

By default, the output TypeScript file is written next to the Go source files.

Tygo can generate TypeScript interfaces that match how Go handles YAML serialization.

By default, Tygo respects yaml Go struct tags (and json tags). However, if you want to emulate the behavior of gopkg.in/yaml.v2 where untagged struct fields are automatically downcased in the resulting YAML, you must set the flavor configuration option to "yaml".

When flavor: "yaml" is used, untagged fields in the TypeScript output will be lowercased to match standard Go YAML behavior.

packages:
  - path: "github.com/my/package"
    output_path: "webapp/api/types.ts"
    flavor: "yaml"

This example shows how Tygo maps Go structs to TypeScript interfaces, specifically demonstrating how the flavor: "yaml" setting affects untagged fields.

Go Input:

type Foo struct {
	TaggedField string `yaml:"custom_field_name_in_yaml"`
    UntaggedField string
}

TypeScript Output (with flavor: "yaml"):

export interface Foo {
  custom_field_name_in_yaml: string;
  untaggedfield: string;
}

This example demonstrates how Tygo converts a Go string-based constant group into TypeScript using both enum and union styles.

Go Input:

type Status = string
const (
    StatusActive   Status = "active"
    StatusInactive Status = "inactive"
    StatusPending  Status = "pending"
)

TypeScript Output (enum_style: "enum"):

export enum Status {
  Active = "active",
  Inactive = "inactive",
  Pending = "pending",
}

TypeScript Output (enum_style: "union"):

export const StatusActive = "active";
export const StatusInactive = "inactive";
export const StatusPending = "pending";
export type Status = typeof StatusActive | typeof StatusInactive | typeof StatusPending;

This example demonstrates how Tygo handles Go numeric constants using iota.

Go Input:

type Priority int
const (
    PriorityLow Priority = iota
    PriorityMedium
    PriorityHigh
)

TypeScript Output (enum_style: "enum"):

export enum Priority {
  Low = 0,
  Medium,
  High,
}

TypeScript Output (enum_style: "union"):

export const PriorityLow = 0;
export const PriorityMedium = 1;
export const PriorityHigh = 2;
export type Priority = typeof PriorityLow | typeof PriorityMedium | typeof PriorityHigh;