IdeaLingua RPC & Domain Modeling Language

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

  • Share & publish APIs and data models in a common concise format
  • Create idiomatic API clients and servers for any programming language.
  • Allow remote calls to services given their public API definitions.
  • Abstract away details such as the network protocol or the serialization format.
  • Save users from the brittleness of 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="com.github.pshirshov.izumi.r2:idealingua-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
coursier launch -E '*:*' -r $S_REPOSITORY -r $R_REPOSITORY $COMPILER -- -i testproject

cd testproject

# compile Scala and Typescript projects using all the defaults
coursier launch -E '*:*' -r S_REPOSITORY -r $R_REPOSITORY $COMPILER -- typescript scala go csharp

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

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

Pet Store Example

See izumi-petstore for samples in Scala, TypeScript, Go, C# and other languages.

Installation

Using SBT Plugin

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

val izumi_version = "0.8.0-SNAPSHOT"
addSbtPlugin("com.github.pshirshov.izumi.r2" % "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
coursier bootstrap com.github.pshirshov.izumi.r2:idealingua-compiler_2.12:0.8.0-SNAPSHOT -o idlc

./idlc --help

To install development snapshot:

# install snapshot
coursier bootstrap -r https://oss.sonatype.org/content/repositories/snapshots/ com.github.pshirshov.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:

scalacOptions += "-Ypartial-unification"

resolvers += Resolver.sonatypeRepo("releases")

addCompilerPlugin("org.spire-math" % "kind-projector" % "0.9.8" cross CrossVersion.binary)

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

0.8.0*