README.md

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

• Developer Experience First

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:

• whatever.ext.hbs will generate whatever.ext with all proto_files as context
• {{file}}.ext.hbs will generate one file by proto_files and send the right file as context
• {{import}}.ext.hbs will generate one file by import (don't know if it's really useful but yes it's possible)
• {{file}}/{{message}}.ext.hbs will generate one file by message and send the message as context and <file> as path
• {{file}}/{{service}}/{{rpc}}.ext.hbs will generate one file by rpc with the right context and <file>/<service> as path
• ...

Helpers

Protobuf

Protobuf helpers was thought as easy to use as possible

• They are all iterators
• They can take parameters as arguments to filter by name or specific field
• Parameters can be globs for strings

{{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

• All handlebars-helpers have been included
• Better string case helpers have been added too (see here)

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