IdeaLingua

IdeaLingua is an RPC framework & Domain Modeling Language, it’s purpose is to:

  • Share & publish APIs and data models in a common concise format
  • Allow remote calls to services given their public API definitions.
  • Create idiomatic API clients and servers for all programming languages – currently Scala, TypeScript, C# & Go.
  • Support frontend-to-backend and backend-to-frontend calls (ala push notifications, via buzzer definitions)
  • Abstract away details such as the network protocol or the serialization format.
  • Save developers from untyped and brittle REST.

User Service Example

package user.api

enum Gender = Male | Female

id EntityID {
  uuid: uuid
}

mixin Entity {
  id: EntityID
}

mixin Person {
  name: str
  surname: str
  gender: Gender
}

data User {
  & Entity
  + Person
  password: str
}

data PublicUser {
  + User
  - password: str
}

adt Result = Success | Failure

data Success {
  message: str
}

data Failure {
  code: int8
}

service UserService {
  def saveUser(user: User): Result
  def findUserByName(name: str): list[PublicUser] | Failure
}

Quick start

You may use our preconfigured Docker environment to experiment with Izumi IDL compiler:

docker run -ti --rm septimalmind/izumi-env

Then try this snippet:

export COMPILER="io.7mind.izumi:idealingua-v1-compiler_2.12:$izumi.version$"
export S_REPOSITORY=https://oss.sonatype.org/content/repositories/snapshots
export R_REPOSITORY=https://oss.sonatype.org/content/repositories/releases

# create sample project in `testproject` directory
cs launch -r $S_REPOSITORY -r $R_REPOSITORY $COMPILER -- :init testproject

cd testproject

# compile Scala and Typescript projects using all the defaults
cs launch -r $S_REPOSITORY -r $R_REPOSITORY $COMPILER -- :scala :typescript

# Run SBT on generated Scala project
pushd .
cd target/scala
sbt package
popd

# Run tsc on generated Typescript project
pushd .
cd target/typescript
yarn install
tsc
popd

apt install -y mc
mc

Example Project

See idealingua-example for examples for Scala, TypeScript, Go, C# and other languages.

Installation

Using SBT Plugin

Add the following to your project/plugins.sbt file:

val izumi_version = "1.2.17-SNAPSHOT"
addSbtPlugin("io.7mind.izumi" % "sbt-idealingua" % izumi_version)

Place your domain definitions into /src/main/izumi directory, then enable the plugin for that project. For the generated code to compile, you will also need to add dependencies on the Idealingua RTS modules:

val izumi = prop

izumiProject
  .enablePlugins(IdealinguaPlugin)
  .settings(
    libraryDependencies ++= Seq(
        Izumi.R.idealingua_model
      , Izumi.R.idealingua_runtime_rpc
      , Izumi.R.idealingua_runtime_rpc_http4s
      , Izumi.R.idealingua_runtime_rpc_circe
    )
  )

You can depend on the code generated by Idealinguain in your other Scala projects:

project.dependsOn(izumiProject)

Using the standalone compiler

The compiler is built as an uberjar and published to Maven Central.

The preferred way to install the compiler is via coursier

To install current release version:

# install release executable
cs bootstrap izumi.r2:idealingua-compiler_2.12:1.2.17-SNAPSHOT -o idlc

./idlc --help

To install development snapshot:

# install snapshot
cs bootstrap -r https://oss.sonatype.org/content/repositories/snapshots/ izumi.r2:idealingua-compiler_2.12:0.7.0-SNAPSHOT -o idlc

./idlc --help

Commandline examples:

# compile sources in ./src and output generated code to ./target/scala and ./target/typescript
# all compiler plugins for Scala and TypeScript are enabled by * pattern

./idlc -s src -t target -L scala=* -L typescript=*

# compile with `AnyValExtension` compiler plugin for Scala disabled

./idlc -s src -t target -L scala=-AnyvalExtension -L typescript=*

Scala http4s Transport

Most likely you’ll need to use Kind Projector and enable partial unification:

addCompilerPlugin("org.typelevel" % "kind-projector" % "0.11.0" cross CrossVersion.full)

// Only for Scala 2.12, not required on 2.13+
scalacOptions += "-Ypartial-unification"

You may find the test suite for the http4s backend here.

1.2.17*