ts

Documentation

Overview

Package ts adds TypeScript support to gojs. It transpiles TypeScript to JavaScript using github.com/iceisfun/typescript — a hoisting of Microsoft's typescript-go compiler — and runs the result on a gojs VM.

Importing this package is what pulls the typescript-go dependency into a build; the gojs core (module github.com/iceisfun/gojs) stays dependency-free, so embeddings that only run JavaScript pay nothing for it.

Transpilation is checker-free (the isolatedModules model): types are erased and TypeScript-only syntax is lowered, but the program is not type-checked. Type errors are ignored — the goal is to *run* TypeScript, not validate it.

Index

• func IsTypeScript(id string) bool
• func Lower(sf *tsast.SourceFile, name, srcText string) (prog *gast.Program, err error)
• func Provider(base interp.ModuleProvider, opts ...Option) interp.ModuleProvider
• func RunString(vm *interp.Interpreter, name, tsSrc string) (interp.Value, error)
• func RunStringAST(vm *interp.Interpreter, name, tsSrc string) (interp.Value, error)
• func Transpile(fileName, src string) (string, error)
• func WithTypeScript(base interp.ModuleProvider, opts ...Option) []interp.Option
• type Mapper
  • func NewMapper() *Mapper
  • func (m *Mapper) MapPosition(source string, line, column int) (string, int, int, bool)
  • func (m *Mapper) SourceText(source string) (string, bool)
• type Option
  • func DisableAST() Option
  • func Permissive() Option
• type UnsupportedNodeError
  • func (e *UnsupportedNodeError) Error() string
• type UnsupportedSyntaxError
  • func (e *UnsupportedSyntaxError) Error() string

Functions

func IsTypeScript

func IsTypeScript(id string) bool

IsTypeScript reports whether a module id names a TypeScript source file.

func Lower

func Lower(sf *tsast.SourceFile, name, srcText string) (prog *gast.Program, err error)

Lower translates a lowered TypeScript SourceFile (from transpiler.ModuleAST) into a gojs *ast.Program. name identifies the module in diagnostics; srcText is the original TypeScript source, used to resolve node byte offsets into 1-based line/column positions for stack traces (pass "" to skip position mapping).

func Provider

func Provider(base interp.ModuleProvider, opts ...Option) interp.ModuleProvider

Provider wraps a base interp.ModuleProvider (the "CodeProvider" that decides how files are included — from disk, memory, network, game data, etc.) so that any module whose id is a TypeScript file is transpiled to JavaScript before gojs evaluates it. Non-TypeScript modules pass through unchanged.

Resolution is delegated entirely to base, so host behavior over what a specifier means is preserved.

func RunString

func RunString(vm *interp.Interpreter, name, tsSrc string) (interp.Value, error)

RunString transpiles a self-contained TypeScript program and runs it on vm as a top-level script. It is for scripts that do not use top-level import/export (those belong to a module and should be reached through a TypeScript-aware Provider via require); name appears in diagnostics.

func RunStringAST

func RunStringAST(vm *interp.Interpreter, name, tsSrc string) (interp.Value, error)

RunStringAST runs a self-contained TypeScript program on vm via the AST path: it lowers the source to a typescript-go AST (transpiler.ModuleAST), translates that directly into a gojs *ast.Program (Lower), and executes it — skipping the emit-JavaScript-text-then-reparse round trip that RunString performs.

It is for scripts that do not use top-level import/export (see RunString). A node the lowerer does not yet handle returns an *UnsupportedNodeError; a caller that needs total coverage can fall back to RunString on that error.

func Transpile

func Transpile(fileName, src string) (string, error)

Transpile converts TypeScript source to CommonJS JavaScript, the module form gojs's require()/module system evaluates. fileName is used for diagnostics and selects TSX parsing for a .tsx name.

func WithTypeScript

func WithTypeScript(base interp.ModuleProvider, opts ...Option) []interp.Option

WithTypeScript returns the VM options for running TypeScript with source-mapped error stacks: a transpiling module provider over base, plus the matching source mapper so a thrown error's stack reports the original .ts line/column. Compose it with other options:

opts := append(ts.WithTypeScript(base), gojs.WithPrintProvider(pp))
vm := gojs.New(opts...)

Types

type Mapper

type Mapper struct {
	// contains filtered or unexported fields
}

Mapper is an interp.SourceMapper that accumulates the source maps of the TypeScript modules transpiled through this package, so error stacks can report original .ts positions. It is safe for concurrent use. Install it on a VM with gojs.WithSourceMapper and feed it from a transpiling provider (see WithTypeScript).

func NewMapper

func NewMapper() *Mapper

NewMapper returns an empty source-map registry.

func (*Mapper) MapPosition

func (m *Mapper) MapPosition(source string, line, column int) (string, int, int, bool)

MapPosition implements interp.SourceMapper: it maps a generated (transpiled) 1-based position for source back to the original .ts position.

func (*Mapper) SourceText

func (m *Mapper) SourceText(source string) (string, bool)

SourceText returns the original TypeScript source for a mapped source name, used to render code frames.

type Option

type Option func(*config)

Option configures TypeScript transpilation for a Provider / WithTypeScript.

func DisableAST

func DisableAST() Option

DisableAST turns off the direct TypeScript-AST -> gojs-AST module frontend, so every TypeScript module is transpiled to JavaScript text and re-parsed (the original behavior). By default a Provider lowers TypeScript modules straight to the gojs AST — skipping the text emit + re-parse — and falls back to the text path per module for anything the lowerer does not yet handle. Use this to force the text path everywhere (for debugging, or to compare the two paths).

func Permissive

func Permissive() Option

Permissive transpiles TypeScript even when it has syntax errors (matching ts.transpileModule) instead of rejecting it. The default is strict: malformed TypeScript is reported as an error rather than run.

type UnsupportedNodeError

type UnsupportedNodeError struct {
	Kind string
	Msg  string
}

UnsupportedNodeError reports a TypeScript AST node kind that the lowerer does not yet translate. A caller can treat it as a signal to fall back to transpile-to-text plus the gojs parser.

func (*UnsupportedNodeError) Error

func (e *UnsupportedNodeError) Error() string

type UnsupportedSyntaxError

type UnsupportedSyntaxError struct {
	Feature  string // human-readable name, e.g. "JSX" or "decorators"
	FileName string
}

UnsupportedSyntaxError reports TypeScript syntax that gojs deliberately does not run. gojs is an embedded, syscall-firewalled scripting engine — not a build tool — so frontend-only features that would need a code transform (lowering JSX elements to factory calls, desugaring decorators) are out of scope. The isolatedModules transpiler PRESERVES such syntax verbatim into JavaScript, which the gojs parser then rejects with a confusing low-level message; detecting it up front turns that into a clear, actionable error.

func (*UnsupportedSyntaxError) Error

func (e *UnsupportedSyntaxError) Error() string