go2type

A Go to TypeScript API client generator.

Overview

go2type is a tool that generates TypeScript API clients from Go server code. It parses Go structs and handler functions, generating corresponding TypeScript types and API client functions.

The generator can produce standard query functions, React hooks, or React Query hooks based on configuration.

Features

• Generates TypeScript types from Go structs
• Creates API client functions from Go handler functions
• Supports generation of:
  • Standard query functions
  • React hooks
  • @tanstack/react-query hooks
• Customizable type mappings
• Automatically parse time.Time as Date objects
• Prettier formatting support
• Automatic configuration initialization
• Flexible header handling with support for different storage options

Installation

To install go2type, use the following command:

go install github.com/dx314/go2type@latest

Usage

go2type provides two main commands:

1. init: Initialize a new configuration file
2. generate: Generate TypeScript files based on the configuration

Initializing Configuration

To create a new configuration file, run:

go2type init

This command will:

• Check for existing Go handlers in your project
• Detect the presence of React or @tanstack/react-query
• Find Prettier in your project or system PATH
• Create a go2type.yaml file with default settings

Generating TypeScript Files

To generate TypeScript files based on your configuration, run:

go2type generate

This command will:

• Load the configuration from go2type.yaml
• Parse the specified Go packages
• Generate TypeScript types and API client functions
• Format the output using Prettier (if available)

Configuration

The go2type.yaml file contains the following fields:

auth_token: "session_token"
auth_token_storage: "localStorage"
prettier_path: "client-ui/node_modules/prettier/bin/prettier.cjs"
hooks: react-query
use_date_object: true
packages:
  - path: "internal/app"
    output_path: "client-ui/src/hooks/index.ts"
    type_mappings:
      null.String: "null | string"
      null.Bool: "null | boolean"
      uuid.UUID: "string /* uuid */"
      uuid.NullUUID: "null | string /* uuid */"

Configuration Options

• auth_token: Specifies the key used to retrieve the authentication token from the specified storage.
• auth_token_storage: Indicates where the authentication token is stored. It can be set to "localStorage" or "sessionStorage". Defaults to "localStorage".
• prettier_path: Specifies the path to the Prettier executable, used for formatting the generated TypeScript code.
• hooks: Indicates the type of hooks to generate. Options are "false", "true" (for React hooks), or "react-query".
• use_date_object: When set to true, date fields will be treated as JavaScript Date objects. Defaults to false.
• packages: Defines the Go packages to process and where to output the generated TypeScript code.
• type_mappings: Allows you to specify custom mappings from Go types to TypeScript types.

Remember to adjust the configuration according to your project's specific needs and structure.

Authentication Token

The auth_token field in the configuration specifies the key used to retrieve the authentication token from the specified storage. This token is automatically included in the headers of all API requests generated by go2type.

The auth_token_storage field determines where the authentication token is stored. It can be set to either:

• "localStorage" (default): The token will be retrieved from and stored in localStorage.
• "sessionStorage": The token will be retrieved from and stored in sessionStorage.

For example, if your configuration has:

auth_token: "session_token"
auth_token_storage: "sessionStorage"

go2type will look for a token stored under the key "session_token" in sessionStorage. The generated API calls will include this token in their headers.

If auth_token_storage is not specified, it defaults to "localStorage".

Header Handling

go2type provides flexible header handling through the @Header directive in Go handler comments. This allows you to specify the source of each header value.

The format for the @Header directive is:

@Header [source]:[HeaderName]:[StorageKey]

Where:

• [source] can be input, localStorage, or sessionStorage
• [HeaderName] is the name of the header
• [StorageKey] (optional) is the key used to retrieve the value from storage. Not relevant for input source.

If [StorageKey] is not provided, it defaults to [HeaderName].

Examples:

// @Header input:X-Custom-Header
// @Header localStorage:X-Account-ID:account_id
// @Header sessionStorage:X-Session-ID

Go Code Examples

Handler function with comments:

// @Method GET
// @Path /users/:id
// @Input GetUserInput
// @Output User
// @Header input:X-Custom-Header
// @Header localStorage:X-Auth-Token:auth_token
// @Header sessionStorage:X-Session-ID
func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    // Handler implementation
}

Go struct:

type User struct {
    ID        int       `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

License

MIT License

Copyright (c) 2024 Alex Dunmow

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss potential changes.