📃 docs: Add Tutorial 01: Run TypeScript

README.md

@@ -65,7 +65,7 @@ function add(a, b) {
 
 ## Docs
 
-* Tutorials (TODO)
+* [Tutorials](docs/tutorial/)
 * [Release Notes](docs/RELEASE_NOTES.md)
 
 ## License

build.gradle.kts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+import org.gradle.internal.os.OperatingSystem
+
 object Config {
     const val GROUP_ID = "com.caoccao.javet"
     const val NAME = "swc4j"
@@ -45,6 +47,10 @@ object Config {
     }
 
     object Projects {
+        const val JAVET = "com.caoccao.javet:javet:${Versions.JAVET}"
+        const val JAVET_LINUX_ARM64 = "com.caoccao.javet:javet-linux-arm64:${Versions.JAVET}"
+        const val JAVET_MACOS = "com.caoccao.javet:javet-macos:${Versions.JAVET}"
+
         // https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-api
         const val JUNIT_JUPITER_API = "org.junit.jupiter:junit-jupiter-api:${Versions.JUNIT}"
 
@@ -57,8 +63,9 @@ object Config {
 
     object Versions {
         const val JAVA_VERSION = "1.8"
-        const val SWC4J = "0.1.0"
+        const val JAVET = "3.0.4"
         const val JUNIT = "5.10.1"
+        const val SWC4J = "0.1.0"
     }
 }
 
@@ -85,6 +92,15 @@ java {
 }
 
 dependencies {
+    val os = OperatingSystem.current()
+    val cpuArch = System.getProperty("os.arch")
+    if (os.isMacOsX) {
+        testImplementation(Config.Projects.JAVET_MACOS)
+    } else if (os.isLinux && (cpuArch == "aarch64" || cpuArch == "arm64")) {
+        testImplementation(Config.Projects.JAVET_LINUX_ARM64)
+    } else {
+        testImplementation(Config.Projects.JAVET)
+    }
     testImplementation(Config.Projects.JUNIT_JUPITER_API)
     testImplementation(Config.Projects.JUNIT_JUPITER_PARAMS)
     testRuntimeOnly(Config.Projects.JUNIT_JUPITER_ENGINE)

docs/tutorials/README.md

@@ -0,0 +1,3 @@
+# Tutorials
+
+* [Tutorial 01: Run TypeScript](tutorial_01_run_typescript.md)

docs/tutorials/tutorial_01_run_typescript.md

@@ -0,0 +1,127 @@
+# Tutorial 01: Run TypeScript
+
+In this tutorial, we are going to learn the follows.
+
+* Transpile a TypeScript code snippet into a JavaScript one.
+* Execute the transpiled JavaScript code in Javet.
+* Generate a separate source map.
+
+## Preparation
+
+* Follow the [instructions](../../) to add swc4j to your project.
+* Follow the [instructions](https://github.com/caoccao/Javet) to add Javet to your project.
+
+## Transpile from TypeScript to JavaScript
+
+* Create a simple Java application with the code as follows.
+
+```java
+// Create an instance of swc4j.
+Swc4j swc4j = new Swc4j();
+// Prepare a simple TypeScript code snippet.
+String code = "function add(a:number, b:number) { return a+b; }";
+// Prepare a script name.
+String specifier = "file:///abc.ts";
+// Prepare an option with script name and media type.
+Swc4jTranspileOptions options = new Swc4jTranspileOptions()
+        .setSpecifier(specifier)
+        .setMediaType(Swc4jMediaType.TypeScript);
+// Transpile the code.
+Swc4jTranspileOutput output = swc4j.transpile(code, options);
+// Print the transpiled code.
+System.out.println("/*********************************************");
+System.out.println("      The transpiled code is as follows.");
+System.out.println("*********************************************/");
+System.out.println(output.getCode());
+```
+
+* The output is as follows. As you can see, the TypeScript code is transpiled into JavaScript code with the source map inlined.
+
+```js
+/*********************************************
+      The transpiled code is as follows.
+*********************************************/
+function add(a, b) {
+  return a + b;
+}
+//# sourceMappingURL=data:application/json;base64,...
+```
+
+## Execute the Code in Javet
+
+* Append the following code to that Java application.
+
+```java
+// Run the code in Javet.
+System.out.println("/*********************************************");
+System.out.println("   The transpiled code is executed in Javet.");
+System.out.println("*********************************************/");
+try (V8Runtime v8Runtime = V8Host.getV8Instance().createV8Runtime()) {
+    v8Runtime.getExecutor(output.getCode()).executeVoid();
+    System.out.println("1 + 2 = " +
+            v8Runtime.getGlobalObject().invokeInteger(
+                    "add", 1, 2));
+}
+```
+
+* The output is as follows. As you can see, the JavaScript code is executed in Javet successfully.
+
+```js
+/*********************************************
+   The transpiled code is executed in Javet.
+*********************************************/
+1 + 2 = 3
+```
+
+## Generate a Separate Source Map
+
+You may want to generate a separate source map as the inline source map sometimes only slows down the script execution a little bit and a separate source map file can be useful in other cases. Yes, it's so easy to do so in swc4j.
+
+* Append the following code to that Java application.
+
+```java
+// Remove the inline source map.
+options.setInlineSourceMap(false).setSourceMap(true);
+output = swc4j.transpile(code, options);
+// Print the transpiled code.
+System.out.println("/*********************************************");
+System.out.println("      The transpiled code is as follows.");
+System.out.println("*********************************************/");
+System.out.println(output.getCode());
+System.out.println("/*********************************************");
+System.out.println("   The transpiled source map is as follows.");
+System.out.println("*********************************************/");
+System.out.println(output.getSourceMap());
+```
+
+* The output is as follows. As you can see, the source map is not inlined. Note: The actual source map is a minified Json string. The output below shows a beautified Json string for better readability.
+
+```js
+/*********************************************
+      The transpiled code is as follows.
+*********************************************/
+function add(a, b) {
+  return a + b;
+}
+
+/*********************************************
+   The transpiled source map is as follows.
+*********************************************/
+{
+    "version": 3,
+    "sources": [
+        "file:///abc.ts"
+    ],
+    "sourcesContent": [
+        "function add(a:number, b:number) { return a+b; }"
+    ],
+    "names": [],
+    "mappings": "AAAA,SAAS,IAAI,CAAQ,EAAE,CAAQ;EAAI,OAAO,IAAE;AAAG"
+}
+```
+
+## Conclusion
+
+In this tutorial we've learned how to transpile from TypeScript to JavaScript, execute the code in Javet, and get a separated source map.
+
+The source code of this tutorial is at [here](../../src/test/java/com/caoccao/javet/swc4j/tutorials/Tutorial01RunTypeScript.java).

src/test/java/com/caoccao/javet/swc4j/tutorials/Tutorial01RunTypeScript.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2024. caoccao.com Sam Cao
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.caoccao.javet.swc4j.tutorials;
+
+import com.caoccao.javet.exceptions.JavetException;
+import com.caoccao.javet.interop.V8Host;
+import com.caoccao.javet.interop.V8Runtime;
+import com.caoccao.javet.swc4j.Swc4j;
+import com.caoccao.javet.swc4j.enums.Swc4jMediaType;
+import com.caoccao.javet.swc4j.exceptions.Swc4jCoreException;
+import com.caoccao.javet.swc4j.options.Swc4jTranspileOptions;
+import com.caoccao.javet.swc4j.outputs.Swc4jTranspileOutput;
+
+public class Tutorial01RunTypeScript {
+    public static void main(String[] args) throws Swc4jCoreException, JavetException {
+        // Create an instance of swc4j.
+        Swc4j swc4j = new Swc4j();
+        // Prepare a simple TypeScript code snippet.
+        String code = "function add(a:number, b:number) { return a+b; }";
+        // Prepare a script name.
+        String specifier = "file:///abc.ts";
+        // Prepare an option with script name and media type.
+        Swc4jTranspileOptions options = new Swc4jTranspileOptions()
+                .setSpecifier(specifier)
+                .setMediaType(Swc4jMediaType.TypeScript);
+        // Transpile the code.
+        Swc4jTranspileOutput output = swc4j.transpile(code, options);
+        // Print the transpiled code.
+        System.out.println("/*********************************************");
+        System.out.println("      The transpiled code is as follows.");
+        System.out.println("*********************************************/");
+        System.out.println(output.getCode());
+        // Run the code in Javet.
+        System.out.println("/*********************************************");
+        System.out.println("   The transpiled code is executed in Javet.");
+        System.out.println("*********************************************/");
+        try (V8Runtime v8Runtime = V8Host.getV8Instance().createV8Runtime()) {
+            v8Runtime.getExecutor(output.getCode()).executeVoid();
+            System.out.println("1 + 2 = " +
+                    v8Runtime.getGlobalObject().invokeInteger(
+                            "add", 1, 2));
+        }
+        // Remove the inline source map.
+        options.setInlineSourceMap(false).setSourceMap(true);
+        output = swc4j.transpile(code, options);
+        // Print the transpiled code.
+        System.out.println("/*********************************************");
+        System.out.println("      The transpiled code is as follows.");
+        System.out.println("*********************************************/");
+        System.out.println(output.getCode());
+        System.out.println("/*********************************************");
+        System.out.println("   The transpiled source map is as follows.");
+        System.out.println("*********************************************/");
+        System.out.println(output.getSourceMap());
+    }
+}