Scala-TS

Scala-TS is a tool which convert Scala data model types to other langages such as TypeScript (to easily integrate REST-ful Scala backends and TypeScript frontends).

See release notes

See demo (with Akka HTTP & Svelte)

Usage

Scala-TS can be used as a SBT plugin (recommended) or as a Scala compiler plugin, to perform code generation during Scala compilation.

Scala-TS is not Scala.js; Scala.js is a great tool to port Scala code to JavaScript, so it can be executed as any JS functions, whereas Scala-TS is focused on transpiling only data model types (so the frontend itself is coded in TypeScript, not in Scala).

Input Scala:

package scalats.docs

case class Incident(id: String, message: String)

Generated TypeScript:

export interface Incident {
  id: string;
  message: string;
}

// Can be used...
const incident: Incident = {
  id: 'id',
  message: 'A message'
}

See examples

More:

• How to share data model between Akka HTTP API and TypeScript Svelte frontend
  • Similar demo with idonttrustlikethat

SBT plugin

Scala-TS can be used as a SBT plugin. It can be set up by adding to project/plugins.sbt:

addSbtPlugin("io.github.scala-ts" % "sbt-scala-ts" % "0.8.0")

Additionally, the plugin can be enabled per project.

// Not enabled by default
enablePlugins(ScalatsGeneratorPlugin)

The TypeScript files are generated at compile-time.

sbt compile

By default, the TypeScript generation is executed in directory target/scala-ts/src_managed (see sourceManaged in scalatsOnCompile in configuration).

See SBT plugin settings

See SBT examples on GitHub

Compiler plugin

Scala-TS can also be configured as a Scalac compiler plugin using the following options.

• -Xplugin:/path/to/scala-ts-core.jar
• -P:scalats:configuration=/path/to/plugin.conf

The plugin.conf is a HOCON file that define the generator settings (see example.

See compiler settings

Type reference

Scala-TS can emit TypeScript for different kinds of Scala types declaration (see examples).

Scala	TypeScript
Case class	Interface
Sealed family	Interface
Enumeration	Enum
Value class	Inner value

Scala-TS support the following scalar types for the members/fields in the transpiled declaration.

Scala	TypeScript
Boolean	boolean
Byte, Double, Float, Int, Long, Short	number
BigDecimal, BigInt, BigInteger	number
String, UUID	string
Date, Instant, Timestamp	Date
LocalDate, LocalDateTime	Date
ZonedDateTime, OffsetDateTime	Date
List, Seq, Set (any collection)	ReadonlyArray
Map[K, V] (K as key type, V as value type)	{ [key: K]: V }
(A, B) (Tuple2 with A as first type)	[A, B]
Tuple3[A, B, C] (similar for other tuple types)	[A, B, C]
Either[L, R] (L on left, R on right)	L | R

Option

By default, according the setting optionToNullable, Option values are generated as omitable TypeScript fields (T | undefined) or as nullable fields.

// For Option[String]
export interface Example {
  ifOptionToNullable?: string | undefined,
  otherwise: string | nullable
}

Extensions

Additionnally to the Scala-TS SBT plugin, some extensions are provided.

idonttrustlikethat

A SBT plugin extension is provided to generate TypeScript idonttrustlikethat validators, and derived types.

This can be configured by first configuring sbt-scala-ts-idtlt to the project/plugins.sbt (instead of base sbt-scala-ts).

addSbtPlugin("io.github.scala-ts" % "sbt-scala-ts-idtlt" % 0.8.0)

Then in the build.sbt is can be configured as below.

enablePlugins(ScalatsIdtltPlugin) // Required as disabled by default

Example: Scala case class

package scalats.docs.idtlt

import java.time.LocalDate

case class Bar(
  name: String,
  age: Int,
  amount: Option[BigInt],
  updated: LocalDate,
  created: LocalDate
)

It generates the following TypeScript validators and types.

import * as idtlt from 'idonttrustlikethat';

// Validator for InterfaceDeclaration Bar
export const idtltBar = idtlt.object({
  created: idtlt.isoDate,
  updated: idtlt.isoDate,
  amount: idtlt.number.optional(),
  age: idtlt.number,
  name: idtlt.string,
});

export const idtltDiscriminatedBar = idtlt.intersection(
  idtltBar,
  idtlt.object({
    '_type': idtlt.literal('Bar')
  })
);

// Deriving TypeScript type from Bar validator
export type Bar = typeof idtltBar.T;

See demo with idonttrustlikethat