scala2ts-core

Transform your Scala classes, objects and traits into Typescript interfaces and classes

This repository contains the parser, transpiler and renderer for the scala2ts project. It's primary purpose is to act as a Scala compiler plugin that, on compile, will produce equivalent Typescript typings for your desired Scala classes, objects and traits.

SBT

It is highly recommended that if you use SBT for your project, to use the scala2ts-sbt SBT plugin instead of this project directly. It streamlines adding the compiler plugin and configuring it for you.

You can find the project here. If you dont use SBT or have a more complex build configuration, proceed below.

Support

Version	Scala
1.1.x	2.13 2.12 2.11
1.0.x	2.13 2.12 2.11

Usage

// build.sbt

lazy val yourProject = (project in file("."))
  .settings(
    autoCompilerPlugins := true,
    addCompilerPlugin("com.github.scala2ts" % "scala2ts-core" % "latestVersion"),
    scalacOptions := Seq(
      // See below for configuration options
    ) 
  )

Adding autoCompilerPlugins tells SBT to automatically include the -Xplugin scalac flag with the appropriate path to found compiler plugins.

Configuration

There are many configuration options in how and what Typescript is emitted from your Scala code. The defaults of which can be found in the com.github.scala2ts.configuration.Configuration case class. For ease of use, here is the current list of configuration options and their defaults:

Option	Flag	Multi	Type	Default	Description
Debug	-P:scala2ts:debug	no	Boolean	false	Enable debug logging
Include File	-P:scala2ts:file:includes	yes	Regex		File path to include in compilation
Exclude File	-P:scala2ts:file:excludes	yes	Regex		File path to exclude in compilation
Include Type	-P:scala2ts:type:includes	yes	Regex		Type name to include in compilation
Exclude Type	-P:scala2ts:type:excludes	yes	Regex		Type name to exclude in compilation
Prefix	-P:scala2ts:type:prefix	no	String		A prefix to use in your Typescript names (e.g. I for IInterface)
Suffix	-P:scala2ts:type:suffix	no	String		A suffix to use in your Typescript names (e.g. Data InterfaceData)
Date Mapping	-P:scala2ts:date	no	String	AsDate	How to emit Date types (options: AsDate, AsString, AsNumber)
Long & Double Mapping	-P:scala2ts:longDouble	no	String	AsString	How to emit Long(s) or Double(s) (options: AsString, AsNumber)
Sealed Trait Type Mapping	-P:scala2ts:sealedTypes	no	SealedTypesMapping	None	Emit an enum or type union for a sealed trait/class's members (options: None, AsEnum, AsUnion, AsUnionString)
Render As	-P:scala2ts:renderAs	no	RenderAs	Interface	How to render interfaces/classes
Class Discriminator	-P:scala2ts:includeDiscriminator	no	Boolean	false	Include a class property that acts as a discriminator
Discriminator Name	-P:scala2ts:discriminatorName	no	String	"type"	The name of the class discriminator property
Output Directory	-P:scala2ts:outDir	no	String		What directory to emit files to
Output File Name	-P:scala2ts:outFileName	no	String	index.d.ts	The name of the outputted Typescript file
package.json Name	-P:scala2ts:pj:name	no	String		The name to use in package.json. Note: This is the only required field to enable package.json to emit
package.json Version	-P:scala2ts:pj:name	no	String		The version to use in package.json
package.json Types	-P:scala2ts:pj:types	no	String		The path to use in the types field of package.json
package.json publishConfig Registry	-P:scala2ts:pj:registry	no	String		The url to use for an external NPM registry

Motivations

Most current Scala -> TS solutions rely on SBT, where they couple the transpile code within an SBT plugin. The way SBT operates, it has its own Scala version separate from the project its operating on. This means that these plugins can only operate on 2.10 (SBT 0.x) and 2.12 (SBT 1.x) codebases.

Why is this the case? Scala's reflection library can only operate on Scala code produced by the specific Scala version being used at the time. If I compile a 2.13 project, I cannot use the 2.12 reflection library against that code. This is where the limitations of the current SBT plugins comes to light.

This library tries to eliminate that by operating at the compiler level, where we're guaranteed binary compatibility. The SBT plugin (scala2ts-sbt) merely acts as a configuration layer for the compiler plugin.

Acknowledgments

Big thanks to the maintainers of scala-ts and Typescript-Generator projects, specifically @cchantep PR with the scala-tslibrary which was the inspiration for this project.