goagen js

This package provides a goa generator for a modern javascript client module. This module enabels calling the API actions and varidate these parameters using goa design definition.

Generated JS code are using

• ES 2015
• fetch API (using whatwg-fetch library)
• Promise API

You need to compile using babel, webpack, or other tool. This compilation is a standard way on the modern JavaScript era.

Presentation Slide: https://speakerdeck.com/shirou/generate-better-javascript-from-goa-design

Status

Very alpha. you can not use in the production.

• handling JS and goa kind difference.
• array is not work
• required is not work
• re-thinking about validate() calling interface. Is this easy to use or not?
• support Flowtype and TypeScript

How to generate JS from your design

At first, you have to do go get

% go get github.com/shirou/goagen_js

Then, you can goagen gen with your design.

% goagen gen --pkg-path=github.com/shirou/goagen_js -d github.com/some/your/great/design

These two files are generated under js directory.

• js/api_request.js
• js/api_validator.js

How to use API

Invoking API

In the api_request.js, each API function is generated and you can use just normal invokation with Promise.

import * as api from "./api_request.js";

// This API is invoked with query parameter.
// Query parameter should be passed as object.
api.FooBar(payload).then((response) => {
  if (response.status !== 200){
    console.log("error", response.status);
  }
  return response.json();
});


// This API is invoked with Path Param and POST payload
// To use this API, passing PathParam and JSON payload as object.
// This API request to /v2/:fooID/:barType
api.FooParam(fooID, barType, payload).then((response) => {
  if (response.status !== 200){
    console.log("error", response.status);
  }
  return response.json();
});

Validation

In the api_validation.js, there are many rules for each APIs and a validate function.

import * as v from "./api_validator.js";

// validate payload
console.log(v.validate(v.FooBarGet.payload, {
  id: 1,
  too_large_int: 99999,
}));

// validate Path Params
console.log(v.validate(v.FooParamPost.fooID, 99999));

This validate function is used in api_request.js. Also you can use to validate before request, for example Form Validation.

Type Anotaion

If flow or type is specified with --target option, type anotation and definition files are generated.

goagen gen --pkg-path=github.com/shirou/goagen_js -d github.com/shirou/goagen_js/example/design -- --target flow

or

goagen gen --pkg-path=github.com/shirou/goagen_js -d github.com/shirou/goagen_js/example/design -- --target type --genout ts
# genout is used to specify output directory name

Then, all of your methods are type anotated like this.

export function UserCreate(userID: number, payload: UserCreatePayload): Promise<UserCreateMedia> {

   ...
}

Payload are defined on api.d.ts file. This is typescript example

declare namespace UserCreatePayload {
  age: number;
  email: string;
  sex: ["male","female","other"];
  name: string;
}

LICENSE

MIT License