webrpc-gen CLI v2: Templates API v0.7.0 (#119)

* Exploring Templates functions API

* Implement "dict", "set" and "get" dictionary funcs for templates

This will help us define type mapping in templates

* Re-add some v0.6.0 functions for now

* Refactor dict function, so we can pass it down to sub-templates

* Add type helper funcmaps

* Implement isBaseType function

* Bring back some obsolete functions to keep generators v0.6.0 working

* make diff

* Fix the tests for now

* Fix go.mod after git cherry-pick

* Pass variables to templates via CLI -Flags, add error/fatal funcmaps

* Remove gofmt/goimports for now

* Implement printfStderr and exit funcs

* Move VERSION to gen/ package, expose it as {{.WebrpcGenVersion}}

* Expose {{.WebrpcTarget}} and {{.WebrpcGenCLI}}

* Remove generator specific tests

Each generator repo should be testing the schema/output on its own

* Improve and document the template variables

* Support old -client, -server and -pkg flags

* Remove bunch of golang-specific funcmaps

* Fix tests

* Remove go-specific funcmaps for method inputs/outputs/arguments

* Resolve rebase

* Print "custom" target in case of local dir

* Remove more go-specific funcmaps; rename "first" to "coalesce"

* Gen: Remove all Go-spefific funcmaps/code

* Remove last go-specific funcmaps

* README: Table of generators

* Remove "indent" and rename "stderrPrintf"

* webrpc-gen: Return early when writing to stdout

* webrpc-gen: Print fatal errors to stderr

Otherwise the errors potentially ended up in the generated output file.

* Execute "main" template as the required generator entrypoint

* Add documentation about generator templates

* Generator docs: Document schema object and add TOC

* Document template functions

* Implement minVersion function

* Markdown: Escape column character in a table row

* Document requiring webrpc-gen version from templates

* Improve error message by naming the template after its target

* Collect flags in its own function

* Implement "default" function

* Add "in" function, remove "str" function and gofmt

* Implement ternary, split, first, last functions

* Remove JavaScript-specific template functions

* Finalize template functions for webrpc schema types

* Remove last generic or TS-specific template functions

* Update template functions docs

* Update README & examples with new webrpc-gen targets

* Bring back goimport/gofmt for golang targets

* PR feedback: Use Go 1.16+

* webrpc-gen CLI: Use v0.7.0 as an example target

* Use os.WriteFile() instead of ioutil.WriteFile()

* Improve isGolangTarget() so it works with local templates too

* webrpc-gen -fmt=false: disable automatic code formatting

* Lowercase all template option CLI flags, print target -help

* Lowercase all generator options, update docs

* Regenerate examples: Apply new DO NOT EDIT comment

.github/workflows/ci.yml

@@ -33,4 +33,4 @@ jobs:
       - name: Regenerate examples
         run: make generate
       - name: Git diff of regenerated examples
-        run: git diff --color --ignore-all-space --ignore-blank-lines --exit-code
+        run: make diff

Makefile

@@ -44,6 +44,9 @@ generate:
 dep:
 	@export GO111MODULE=on && go mod tidy
 
+diff:
+	git diff --color --ignore-all-space --ignore-blank-lines --exit-code
+
 dep-upgrade-all:
 	@GO111MODULE=on go get -u
 	@$(MAKE) dep

README.md

@@ -10,12 +10,14 @@ strongly-typed Web services and never having to write an API client library agai
 Under the hood, webrpc is a Web service meta-protocol, schema and code-generator tool for
 simplifying the development of backend services for modern Web applications.
 
-Current code-generation language targets:
-* [Go](https://github.com/webrpc/gen-golang)
-* [Typescript](https://github.com/webrpc/gen-typescript)
-* [Javascript](https://github.com/webrpc/gen-javascript)
-* .. contribute more! they're just templates
+| Generator                                              | Description           | Schema | Client | Server |
+|--------------------------------------------------------|-----------------------|--------|--------|--------|
+| [golang](https://github.com/webrpc/gen-golang)         | Go 1.16+              | v1     | ✅     | ✅     |
+| [typescript](https://github.com/webrpc/gen-typescript) | TypeScript            | v1     | ✅     | ✅     |
+| [javascript](https://github.com/webrpc/gen-javascript) | JavaScript (ES6)      | v1     | ✅     | ✅     |
+| [openapi](https://github.com/webrpc/gen-openapi)       | OpenAPI 3.x (Swagger) | v1     | ✅ [*](https://github.com/swagger-api/swagger-codegen#overview) | ✅ [*](https://github.com/swagger-api/swagger-codegen#overview) |
 
+..contribute more! [webrpc generators](./gen/) are just Go templates (similar to [Hugo](https://gohugo.io/templates/) or [Helm](https://helm.sh/docs/chart_best_practices/templates/)).
 
 ## Quick example
 
@@ -53,7 +55,7 @@ source code for your target language.
 For example, to generate webrpc server+client code -- run:
 
 ```
-bin/webrpc-gen -schema=example.ridl -target=go -pkg=main -server -client -out=./example.gen.go
+bin/webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go
 ```
 
 and see the generated `./example.gen.go` file of types, server and client in Go. This is essentially
@@ -152,8 +154,8 @@ Future goals/work:
     * for earlier versions: `go get -u github.com/webrpc/webrpc/cmd/webrpc-gen`  
 2. Write+design a [webrpc schema file](./_examples/golang-basics/example.ridl) for your Web service
 3. Run the code-generator to create your server interface and client, ie.
-  * `webrpc-gen -schema=example.ridl -target=go -pkg=service -server -client -out=./service/proto.gen.go`
-  * `webrpc-gen -schema=example.ridl -target=ts -pkg=client -client -out=./web/client.ts`
+  * `webrpc-gen -schema=example.ridl -target=golang -pkg=service -server -client -out=./service/proto.gen.go`
+  * `webrpc-gen -schema=example.ridl -target=typescript -client -out=./web/client.ts`
 4. Implement the handlers for your server -- of course, it can't guess the server logic :)
 
 another option is to copy the [hello-webrpc](./_examples/hello-webrpc) example, and adapt for your own webapp and server.

_examples/golang-basics/Makefile

@@ -2,7 +2,7 @@ all:
 	@echo "please read Makefile source or README to see available commands"
 
 generate:
-	webrpc-gen -schema=example.ridl -target=go -pkg=main -server -client -out=./example.gen.go
+	webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go
 
 dev-generate:
 	../../bin/webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go

_examples/golang-basics/README.md

@@ -16,15 +16,15 @@ to your service
 4. From the inputs and outputs for the function definitions, start writing the "messages"
 section of the data types needed in your program.
 5. Run the code generator to build the server and client:
-  * `webrpc-gen -schema=example.ridl -target=go -pkg=main -server -client -out=./example.gen.go`
-  * or...   * `webrpc-gen -schema=example.webrpc.json -target=go -pkg=main -server -client -out=./example.gen.go`
+  * `webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go`
+  * or...   * `webrpc-gen -schema=example.webrpc.json -target=golang -pkg=main -server -client -out=./example.gen.go`
   * however, in this example we put it inside a `go:generate`, so you can run `go generate .`
 6. Write your server ([./main.go](./main.go)) and implement the `ExampleServiceRPC` interface type
 that was created by the code generator, and located in the [gen'd file](./example.gen.go).
 7. Enjoy!
 
 Next steps, you can generate a Typescript client by running:
-* `webrpc-gen -schema=example.ridl -target=ts -pkg=example -client -out=./example-client.ts`
+* `webrpc-gen -schema=example.ridl -target=typescript -client -out=./example-client.ts`
 * check out the [hello-webrpc](../hello-webrpc) for an example with a Webapp client talking to a webrpc backend
 
 

_examples/golang-basics/main.go

@@ -1,4 +1,4 @@
-//go:generate webrpc-gen -schema=example.ridl -target=go -pkg=main -server -client -out=./example.gen.go
+//go:generate webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go
 package main
 
 import (

_examples/golang-imports/main.go

@@ -1,4 +1,4 @@
-//go:generate webrpc-gen -schema=./proto/api.ridl -target=go -pkg=main -server -client -out=./api.gen.go
+//go:generate webrpc-gen -schema=./proto/api.ridl -target=golang -pkg=main -server -client -out=./api.gen.go
 package main
 
 import (

_examples/golang-nodejs/Makefile

@@ -2,8 +2,8 @@ all:
 	@echo "please read Makefile source or README to see available commands"
 
 generate:
-	webrpc-gen -schema=example.webrpc.json -target=go -pkg=main -server -out=./server/server.gen.go
-	webrpc-gen -schema=example.webrpc.json -target=js -client -out=./client/client.gen.mjs
+	webrpc-gen -schema=example.webrpc.json -target=golang -pkg=main -server -out=./server/server.gen.go
+	webrpc-gen -schema=example.webrpc.json -target=javascript -client -out=./client/client.gen.mjs
 
 run-server:
 	go run ./server

_examples/golang-nodejs/client/client.gen.mjs

@@ -1,7 +1,8 @@
 // example  v0.0.1 33aa93c6d912046df938c7f94cef36d3a30679fa
 // --
-// This file has been generated by https://github.com/webrpc/webrpc using gen/javascript
-// Do not edit by hand. Update your webrpc schema and re-generate.
+// Code generated by webrpc-gen@v0.7.0 with javascript generator. DO NOT EDIT.
+//
+// webrpc-gen -schema=example.webrpc.json -target=javascript -client -out=./client/client.gen.mjs
 
 // WebRPC description and code-gen version
 export const WebRPCVersion = "v1"
@@ -12,7 +13,6 @@ export const WebRPCSchemaVersion = " v0.0.1"
 // Schema hash generated from your RIDL schema
 export const WebRPCSchemaHash = "33aa93c6d912046df938c7f94cef36d3a30679fa"
 
-
 //
 // Types
 //

_examples/hello-webrpc-ts/Makefile

@@ -7,10 +7,10 @@ tools:
 generate: generate-server generate-client
 
 generate-server:
-	webrpc-gen -schema=hello-api.ridl -target=go -pkg=main -server -out=./server/hello_api.gen.go
+	webrpc-gen -schema=hello-api.ridl -target=golang -pkg=main -server -out=./server/hello_api.gen.go
 
 generate-client:
-	webrpc-gen -schema=hello-api.ridl -target=ts -client -out=./webapp/src/client.gen.ts
+	webrpc-gen -schema=hello-api.ridl -target=typescript -client -out=./webapp/src/client.gen.ts
 
 bootstrap:
 	rm -rf webapp/node_modules

_examples/hello-webrpc-ts/webapp/src/client.gen.ts

@@ -1,8 +1,9 @@
 /* eslint-disable */
 // hello-webrpc v1.0.0 5ace0c3aa305e464d6a2c180f43e8876be34e155
 // --
-// This file has been generated by https://github.com/webrpc/webrpc using gen/typescript
-// Do not edit by hand. Update your webrpc schema and re-generate.
+// Code generated by webrpc-gen@v0.7.0 with typescript generator. DO NOT EDIT.
+//
+// webrpc-gen -schema=hello-api.ridl -target=typescript -client -out=./webapp/src/client.gen.ts
 
 // WebRPC description and code-gen version
 export const WebRPCVersion = "v1"
@@ -13,7 +14,6 @@ export const WebRPCSchemaVersion = "v1.0.0"
 // Schema hash generated from your RIDL schema
 export const WebRPCSchemaHash = "5ace0c3aa305e464d6a2c180f43e8876be34e155"
 
-
 //
 // Types
 //
@@ -89,6 +89,7 @@ export class ExampleService implements ExampleService {
       ).then((res) => {
       return buildResponse(res).then(_data => {
         return {
+
           status: <boolean>(_data.status)
         }
       })
@@ -101,6 +102,7 @@ export class ExampleService implements ExampleService {
       createHTTPRequest(args, headers)).then((res) => {
       return buildResponse(res).then(_data => {
         return {
+
           user: <User>(_data.user)
         }
       })
@@ -113,6 +115,7 @@ export class ExampleService implements ExampleService {
       createHTTPRequest(args, headers)).then((res) => {
       return buildResponse(res).then(_data => {
         return {
+
           page: <Page>(_data.page), 
           users: <Array<User>>(_data.users)
         }

_examples/hello-webrpc/Makefile

@@ -7,10 +7,10 @@ tools:
 generate: generate-server generate-client
 
 generate-server:
-	webrpc-gen -schema=hello-api.ridl -target=go -pkg=main -server -out=./server/hello_api.gen.go
+	webrpc-gen -schema=hello-api.ridl -target=golang -pkg=main -server -out=./server/hello_api.gen.go
 
 generate-client:
-	webrpc-gen -schema=hello-api.ridl -target=js -extra=noexports -client -out=./webapp/client.gen.js
+	webrpc-gen -schema=hello-api.ridl -target=javascript -exports=false -client -out=./webapp/client.gen.js
 
 run-server:
 	go run ./server

_examples/hello-webrpc/webapp/client.gen.js

@@ -1,7 +1,8 @@
 // hello-webrpc v1.0.0 d12378d7d88e036c2e5f779db475e7144b638b26
 // --
-// This file has been generated by https://github.com/webrpc/webrpc using gen/javascript
-// Do not edit by hand. Update your webrpc schema and re-generate.
+// Code generated by webrpc-gen@v0.7.0 with javascript generator. DO NOT EDIT.
+//
+// webrpc-gen -schema=hello-api.ridl -target=javascript -exports=false -client -out=./webapp/client.gen.js
 
 // WebRPC description and code-gen version
 export const WebRPCVersion = "v1"
@@ -12,7 +13,6 @@ export const WebRPCSchemaVersion = "v1.0.0"
 // Schema hash generated from your RIDL schema
 export const WebRPCSchemaHash = "d12378d7d88e036c2e5f779db475e7144b638b26"
 
-
 //
 // Types
 //

_examples/node-ts/Makefile

@@ -7,8 +7,8 @@ bootstrap:
 	cd webapp && yarn
 
 generate:
-	webrpc-gen -schema=service.ridl -target=ts -server -out=./server/server.gen.ts
-	webrpc-gen -schema=service.ridl -target=ts -client -out=./webapp/client.gen.ts
+	webrpc-gen -schema=service.ridl -target=typescript -server -out=./server/server.gen.ts
+	webrpc-gen -schema=service.ridl -target=typescript -client -out=./webapp/client.gen.ts
 
 run-server:
 	yarn --cwd ./server start

_examples/node-ts/README.md

@@ -21,7 +21,7 @@ Visit http://localhost:4444 !
 The cool thing about webrpc and other schema-driven rpc libraries (like grpc), is that you can
 generate a Go client for this node server just by running:
 
-`webrpc-gen -schema=service.ridl -target=go -pkg=proto -client -out=./proto/client.gen.go`
+`webrpc-gen -schema=service.ridl -target=golang -pkg=proto -client -out=./proto/client.gen.go`
 
 and tada, your Go programs now have full type definitions and network communication to the node
 server!

_examples/node-ts/server/server.gen.ts

@@ -1,8 +1,9 @@
 /* eslint-disable */
 // node-ts v1.0.0 ecee5cfb3e360bc0bc632e78556b19a2c58d4e25
 // --
-// This file has been generated by https://github.com/webrpc/webrpc using gen/typescript
-// Do not edit by hand. Update your webrpc schema and re-generate.
+// Code generated by webrpc-gen@v0.7.0 with typescript generator. DO NOT EDIT.
+//
+// webrpc-gen -schema=service.ridl -target=typescript -server -out=./server/server.gen.ts
 
 // WebRPC description and code-gen version
 export const WebRPCVersion = "v1"
@@ -13,7 +14,6 @@ export const WebRPCSchemaVersion = "v1.0.0"
 // Schema hash generated from your RIDL schema
 export const WebRPCSchemaHash = "ecee5cfb3e360bc0bc632e78556b19a2c58d4e25"
 
-
 //
 // Types
 //

_examples/node-ts/webapp/client.gen.ts

@@ -1,8 +1,9 @@
 /* eslint-disable */
 // node-ts v1.0.0 ecee5cfb3e360bc0bc632e78556b19a2c58d4e25
 // --
-// This file has been generated by https://github.com/webrpc/webrpc using gen/typescript
-// Do not edit by hand. Update your webrpc schema and re-generate.
+// Code generated by webrpc-gen@v0.7.0 with typescript generator. DO NOT EDIT.
+//
+// webrpc-gen -schema=service.ridl -target=typescript -client -out=./webapp/client.gen.ts
 
 // WebRPC description and code-gen version
 export const WebRPCVersion = "v1"
@@ -13,7 +14,6 @@ export const WebRPCSchemaVersion = "v1.0.0"
 // Schema hash generated from your RIDL schema
 export const WebRPCSchemaHash = "ecee5cfb3e360bc0bc632e78556b19a2c58d4e25"
 
-
 //
 // Types
 //
@@ -81,6 +81,7 @@ export class ExampleService implements ExampleService {
       ).then((res) => {
       return buildResponse(res).then(_data => {
         return {
+
           status: <boolean>(_data.status)
         }
       })
@@ -93,6 +94,7 @@ export class ExampleService implements ExampleService {
       createHTTPRequest(args, headers)).then((res) => {
       return buildResponse(res).then(_data => {
         return {
+
           code: <number>(_data.code), 
           user: <User>(_data.user)
         }