mike-lischke/java2typescript

A Node.js tool to convert Java source code to Typescript

Summary

java2typescript is a Node.js tool that converts Java source code into TypeScript. It takes a Java package root as input, preserves the folder structure, and rewrites each .java file as a .ts file. The project relies on the ANTLR4 Java grammar and supports language features up to Java 11.

What it is useful for

This converter helps teams migrate Java code to TypeScript or maintain a parallel TypeScript implementation of a Java library. Because it preserves the directory layout, it fits into existing build pipelines that expect one TypeScript file per Java source file.

The tool also supports iterative workflows. If an engineer fixes a generated file manually, they can add /* java2ts: keep */ as the first line. On subsequent runs, the converter parses the original Java file for symbol resolution but leaves the hand-edited TypeScript file untouched.

How engineers can use it

The README documents two main workflows.

1. Command line interface: Install the package locally with npm i java2typescript and add a script to package.json:

   "scripts": {
     "java2ts": "java2ts config.json"
   }
   

   Running npm run java2ts executes the conversion using the provided configuration file. A global install (npm i -g java2typescript) allows running the java2ts command from any directory.

2. Programmatic API: Import the JavaToTypescriptConverter class, supply an IConverterConfiguration object, and start the process:

   const converter = new JavaToTypescriptConverter({
     packageRoot: "../path/to/java/root",
   });
   await converter.startConversion();
   

Engineers should consult doc/configuration.md for the full set of options and the java2ts-examples repository for working setups.

Documented limitations to expect:

• Conversions are rarely error-free and manual cleanup is expected.
• TypeScript does not auto-initialize variables like Java; for example, new Array<T>() leaves indices undefined until you call array.fill().
• TypeScript auto-boxing only works for built-in types. Converting a string literal where java.lang.String is expected fails and must be adjusted by hand.
• Circular dependencies behave differently in TypeScript, and explicit this() constructor calls are not supported.
• Generated code often violates standard TypeScript linter rules. The configuration allows injecting prefix text, such as lint suppressions, via configuration.options.prefix.