Home

Awesome

protoc-gen-hbs

🏃‍♀️ Fast Templating for Protobuf Generation with Handlebars and some Helpers

Why ?

This project aims to be the simplest way to generate api, model and whatever based on protobuf for any languages. Protobuf based generation can really improve productivity of developers, and a lot of tools already exists in that way. But, it is really painful to generate custom things or create plugin with imperative languages. This is where template languages are useful. But there is another problem. After releasing and using pbhbs, I realised that every templates I did was not maintainable and this was a mess to re-create new ones. This is why this project exists.

Philosophy

Installation

First, install protoc and yarn or npm

Then type:

yarn global add protoc-gen-hbs

or

npm install --global protoc-gen-hbs

Usage

CLI

protoc --hbs_out="[<template_dir>:]<out_dir>" [-I<proto_paths>...] <proto_files>..

Options:
  out_dir         Path where to generate output files
  templates_dir   Path where to store templates (default: ./templates)
  proto_paths     Paths where to find your protos
  proto_files     Proto files to use for generation

Templates

Paths Definition

Path definition is very free to you, all you must know is that we parse it to send the right context and create the right path to generate files.

Some examples:

Helpers

Protobuf

Protobuf helpers was thought as easy to use as possible

{{file}}
{{#file}}
  {{@name}}
{{/file}}
{{import}}
{{#import}}
include "{{@name}}.pb.h"
{{/import}}
{{package}}
// get root packages
{{#package}}
namespace {{@name}} {
  // ...
}
{{/package}}

// get all packages
{{#package recursive=true}}
namespace {{@name}} {
  // ...
}
{{/package}}

// get all packages recursively in their scope
{{#package}}
namespace {{@name}} {
  {{@recursive}}
}
{{/package}}

// filter by name
{{#package name="google*" recursive=true}}
  // {{@name}}
{{else}}
  // ...
{{/package}}
{{message}}
// Display messages name
{{#message}}
  {{@name}}
{{/message}}

// Filter by name
{{#message name="google.protobuf.Timestamp"}}
class {{@name}} extends DateTime {}
{{else}}
class {{@name}} {}
{{/message}}

// By default children will get parents name as prefix
{{#message}}
  {{@name}}
{{/message}}

// Is equal to
{{#package}}
  {{#message}}
  {{@service.name}}.{{@name}}
  {{/message}}
{{/package}}

// You can access nested message this way
{{#message}}
  {{#nested}}
    {{@name}}
  {{/nested}}
{{/message}}

// Or recursively
{{#message}}
  {{@name}}
  {{@recursive}}
{{/message}}

// Or recursively as param
{{#message recursive=true}}
  {{@name}}
{{/message}}
{{field}}
{{#message}}
  {{#field}}
    {{@name}}: {{@type}}
  {{/field}}
{{/message}}

// You can filter fields by label and/or type
{{#field label="repeated"}}
// TODO: convert type
const {{@name}}: Array<{{@type}}> = []
{{/field}}

{{#field type="string"}}
const {{@name}}: string = ''
{{/field}}

{{#field label="optional" type="number"}}
const {{@name}}: number? = undefined
{{/field}}
{{extension}}
// Work exactly like field
{{#message}}
  {{#extension}}
    {{@name}}: {{@type}}
  {{/extension}}
{{/message}}
{{enum}}
{{#enum}}
enum {{@name}} {
  {{#value}}
    {{@name}}: {{@number}}
  {{/value}}
}
{{/enum}}
{{service}}
{{#service}}
interface {{@name}} {
  // do stuff
}
{{/service}}
{{rpc}}
{{#rpc}}
  // TODO: convert input and output type
  const {{@name}} = (request: {{@input}}): Promise<{{@output}}> => {
    // do stuff
  }
{{/rpc}}

// You can filter by request/response type
{{#rpc client="unary" server="stream"}}
  // TODO: convert input and output type
  const {{@name}} = (request: {{@input}}, (response: {{@output}} => void): Promise<void>
{{/rpc}}

{{#service}}
  const {{@service.name}} = {
    {{#rpc}}
      {{@name}}: (request: {{@input}}, (response: {{@output}} => void): Promise<void>
    {{/rpc}}
  }
{{/service}}
{{option}}
// You can filter by option like this
{{#service}}
  {{#option deprecated=true}}
    // Do stuff
  {{/option}}
{{/service}}

// Or
{{#service deprecated=true}}
  // Do stuff
{{/service}}

// You can also access it directly
{{#message}}
  {{#field}}
    {{@jsonName}}
  {{/field}}
{{/message}}

Others

For helpers not related with protobuf

Contributing

Make PRs and have fun 👻

Issues

No rules, if you see anything weird, open an issue :)

Examples

See examples directory here

License

This project is licensed under Apache 2.0 - see LICENSE file for details