tserrgen

README

tserrgen

Go package for automated code generation of error handling code for the tserr error handling package. It reads error definitions from a JSON configuration file and generates the corresponding error types, API functions, and comprehensive test functions.

• Automated: Generates complete error handling implementation from simple JSON configuration
• Tested: Automatically generates comprehensive test functions for all error cases
• Configuration-driven: Simple JSON schema makes it easy to define and extend errors
• Dependencies: Minimal dependencies and only depends on Go Standard Library, lpcode, tsfio and tserr

Usage

In the Go app, the package is imported with

import "github.com/thorsphere/tserrgen"

The package provides automated code generation for error handling based on JSON configuration files. The primary entry point is the Generate function, which orchestrates the entire code generation process.

Basic Workflow

The generation process follows these steps:

1. Define your errors in a JSON configuration file (e.g., tserr.json)
2. Call Generate with the path to your configuration file
3. The generator produces three Go files:

• tserr_messages.go - Error message constants
• tserr_api.go - Error constructor functions
• tserr_api_test.go - Comprehensive test functions

func main() {
    if err := tserrgen.Generate(tsfio.Filename("tserr.json")); err != nil {
        log.Fatal(err)
    }
}

Configuration File

The JSON configuration file defines error definitions with their names, comments, HTTP status codes, message templates, and parameters:

{
  "tserr": {
    "path": "../tserr",
    "version": "1.0.0",
    "errors": [
      {
        "name": "NotFound",
        "comment": "NotFound is returned when a resource is not found.",
        "code": "404",
        "message": "resource %v not found",
        "param": [
          {
            "name": "resource",
            "comment": "the resource type that was not found",
            "type": "string"
          }
        ]
      }
    ]
  }
}

Generated code

For each error definition, the generator creates:

• Error message structs in tserr_messages.go - Constants holding error metadata
• Constructor functions in tserr_api.go - Type-safe functions for creating errors
• Test functions in tserr_api_test.go - Comprehensive tests validating error generation

Core Function

func Generate(fn tsfio.Filename) error

The Generate function reads the JSON configuration file and generates the complete error handling implementation. It validates the configuration and returns an error if any step fails.

Requirements

Generated files require header and footer template files with suffixes .header and .footer to be present in the target directory. These files contain package declarations, imports, and other boilerplate that should appear at the beginning or end of generated files:

• tserr_messages.go.header and tserr_messages.go.footer
• tserr_api.go.header and tserr_api.go.footer
• tserr_api_test.go.header and tserr_api_test.go.footer

Example

package main

import (
    "github.com/thorsphere/tserrgen"
)

func main() {
    if e := tserrgen.Generate("tserr.json"); e != nil {
        panic(e)
    }
}

Limitations

The generator does not validate or check for non-printable characters in the tserr.json configuration file. When defining error names, comments, or message templates, ensure that your JSON configuration contains only printable characters. Non-printable characters (control characters, invalid UTF-8 sequences, etc.) may result in corrupted or invalid generated error messages.

Recommendation: Use only standard ASCII printable characters and valid UTF-8 sequences in your configuration file.

Links

Godoc

Go Report Card

Open Source Insights

Documentation

Overview

Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Package tserrgen provides automated Go code generation for the tserr package. It reads error definitions from a JSON configuration file and generates the corresponding error types, API functions, and test functions.

The main component is:

• Generate: The primary entry point that orchestrates the entire code generation process. It reads a JSON configuration file, parses the error definitions, and invokes the appropriate generators for messages, API functions, and tests.

The JSON configuration file defines errors with their names, comments, HTTP status codes, message templates, and parameter specifications. The generator creates type-safe, testable error functions that integrate seamlessly with the tserr error handling package.

The package leverages lpcode for programmatic code generation, tsfio for file operations, and tserr for consistent error handling throughout the generation process.

Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Index

• func Generate(fn tsfio.Filename) error

Functions

func Generate

func Generate(fn tsfio.Filename) error

Generate generates Go code for the tserr package based on the error definitions provided in the JSON file specified by fn. It reads the JSON file, unmarshals it into a tserrconfig struct, and then generates the necessary Go code for error messages and API functions. If any error occurs during this process, it returns an error with details about the operation that failed.