buildo / metarpheus-tcomb

metarpheus to JS / tcomb

metarpheus-tcomb

generate a tcomb domain model interpreting metarpheus output

install

npm i metarpheus-tcomb

usage

metarpheus-tcomb --config=path/to/config/file

usage from node

metarpheusTcomb = require('metarpheus-tcomb')

model = metarpheusTcomb({
  intermRep: {}, // a valid interm. rep. object (output from metarpheus),
  config: {
    // more configuration (see below)
  }
}).model

configuration

An example config file is in config.js

By default, the model is generated into ./model.js

export default {
  intermRepIn: 'test/fixtures/metarpheus-interm-rep.json',
  modelPrelude: `import t from 'tcomb';
`,
  apiPrelude: `import t from 'tcomb';
import * as m from './model';
`,
  apiModelPrefix: 'm.',
  modelOut: 'model.js',
  apiOut: 'api.js',
  overrides: {
    Date: (_, { prefix = '' }) => `${prefix}MyDateType`
  }
};

Note: for node usage, you shouldn't provide intermRepIn, modelOut, apiOut via config. You should pass intermRep as a separate parameter, and the model and api outputs are returned by the node api function.

Example

Here's the gist:

sealed trait UserType extends CaseEnum
object UserType {
  case object User extends UserType
  case object SuperUser extends UserType
}

/**
  * A user
  *
  * @param _id ID of the user
  * @param username username
  * @param userType type of the user
  */
case class User(
  _id: Id[User],
  username: String,
  userType: UserType)


val route = {
  pathPrefix("users") {
    (get & pathCommit(`:Id`[User]) /**
      get user by id
    */) (returns[User].ctrlu(userController.findById)) ~
    (post & pathCommit("logout") /**
      performs the logout for the currently logged user
    */) (returns[Unit].ctrlu(userController.logout))
  }
}

becomes...

export const UserType = t.enums.of([
  'User',
  'SuperUser'
], 'UserType');

export const User = t.struct({
  _id: Id/*Id[User]*/, // ID of the user
  username: t.String, // username
  userType: UserType // type of the user
}, 'User');

export const api = [
  // GET /users/ : get user by id
  {
    method: 'get',
    name: ['userController', 'findById'],
    authenticated: true,
    returnType: User,
    route: (...routeParams) => ['users', routeParams[0]].join('/'),
    routeParamTypes: [Id/*Id[User]*/],
    params: {}
  },
  // POST /users/logout : performs the logout for the currently logged user
  {
    method: 'post',
    name: ['userController', 'logout'],
    authenticated: true,
    returnType: User,
    route: (...routeParams) => ['users', 'logout'].join('/'),
    routeParamTypes: [],
    params: {}
  }
];

TODO

the api part should probably be moved to its own repo, left it here for simplicity for now.

apiOut config param is thus optional

metarpheus-tcomb's Issues

fail if there are duplicate models (..or apis)

requirements

as per title, we could fail at "generation time", instead of brutally at runtime:

see also https://twitter.com/CodeWisdom/status/841720334130765824

specs

{optional: describe technical specs to implement this feature, if not obvious}

misc

{optional: other useful info}

support `inBody` option for `params`

requirements

in order to support wiro-output metarpheus interm-rep:

• there can be multiple body param types
• body params are listed among other params and marked with the inBody: true flag

specs

collect body params and generate an handy interface({ ...bodyParams })

misc

{optional: other useful info}

Skip model generation when overridden

Currently we are generating the tcomb define/declare couple also for models that are overridden.

This is a problem when overriding a model that is also present in the metarpheus model.

E.g. suppose you have a model in scala

case class UserId(value: Int)

Metarpheus generates a UserId model.

Now suppose you want to override it in metarpheus-tcomb:

{
  overrides: {
    UserId: () => 't.Integer'
  }
}

This causes UserId to be overridden everywhere, but theUserId` model is declared anyway.

The worst part, is that the overridden value is used in the definition, so it crashes at runtime.

t.declare(UserId);
UserId.define(t.Integer); // BOOM!

My proposal is to skip generating the tcomb model for overrides.

/cc @giogonzo @dhinus @FrancescoCioria

Upgrade to babel^6

requirements

• upgrade babel to ^6
• upgrade .babelrc syntax
• move all babel-deps to devDependencies (only babel for now)

specs

{optional: describe technical specs to implement this feature, if not obvious}

misc

{optional: other useful info}

add support for TreeSet

requirements

transform TreeSet(x) into t.list(x).

should handle TreeSet of standard types too (TreeSet(String) into TreeSet(t.String))

specs

copy List logic

misc

{optional: other useful info}

sort generated models and routes

It should do no harm, so no configuration option

display route params types names

problem

routeParamTypes: [t.String, t.String]

doesn't document properly the route params

solution

routeParamTypes: [{ workcellGroupType: t.String }, { workcellSerialNumber: t.String }]

Why is babel-cli a peerDependency?

It doesn't seem necessary, am I wrong?

Map Unit to t.Nil

requirements

Unit should be mapped to t.Nil

make node integration simpler

requirements

• avoid structs, prefer interfaces where possible
  • I'm talking about metarpheus-tcomb code, not the generated models ;)
• export a single node entry point

specs

{optional: describe technical specs to implement this feature, if not obvious}

misc

{optional: other useful info}

add `renameModel` option

in order to be able to customize the generated tcomb struct/enum name

e.g. you might want to refer to a scala API_Model as just Model in js

add a few more standard types

requirements

as per #6 + Set and Map

specs

{optional: describe technical specs to implement this feature, if not obvious}

misc

{optional: other useful info}

update "body type" format as per new metarpheus

requirements

see buildo/metarpheus#52

we should handle here both the "old style" (a single body type) and the new one (0+ inBody: true params among params)

specs

{optional: describe technical specs to implement this feature, if not obvious}

misc

{optional: other useful info}

Tcomb annotations for requests body are not generated

description

It seems that metarpheus-tcomb is not generating any annotation for the body to pass to POST (and maybe also to GET) calls.
This make it difficult for frontenders to know which data they should pass to the call, beside the obvious pain point of losing any typechecking on passed data.

how to reproduce

Look at workcellGroupConfigurationController_updateWorkcellGroupConfigurations in AliniQ's generated api.js as an example. There is no info about the structure of data to pass to the call.

specs

• It seems that metarpheus is generating this kind of info, but metarpheus-tcomb is ignoring it.

misc

{optional: other useful info}