typescript

README

This package provides a thin wrapper around goja (a native Javascript runtime for Go). There are no direct dependencies besides goja, and testify (for testing only). This package supports the following features:

• Typescript compilation and evaluation.
• A context-aware evaluation API to support cancellation.
• AMD-style modules using the built-in Almond module loader.
• Custom Typescript version registration with built-in support for versions 3.8.3, 3.9.9, 4.1.2, 4.1.3, 4.1.4, 4.1.5, 4.2.2, 4.2.3, 4.2.4, and 4.7.2.
• 90%+ test coverage

Installation

go get github.com/clarkmcc/go-typescript

Examples

• Transpile Typescript
• Transpile and Evaluate Typescript
• AMD Modules
• Context Cancellation

Documentation

Index

• func Evaluate(src io.Reader, opts ...EvaluateOptionFunc) (goja.Value, error)
• func EvaluateCtx(ctx context.Context, src io.Reader, opts ...EvaluateOptionFunc) (result goja.Value, err error)
• func Transpile(reader io.Reader, opts ...TranspileOptionFunc) (string, error)
• func TranspileCtx(ctx context.Context, script io.Reader, opts ...TranspileOptionFunc) (string, error)
• func TranspileString(script string, opts ...TranspileOptionFunc) (string, error)
• type Config
  • func NewDefaultConfig() *Config
  • func (c *Config) Initialize() error
• type EvaluateConfig
  • func (cfg *EvaluateConfig) ApplyDefaults()
  • func (cfg *EvaluateConfig) HasEvaluateBefore() bool
• type EvaluateOptionFunc
  • func WithAlmondModuleLoader() EvaluateOptionFunc
  • func WithEvaluateBefore(sources ...io.Reader) EvaluateOptionFunc
  • func WithEvaluationRuntime(runtime *goja.Runtime) EvaluateOptionFunc
  • func WithScriptHook(hook func(script string) (string, error)) EvaluateOptionFunc
  • func WithScriptPreTranspileHook(hook func(script string) (string, error)) EvaluateOptionFunc
  • func WithTranspile() EvaluateOptionFunc
  • func WithTranspileOptions(opts ...TranspileOptionFunc) EvaluateOptionFunc
• type TranspileOptionFunc
  • func WithCompileOptions(options map[string]interface{}) TranspileOptionFunc
  • func WithModuleName(name string) TranspileOptionFunc
  • func WithPreventCancellation() TranspileOptionFunc
  • func WithRuntime(runtime *goja.Runtime) TranspileOptionFunc
  • func WithTypescriptSource(src string) TranspileOptionFunc
  • func WithVersion(tag string) TranspileOptionFunc

Functions

func Evaluate

func Evaluate(src io.Reader, opts ...EvaluateOptionFunc) (goja.Value, error)

Evaluate calls EvaluateCtx using the default background context

func EvaluateCtx

func EvaluateCtx(ctx context.Context, src io.Reader, opts ...EvaluateOptionFunc) (result goja.Value, err error)

EvaluateCtx evaluates the provided src using the specified options and returns the goja value result or an error.

func Transpile

func Transpile(reader io.Reader, opts ...TranspileOptionFunc) (string, error)

Transpile transpiles the bytes read from reader using the provided config and options

func TranspileCtx

func TranspileCtx(ctx context.Context, script io.Reader, opts ...TranspileOptionFunc) (string, error)

TranspileCtx compiles the bytes read from script using the provided context. Note that due to a limitation in goja, context cancellation only works while in JavaScript code, it does not interrupt native Go functions.

func TranspileString

func TranspileString(script string, opts ...TranspileOptionFunc) (string, error)

TranspileString compiles the provided typescript string and returns the

Types

type Config

type Config struct {
	CompileOptions   map[string]interface{}
	TypescriptSource *goja.Program
	Runtime          *goja.Runtime

	// If a module is exported by the typescript compiler, this is the name the module will be called
	ModuleName string

	// Verbose enables built-in verbose logging for debugging purposes.
	Verbose bool

	// PreventCancellation indicates that the transpiler should not handle context cancellation. This
	// should be used when external runtimes are configured AND cancellation is handled by those runtimes.
	PreventCancellation bool
	// contains filtered or unexported fields
}

Config defines the behavior of the typescript compiler.

func NewDefaultConfig

func NewDefaultConfig() *Config

NewDefaultConfig creates a new instance of the Config struct with default values and the latest typescript source code.s

func (*Config) Initialize

func (c *Config) Initialize() error

type EvaluateConfig

type EvaluateConfig struct {
	// EvaluateBefore are sequentially evaluated in the Javascript runtime before evaluating the provided script.
	EvaluateBefore []io.Reader
	// ScriptHooks are called after transpiling (if applicable) with the script that will be evaluated immediately
	// before evaluation. If an error is returned from any of these functions, the evaluation process is aborted.
	// The script hook can make modifications and return them to the script if necessary.
	ScriptHooks []func(string) (string, error)
	// ScriptPreTranspileHooks are called before transpiling (if applicable) with the script that will be evaluated
	ScriptPreTranspileHooks []func(string) (string, error)
	// Transpile indicates whether the script should be transpiled before its evaluated in the runtime.
	Transpile bool
	// TranspileOptions are options passed directly to the transpiler if applicable
	TranspileOptions []TranspileOptionFunc
	// Runtime is the goja runtime used for script execution. If not specified, it defaults to an empty runtime
	Runtime *goja.Runtime
}

func (*EvaluateConfig) ApplyDefaults

func (cfg *EvaluateConfig) ApplyDefaults()

ApplyDefaults applies defaults to the configuration and is called automatically before the config is used

func (*EvaluateConfig) HasEvaluateBefore

func (cfg *EvaluateConfig) HasEvaluateBefore() bool

type EvaluateOptionFunc

type EvaluateOptionFunc func(cfg *EvaluateConfig)

func WithAlmondModuleLoader

func WithAlmondModuleLoader() EvaluateOptionFunc

WithAlmondModuleLoader adds the almond module loader to the list of scripts that should be evaluated first

func WithEvaluateBefore

func WithEvaluateBefore(sources ...io.Reader) EvaluateOptionFunc

WithEvaluateBefore adds scripts that should be evaluated before evaluating the provided script. Each provided script is evaluated in the order that it's provided.

func WithEvaluationRuntime

func WithEvaluationRuntime(runtime *goja.Runtime) EvaluateOptionFunc

WithEvaluationRuntime allows callers to use their own runtimes with the evaluator.

func WithScriptHook

func WithScriptHook(hook func(script string) (string, error)) EvaluateOptionFunc

WithScriptHook adds a script hook that should be evaluated immediately before the actual script evaluation

func WithScriptPreTranspileHook

func WithScriptPreTranspileHook(hook func(script string) (string, error)) EvaluateOptionFunc

WithScriptPreTranspileHook adds a script hook that should be evaluated immediately before transpiling the script

func WithTranspile

func WithTranspile() EvaluateOptionFunc

WithTranspile indicates whether the provided script should be transpiled before it is evaluated. This does not mean that all the evaluate before's will be transpiled as well, only the src provided to EvaluateCtx will be transpiled

func WithTranspileOptions

func WithTranspileOptions(opts ...TranspileOptionFunc) EvaluateOptionFunc

WithTranspileOptions adds options to be passed to the transpiler if the transpiler is applicable

type TranspileOptionFunc

type TranspileOptionFunc func(*Config)

TranspileOptionFunc allows for easy chaining of pre-built config modifiers such as WithVersion.

func WithCompileOptions

func WithCompileOptions(options map[string]interface{}) TranspileOptionFunc

WithCompileOptions sets the compile options that will be passed to the typescript compiler.

func WithModuleName

func WithModuleName(name string) TranspileOptionFunc

WithModuleName determines the module name applied to the typescript module if applicable. This is only needed to customize the module name if the typescript module mode is AMD or SystemJS.

func WithPreventCancellation

func WithPreventCancellation() TranspileOptionFunc

WithPreventCancellation prevents the transpiler runtime from handling its own context cancellation.

func WithRuntime

func WithRuntime(runtime *goja.Runtime) TranspileOptionFunc

WithRuntime allows you to over-ride the default runtime

func WithTypescriptSource

func WithTypescriptSource(src string) TranspileOptionFunc

WithTypescriptSource configures a Typescript source from the provided typescript source string which is compiled by goja when the config is initialized. This function will panic if the Typescript source is invalid.

func WithVersion

func WithVersion(tag string) TranspileOptionFunc

WithVersion loads the provided tagged typescript source from the default registry