go/go2ts/typescript/typescript.go

// Package typescript provides primitives to represent TypeScript types, and type declarations.
//
// This package is completely decoupled from Go's reflect package. It provides a set of very simple
// primitives to build an AST-like representation of TypeScript types, and type declarations. Each
// primitive includes a ToTypeScript() method that can be used to recursively generate Go2TS's
// output TypeScript code.
//
// These primitives decouple Go2TS's reflection code from its code generation code, which makes
// Go2TS easier to debug and reason about, and provide a flexible foundation that will allow us to
// extend Go2TS in the future with support for additional types, new features, etc.
//
// The "root" type in this package is the TypeDeclaration interface, which is implemented by the
// InterfaceDeclaration and TypeAliasDeclaration structs.
//
// The names of the primitives in this package are loosely based on the names and terms used in the
// TypeScript AST. Recommended links:
//   - https://ts-ast-viewer.com/
//   - https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API
package typescript

import (
	"fmt"
	"strings"
)

// Type represents a TypeScript type.
type Type interface {
	// ToTypeScript returns a TypeScript expression that can be used as a type, or panics if the type
	// is invalid.
	ToTypeScript() string

	isType()
}

///////////////
// BasicType //
///////////////

// BasicType represents a TypeScript basic type supported by Go2TS.
//
// The "null" and "any" types are represented as basic types for simplicity.
type BasicType string

const (
	// Boolean represents the "boolean" TypeScript type.
	Boolean = BasicType("boolean")

	// Number represents the "number" TypeScript type.
	Number = BasicType("number")

	// String represents the "string" TypeScript type.
	String = BasicType("string")

	// Null represents the "null" TypeScript type.
	Null = BasicType("null")

	// Any represents the "null" TypeScript type.
	Any = BasicType("any")
)

// ToTypeScript implements the Type interface.
func (b BasicType) ToTypeScript() string { return string(b) }

// isType implements the Type interface.
func (b BasicType) isType() {}

var _ Type = (*BasicType)(nil)

/////////////////
// LiteralType //
/////////////////

// LiteralType represents a TypeScript literal type such as "hello", 123, true, etc.
//
// See https://www.typescriptlang.org/docs/handbook/literal-types.html.
type LiteralType struct {
	BasicType BasicType
	Literal   string
}

// ToTypeScript implements the Type interface.
func (l *LiteralType) ToTypeScript() string {
	switch l.BasicType {
	case Boolean:
		if l.Literal != "true" && l.Literal != "false" {
			panic(fmt.Sprintf(`Invalid boolean literal: %q`, l.Literal))
		}
		return l.Literal
	case Number:
		return l.Literal
	case String:
		return fmt.Sprintf(`'%s'`, l.Literal)
	}
	panic(fmt.Sprintf(`Invalid basic type: %q`, l.BasicType))
}

// isType implements the Type interface.
func (l *LiteralType) isType() {}

var _ Type = (*LiteralType)(nil)

///////////////
// ArrayType //
///////////////

// ArrayType represents a TypeScript array type such as string[], MyType[], etc.
type ArrayType struct {
	ItemsType Type
}

// ToTypeScript implements the Type interface.
func (a *ArrayType) ToTypeScript() string {
	fmtStr := "%s[]"
	if _, ok := a.ItemsType.(*UnionType); ok {
		fmtStr = "(%s)[]"
	}
	return fmt.Sprintf(fmtStr, a.ItemsType.ToTypeScript())
}

// isType implements the Type interface.
func (a *ArrayType) isType() {}

var _ Type = (*ArrayType)(nil)

/////////////
// MapType //
/////////////

// MapType represents a TypeScript type that describes an object used as a dictionary of key/value
// pairs, e.g. { [key: string]: MyStruct }.
type MapType struct {
	IndexType Type
	ValueType Type
}

// ToTypeScript implements the Type interface.
func (m *MapType) ToTypeScript() string {
	indexTypeToTS := m.IndexType.ToTypeScript()
	if indexTypeToTS != "number" && indexTypeToTS != "string" {
		panic(fmt.Sprintf("TypeScript type %q cannot be used as an index signature parameter type.", indexTypeToTS))
	}

	return fmt.Sprintf("{ [key: %s]: %s }", indexTypeToTS, m.ValueType.ToTypeScript())
}

// isType implements the Type interface.
func (m *MapType) isType() {}

var _ Type = (*MapType)(nil)

///////////////
// UnionType //
///////////////

// UnionType represents a TypeScript union type, e.g. 'up' | 'right' | 'down' | 'left'.
type UnionType struct {
	Types []Type
}

// ToTypeScript implements the Type interface.
func (u UnionType) ToTypeScript() string {
	tsTypes := []string{}
	for _, t := range u.Types {
		tsTypes = append(tsTypes, t.ToTypeScript())
	}
	return strings.Join(tsTypes, " | ")
}

// isType implements the Type interface.
func (u UnionType) isType() {}

var _ Type = (*UnionType)(nil)

///////////////////
// TypeReference //
///////////////////

// TypeReference represents a reference to a type declared via a TypeDeclaration (e.g. an interface,
// a type alias, etc.) and can be used anywhere a Type can be used.
type TypeReference struct {
	typeDeclaration TypeDeclaration
}

// ToTypeScript implements the Type interface.
func (t *TypeReference) ToTypeScript() string {
	return t.typeDeclaration.QualifiedName()
}

// isType implements the Type interface.
func (t *TypeReference) isType() {}

var _ Type = (*TypeReference)(nil)

/////////////////////
// TypeDeclaration //
/////////////////////

// TypeDeclaration represents a TypeScript type declaration, which can be an interface declaration,
// a type alias, etc.
type TypeDeclaration interface {
	// TypeReference returns a reference to the declared type.
	TypeReference() *TypeReference

	// QualifiedName returns the qualified name of the declared type, e.g. MyNamespace.MyType.
	QualifiedName() string

	// ToTypeScript converts the TypeDeclaration to valid TypeScript.
	ToTypeScript() string

	isTypeDeclaration()
}

//////////////////////////
// TypeAliasDeclaration //
//////////////////////////

// TypeAliasDeclaration represents a TypeScript type alias declaration, e.g. type Color = string.
type TypeAliasDeclaration struct {
	// Namespace is the namespace that the type alias belongs to, or empty for the global namespace.
	Namespace  string
	Identifier string
	Type       Type
	// GenerateNominalTypes tells TypeAliasDeclaration to generate nominal TypeScript types
	// for aliased Go types. For background on "nominal typing" in TypeScript, see
	// https://www.typescriptlang.org/play#example/nominal-typing and
	// https://basarat.gitbook.io/typescript/main-1/nominaltyping.
	// The TypeScript compiler itself uses this technique to achieve
	// a similar effect as with Go's type aliases:
	// https://github.com/Microsoft/TypeScript/blob/7b48a182c05ea4dea81bab73ecbbe9e013a79e99/src/compiler/types.ts#L693
	GenerateNominalTypes bool
}

// TypeReference implements the TypeDeclaration interface.
func (a *TypeAliasDeclaration) TypeReference() *TypeReference {
	return &TypeReference{
		typeDeclaration: a,
	}
}

// QualifiedName implements the TypeDeclaration interface.
func (a *TypeAliasDeclaration) QualifiedName() string {
	return makeQualifiedName(a.Namespace, a.Identifier)
}

// ToTypeScript implements the TypeDeclaration interface.
func (a *TypeAliasDeclaration) ToTypeScript() string {
	if _, ok := a.Type.(*UnionType); !ok && a.GenerateNominalTypes {
		if a.Namespace == "" {
			return fmt.Sprintf(`export type %s = %s & {
	/**
	* WARNING: Do not reference this field from application code.
	*
	* This field exists solely to provide nominal typing. For reference, see
	* https://www.typescriptlang.org/play#example/nominal-typing.
	*/
	_%sBrand: 'type alias for %s'
};

export function %s(v: %s): %s {
	return v as %s;
};`,
				a.Identifier,
				a.Type.ToTypeScript(),
				strings.ToLower(string(a.Identifier[0]))+a.Identifier[1:],
				a.Type.ToTypeScript(),
				a.Identifier,
				a.Type.ToTypeScript(),
				a.Identifier,
				a.Identifier)
		}
		return fmt.Sprintf(`export namespace %s {
    export type %s = %s & {
		/**
		* WARNING: Do not reference this field from application code.
		*
		* This field exists solely to provide nominal typing. For reference, see
		* https://www.typescriptlang.org/play#example/nominal-typing.
		*/
        _%sbrand: 'type alias for %s'
    };

    export function %s(v: %s): %s {
        return v as %s;
    };
}`,
			a.Namespace,
			a.Identifier,
			a.Type.ToTypeScript(),
			strings.ToLower(string(a.Identifier[0]))+a.Identifier[1:],
			a.Type.ToTypeScript(),
			a.Identifier,
			a.Type.ToTypeScript(),
			a.Identifier,
			a.Identifier)
	}
	if a.Namespace == "" {
		return fmt.Sprintf("export type %s = %s;", a.Identifier, a.Type.ToTypeScript())
	}
	return fmt.Sprintf("export namespace %s { export type %s = %s; }", a.Namespace, a.Identifier, a.Type.ToTypeScript())
}

// isTypeDeclaration implements the TypeDeclaration interface.
func (a *TypeAliasDeclaration) isTypeDeclaration() {}

var _ TypeDeclaration = (*TypeAliasDeclaration)(nil)

//////////////////////////
// InterfaceDeclaration //
//////////////////////////

// PropertySignature represents a property signature of a TypeScript interface declaration.
type PropertySignature struct {
	Identifier string
	Type       Type
	Optional   bool
}

// ToTypeScript converts the PropertySignature to a valid TypeScript interface property declaration.
func (p *PropertySignature) ToTypeScript() string {
	optionalString := ""
	if p.Optional {
		optionalString = "?"
	}
	return fmt.Sprintf("%s%s: %s;", p.Identifier, optionalString, p.Type.ToTypeScript())
}

// InterfaceDeclaration represents a TypeScript interface declaration.
type InterfaceDeclaration struct {
	// Namespace is the namespace that the interface belongs to, or empty for the global namespace.
	Namespace  string
	Identifier string
	Properties []PropertySignature
}

// TypeReference implements the TypeDeclaration interface.
func (i *InterfaceDeclaration) TypeReference() *TypeReference {
	return &TypeReference{
		typeDeclaration: i,
	}
}

// QualifiedName implements the TypeDeclaration interface.
func (i *InterfaceDeclaration) QualifiedName() string {
	return makeQualifiedName(i.Namespace, i.Identifier)
}

// ToTypeScript implements the TypeDeclaration interface.
func (i *InterfaceDeclaration) ToTypeScript() string {
	var sb strings.Builder

	namespaced := i.Namespace != ""
	interfaceIndentation := ""
	propertyIndentation := "\t"

	if namespaced {
		sb.WriteString(fmt.Sprintf("export namespace %s {\n", i.Namespace))
		interfaceIndentation = "\t"
		propertyIndentation = "\t\t"
	}

	sb.WriteString(interfaceIndentation)
	sb.WriteString(fmt.Sprintf("export interface %s {\n", i.Identifier))

	for _, prop := range i.Properties {
		sb.WriteString(propertyIndentation)
		sb.WriteString(prop.ToTypeScript())
		sb.WriteString("\n")
	}

	sb.WriteString(interfaceIndentation)
	sb.WriteString("}")

	if namespaced {
		sb.WriteString("\n}")
	}

	return sb.String()
}

// isTypeDeclaration implements the TypeDeclaration interface.
func (i *InterfaceDeclaration) isTypeDeclaration() {}

var _ TypeDeclaration = (*InterfaceDeclaration)(nil)

///////////////////////
// Utility functions //
///////////////////////

// makeQualifiedName returns a qualified TypeScript type name given a namespace and an identifier.
// If the namespace is the empty string, the type is assumed to be declared in the global namespace.
// Does not support nested namespaces.
func makeQualifiedName(namespace, identifier string) string {
	if namespace != "" {
		return fmt.Sprintf("%s.%s", namespace, identifier)
	}
	return identifier
}