From 2d6083c3b07bc3171f3a4ba3806a4518494719b8 Mon Sep 17 00:00:00 2001 From: Sam Cao Date: Tue, 12 Mar 2024 12:27:01 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=83=20docs:=20Add=20Tutorial=2001:=20R?= =?UTF-8?q?un=20TypeScript?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- build.gradle.kts | 18 ++- docs/tutorials/README.md | 3 + docs/tutorials/tutorial_01_run_typescript.md | 127 ++++++++++++++++++ .../tutorials/Tutorial01RunTypeScript.java | 70 ++++++++++ 5 files changed, 218 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/README.md create mode 100644 docs/tutorials/tutorial_01_run_typescript.md create mode 100644 src/test/java/com/caoccao/javet/swc4j/tutorials/Tutorial01RunTypeScript.java diff --git a/README.md b/README.md index 15a9cc02..df491cd4 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ function add(a, b) { ## Docs -* Tutorials (TODO) +* [Tutorials](docs/tutorial/) * [Release Notes](docs/RELEASE_NOTES.md) ## License diff --git a/build.gradle.kts b/build.gradle.kts index 4631ca1c..58ca08b0 100644 --- a/build.gradle.kts +++ b/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) diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 00000000..f23647fa --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,3 @@ +# Tutorials + +* [Tutorial 01: Run TypeScript](tutorial_01_run_typescript.md) diff --git a/docs/tutorials/tutorial_01_run_typescript.md b/docs/tutorials/tutorial_01_run_typescript.md new file mode 100644 index 00000000..b44cb896 --- /dev/null +++ b/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). diff --git a/src/test/java/com/caoccao/javet/swc4j/tutorials/Tutorial01RunTypeScript.java b/src/test/java/com/caoccao/javet/swc4j/tutorials/Tutorial01RunTypeScript.java new file mode 100644 index 00000000..19e75b3c --- /dev/null +++ b/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()); + } +}