Evaluator with amd module support (#5)

* Added AMD-based almond module loader and evaluator that can evaluate scripts and transpile them if needed

* Allow transpiler to not use context cancellation (handle cancellation in the runtime)

* Added transpiler option for custom typescript source

* Removed examples directory and updated readme

* Added support for Typescript v4.2.4

* Added support for pre-evaluation script modifier hooks and custom evaluation runtimes

Co-authored-by: Clark McCauley <[email protected]>

Author: clarkmcc

README.md

@@ -1,10 +1,9 @@
-# Goja Typescript Transpiler
-This package provides a simple interface using [github.com/dop251/goja](github.com/dop251/goja) under the hood to allow you to transpile Typescript to Javascript in Go. This package has no direct dependencies besides testing utilities and has a 95% test coverage rate.
+# Goja Typescript Transpiler and Evaluator (with AMD module support)
+This package provides a simple interface using [github.com/dop251/goja](github.com/dop251/goja) under the hood to allow you to transpile Typescript to Javascript in Go. In addition it provides an evaluator with a built-in AMD module loader which allows you to run Typescript code against a compiled typescript bundle. This package has no direct dependencies besides testing utilities and has a 95% test coverage rate.
 
 Feel free to contribute. This package is fresh and may experience some changes before it's first tagged release.
 
-## Example
-For more examples, see the `examples/` directory of this repository
+## Transpiling Examples
 ### Transpile Strings
 ```go
 output, err := typescript.TranspileString("let a: number = 10;", nil)
@@ -19,47 +18,67 @@ output, err := typescript.Transpile(reader, nil)
 ### Custom Typescript Compile Options
 You can optionally specify alternative compiler options that are used by Typescript. Any of the options [https://www.typescriptlang.org/docs/handbook/compiler-options.html](https://www.typescriptlang.org/docs/handbook/compiler-options.html) can be added.
 ```go
-output, err = typescript.TranspileString(script, nil, typescript.WithCompileOptions(map[string]interface{}{
+output, err = typescript.TranspileString(script, typescript.WithCompileOptions(map[string]interface{}{
     "module": "none",
     "strict": true,
 }))
 ```
 
 ### Custom Typescript Version
-#### Default Registry
 You can optionally specify which typescript version you want to compile using. These versions are based on the Git tags from the Typescript repository. If you're using a version that is supported in this package, you'll need to import the version package as a side-effect and will automatically be registered to the default registry.
 ```go
 import _ "github.com/clarkmcc/go-typescript/versions/v4.2.2"
 
 func main() {
-    output, err := typescript.Transpile(reader, nil, typescript.WithVersion("v4.2.2"))
+    output, err := typescript.Transpile(reader, typescript.WithVersion("v4.2.2"))
 }
 ```
 
-#### Custom Registry
-You may want to use a custom version registry rather than the default registry.
+### Custom Typescript Source
+You may want to use a custom typescript version.
 
 ```go
-import version "github.com/clarkmcc/go-typescript/versions/v4.2.2"
-
 func main() {
-    registry := versions.NewRegistry()
-    registry.MustRegister("v4.2.3", version.Source)
-    
-    output, err := typescript.TranspileString("let a:number = 10;", &typescript.Config{
-        TypescriptSource: program,
-    })
+    output, err := typescript.TranspileString("let a:number = 10;", 
+    	WithTypescriptSource("/* source code for typescript*/"))
 }
 ```
 
-#### Custom Version
-Need a different typescript version than the tags we support in this repo? No problem, you can load your own:
+## Evaluate Examples
+### Basic Evaluation
+You can evaluate pure Javascript code with:
+
+```go
+result, err := Evaluate(strings.NewReader('var a = 10;')) // returns 10;
+```
+
+### Transpile and Evaluate
+Or you can transpile first:
 
 ```go
-program, err := goja.Compile("typescript", "<typescript source code here>", true)
-output, err := typescript.Transpile(reader, &typescript.Config{
-    CompileOptions:   map[string]interface{}{},
-    TypescriptSource: program,
-    Runtime:          goja.New(),
-})
+result, err := Evaluate(strings.NewReader('let a: number = 10;'), WithTranspile()) // returns 10;
+```
+
+### Run Script with AMD Modules
+You can load in an AMD module bundle, then execute a Typescript script with access to the modules.
+
+```go
+// This is the module we're going to import
+modules := strings.TrimSpace(`
+    define("myModule", ["exports"], function (exports, core_1) {
+        Object.defineProperty(exports, "__esModule", { value: true });
+        exports.multiply = void 0;
+        var multiply = function (a, b) { return a * b; };
+        exports.multiply = multiply;
+    });
+`)
+
+// This is the script we're going to transpile and evaluate
+script := "import { multiply } from 'myModule'; multiply(5, 5)"
+
+// Returns 25
+result, err := EvaluateCtx(context.Background(), strings.NewReader(script),
+    WithAlmondModuleLoader(),
+    WithTranspile(),
+    WithEvaluateBefore(strings.NewReader(amdModuleScript)))
 ```

config.go

@@ -5,18 +5,29 @@ import (
 	"fmt"
 	"github.com/clarkmcc/go-typescript/utils"
 	"github.com/clarkmcc/go-typescript/versions"
-	_ "github.com/clarkmcc/go-typescript/versions/v4.2.3"
+	_ "github.com/clarkmcc/go-typescript/versions/v4.2.4"
 	"github.com/dop251/goja"
 )
 
-// OptionFunc allows for easy chaining of pre-built config modifiers such as WithVersion.
-type OptionFunc func(*Config)
+// TranspileOptionFunc allows for easy chaining of pre-built config modifiers such as WithVersion.
+type TranspileOptionFunc func(*Config)
 
 // Config defines the behavior of the typescript compiler.
 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
+
 	// decoderName refers to a random generated string assigned to a function in the runtimes
 	// global scope which is analogous to atob(), or a base64 decoding function. This function
 	// is needed in the transpile process to ensure that we don't have any issues with string
@@ -49,34 +60,59 @@ func NewDefaultConfig() *Config {
 	return &Config{
 		Runtime:          goja.New(),
 		CompileOptions:   nil,
-		TypescriptSource: versions.DefaultRegistry.MustGet("v4.2.3"),
+		TypescriptSource: versions.DefaultRegistry.MustGet("v4.2.4"),
+		ModuleName:       "default",
 	}
 }
 
 // WithVersion loads the provided tagged typescript source from the default registry
-func WithVersion(tag string) OptionFunc {
+func WithVersion(tag string) TranspileOptionFunc {
 	return func(config *Config) {
 		config.TypescriptSource = versions.DefaultRegistry.MustGet(tag)
 	}
 }
 
+// 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 WithTypescriptSource(src string) TranspileOptionFunc {
+	return func(config *Config) {
+		config.TypescriptSource = goja.MustCompile("", src, true)
+	}
+}
+
 // WithCompileOptions sets the compile options that will be passed to the typescript compiler.
-func WithCompileOptions(options map[string]interface{}) OptionFunc {
+func WithCompileOptions(options map[string]interface{}) TranspileOptionFunc {
 	return func(config *Config) {
 		config.CompileOptions = options
 	}
 }
 
 // WithRuntime allows you to over-ride the default runtime
-func WithRuntime(runtime *goja.Runtime) OptionFunc {
+func WithRuntime(runtime *goja.Runtime) TranspileOptionFunc {
 	return func(config *Config) {
 		config.Runtime = runtime
 	}
 }
 
+// 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 WithModuleName(name string) TranspileOptionFunc {
+	return func(config *Config) {
+		config.ModuleName = name
+	}
+}
+
+// WithPreventCancellation prevents the transpiler runtime from handling its own context cancellation.
+func WithPreventCancellation() TranspileOptionFunc {
+	return func(config *Config) {
+		config.PreventCancellation = true
+	}
+}
+
 // withFailOnInitialize used to test a config initialization failure. This is not exported because
 // it's used only for testing.
-func withFailOnInitialize() OptionFunc {
+func withFailOnInitialize() TranspileOptionFunc {
 	return func(config *Config) {
 		config.failOnInitialize = true
 	}

config_test.go

@@ -25,58 +25,47 @@ func TestConfig_Initialize(t *testing.T) {
 
 func TestVersionLoading(t *testing.T) {
 	t.Run("v3.8.3", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v3.8.3"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v3.8.3"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v3.9.9", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v3.9.9"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v3.9.9"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.1.2", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.1.2"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.1.2"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.1.3", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.1.3"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.1.3"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.1.4", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.1.4"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.1.4"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.1.5", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.1.5"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.1.5"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.2.2", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.2.2"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.2.2"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
 	t.Run("v4.2.3", func(t *testing.T) {
-		output, err := TranspileString("let a: number = 10;", &Config{
-			TypescriptSource: versions.DefaultRegistry.MustGet("v4.2.3"),
-		})
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.2.3"))
+		require.NoError(t, err)
+		require.Equal(t, "var a = 10;", output)
+	})
+	t.Run("v4.2.4", func(t *testing.T) {
+		output, err := TranspileString("let a: number = 10;", WithVersion("v4.2.4"))
 		require.NoError(t, err)
 		require.Equal(t, "var a = 10;", output)
 	})
@@ -86,9 +75,26 @@ func TestCustomRegistry(t *testing.T) {
 	registry := versions.NewRegistry()
 	registry.MustRegister("v4.2.3", v423.Source)
 
-	output, err := TranspileString("let a: number = 10;", &Config{
-		TypescriptSource: registry.MustGet("v4.2.3"),
+	output, err := TranspileString("let a: number = 10;", func(config *Config) {
+		config.TypescriptSource = registry.MustGet("v4.2.3")
 	})
 	require.NoError(t, err)
 	require.Equal(t, "var a = 10;", output)
 }
+
+func TestWithModuleName(t *testing.T) {
+	output, err := TranspileString("let a: number = 10;",
+		WithModuleName("myModuleName"),
+		WithCompileOptions(map[string]interface{}{
+			"module": "amd",
+		}))
+	require.NoError(t, err)
+	require.Contains(t, output, "define(\"myModuleName\"")
+}
+
+func TestWithTypescriptSource(t *testing.T) {
+	output, err := TranspileString("let a: number = 10;",
+		WithTypescriptSource(v423.Source))
+	require.NoError(t, err)
+	require.Equal(t, "var a = 10;", output)
+}