Overhauled README.md and added examples directory

Author: clarkmcc

README.md

@@ -1,84 +1,18 @@
-# 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.
+![](assets/banner.png)
 
-Feel free to contribute. This package is fresh and may experience some changes before it's first tagged release.
+This package provides a thin wrapper around [goja](https://github.com/dop251/goja) (a native Javascript runtime for Go). There are no direct dependencies besides goja, and [testify](https://github.com/stretchr/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](https://github.com/requirejs/almond).
+* 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
 
-## Transpiling Examples
-### Transpile Strings
-```go
-output, err := typescript.TranspileString("let a: number = 10;", nil)
-// output: var a = 10;
-```
+## Installation
 
-### Transpile Reader
-```go
-output, err := typescript.Transpile(reader, nil)
-```
+    go get github.com/clarkmcc/go-typescript
 
-### 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, typescript.WithCompileOptions(map[string]interface{}{
-    "module": "none",
-    "strict": true,
-}))
-```
-
-### Custom Typescript Version
-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, typescript.WithVersion("v4.2.2"))
-}
-```
-
-### Custom Typescript Source
-You may want to use a custom typescript version.
-
-```go
-func main() {
-    output, err := typescript.TranspileString("let a:number = 10;", 
-    	WithTypescriptSource("/* source code for typescript*/"))
-}
-```
-
-## 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
-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)))
-```
+## Examples
+* [Transpile Typescript](examples/typescript_evaluate_test.go)
+* [Transpile and Evaluate Typescript](examples/typescript_evaluate_test.go)
+* [AMD Modules](examples/typescript_amd_modules_test.go)
+* [Context Cancellation](examples/typescript_context_test.go)

assets/banner.png

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"github.com/dop251/goja"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"io"
 	"strings"
@@ -94,6 +95,17 @@ func TestEvaluateCtx(t *testing.T) {
 			}))
 		require.NoError(t, err)
 	})
+
+	t.Run("pre-transpile hook", func(t *testing.T) {
+		s1 := "let a: number = 10"
+		_, err := Evaluate(strings.NewReader(s1),
+			WithTranspile(),
+			WithScriptPreTranspileHook(func(s2 string) (string, error) {
+				assert.Equal(t, s1, s2)
+				return s2, nil
+			}))
+		assert.NoError(t, err)
+	})
 }
 
 var _ io.Reader = &failingReader{}

evaluate_test.go

@@ -0,0 +1,6 @@
+define("myModule", ["exports"], function (exports) {
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.multiply = void 0;
+    var multiply = function (a, b) { return a * b; };
+    exports.multiply = multiply;
+});

examples/javascript-example-module.js

@@ -0,0 +1,14 @@
+class Person {
+    name: string;
+
+    constructor(name: string) {
+        this.name = name
+    }
+
+    public greet(): string {
+        return `Hello ${this.name}!`
+    }
+}
+
+const me = new Person("John Doe")
+me.greet()

examples/typescript-example.ts

@@ -0,0 +1,23 @@
+package examples
+
+import (
+	_ "embed"
+	"fmt"
+	"github.com/clarkmcc/go-typescript"
+	"strings"
+)
+
+//go:embed javascript-example-module.js
+var module string
+
+func ExampleTypescriptAMDModule() {
+	result, err := typescript.Evaluate(strings.NewReader(`import { multiply } from 'myModule'; multiply(5, 5)`),
+		typescript.WithTranspile(),
+		typescript.WithAlmondModuleLoader(),
+		typescript.WithEvaluateBefore(strings.NewReader(module)))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(result.ToInteger())
+	// Output:25
+}

examples/typescript_amd_modules_test.go

@@ -0,0 +1,24 @@
+package examples
+
+import (
+	"context"
+	_ "embed"
+	"fmt"
+	"github.com/clarkmcc/go-typescript"
+	"strings"
+)
+
+//go:embed typescript-example.ts
+var script3 string
+
+func ExampleContext() {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := typescript.TranspileCtx(ctx, strings.NewReader(script3))
+	if err == nil {
+		panic("expected error")
+	}
+	fmt.Println(err)
+	// Output:running typescript compiler: context halt at <eval>:1:1(0)
+}

examples/typescript_context_test.go

@@ -0,0 +1,21 @@
+package examples
+
+import (
+	_ "embed"
+	"fmt"
+	"github.com/clarkmcc/go-typescript"
+	"strings"
+)
+
+//go:embed typescript-example.ts
+var script2 string
+
+func ExampleTypescriptEvaluate() {
+	// Transpile the typescript and return evaluated result
+	result, err := typescript.Evaluate(strings.NewReader(script2), typescript.WithTranspile())
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(result.String())
+	// Output:Hello John Doe!
+}

examples/typescript_evaluate_test.go

@@ -0,0 +1,36 @@
+package examples
+
+import (
+	_ "embed"
+	"fmt"
+	"github.com/clarkmcc/go-typescript"
+	"strings"
+)
+
+//go:embed typescript-example.ts
+var script1 string
+
+var expected = `
+var Person = /** @class */ (function () {
+    function Person(name) {
+        this.name = name;
+    }
+    Person.prototype.greet = function () {
+        return "Hello ".concat(this.name, "!");
+    };
+    return Person;
+}());
+var me = new Person("John Doe");
+me.greet();`
+
+func ExampleTranspile() {
+	// Only transpile the typescript and return transpiled Javascript, don't evaluate
+	transpiled, err := typescript.TranspileString(script1)
+	if err != nil {
+		panic(err)
+	}
+	if transpiled != expected {
+		panic("unexpected transpile result")
+	}
+	fmt.Println(strings.TrimSpace(transpiled))
+}

examples/typescript_test.go

@@ -0,0 +1,20 @@
+// Copyright (C) 2022 Print Tracker, LLC - All Rights Reserved
+//
+// Unauthorized copying of this file, via any medium is strictly prohibited
+// as this source code is proprietary and confidential. Dissemination of this
+// information or reproduction of this material is strictly forbidden unless
+// prior written permission is obtained from Print Tracker, LLC.
+
+package utils
+
+import (
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestRandomString(t *testing.T) {
+	s1 := RandomString()
+	assert.Len(t, s1, 24)
+	s2 := RandomString()
+	assert.NotEqual(t, s1, s2)
+}