README.md

JSONError for Golang

This package is for adding some structure to your error messages. This makes error-handling, debugging and diagnosis for all your Go projects a lot more elegant and simpler. Use it wherever error type is required.

It utilizes the fact that built-in type error is actually an interface.

The package also contains the ErrorCollection struct which allows for accumulation of multiple errors. It is safe to use from multiple concurrent goroutines unlike other comparable packages.

Please Star this package so I can add it to awesome-go.

Refer to documentation on GoDoc because the information below is a small subset of all the features.

Install

go get -u github.com/pjebs/jsonerror

Optional - if you want to output JSON formatted error messages (e.g. for REST API):

go get -u gopkg.in/unrolled/render.v1

Prehistoric Usage - Using Go Standard Library

import (
	"errors"
	"fmt"
)

func main() {
	err := errors.New("emit macho dwarf: elf header corrupted")
	if err != nil {
		fmt.Print(err)
	}
}

//Or alternatively

panic(errors.New("failed"))

Using this package instead

import (
	errors "github.com/pjebs/jsonerror" //aliased for ease of usage
	"math"                              //For realSquareRoot() example function below
)

//EXAMPLE 1 - Creating a JE Struct

err := errors.New(1, "Square root of negative number is prohibited", "Please make number positive or zero") //Domain is optional and not included here

//Or  
err := errors.New(1, "Square root of negative number is prohibited", "Please make number positive or zero", "com.github.pjebs.jsonerror")

//EXAMPLE 2 - Practical Example

//Custom function
func realSquareRoot(n float64) (float64, error) {
	if n < 0 {
		return 0, errors.New(1, "Square root of negative number is prohibited", "Please make number positive or zero")
	} else {
		return math.Sqrt(n), nil
	}
}

//A function that uses realSquareRoot
func main() {

	s, err := realSquareRoot(12.0)
	if err != nil {
		if err.(errors.JE).Code == 1 {
			//Square root of negative number
		} else {
			//Unknown error
		}
		return
	}

	//s is Valid answer
}

Methods

func New(code int, error string, message string, domain ...string) JE

code int - Error code. Arbitrary and set by fiat. Different types of errors should have an unique error code in your project.

error string - A standard description of the error code.

message string - A more detailed description that may be customized for the particular circumstances. May also provide extra information.

domain ...string - Optional It allows you to distinguish between same error codes. Only 1 domain string is allowed.

func (this JE) Render() map[string]string {

Formats JE (JSONError) struct so it can be used by gopkg.in/unrolled/render.v1 package to generate JSON output.

Output JSON formatted error message (i.e. REST API Server response)

import (
	"github.com/codegangsta/negroni" //Using Negroni (https://github.com/codegangsta/negroni)
	errors "github.com/pjebs/jsonerror"
	"gopkg.in/unrolled/render.v1"
	"net/http"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {

		err := errors.New(12, "Unauthorized Access", "Please log in first to access this site")

    	r := render.New(render.Options{})
		r.JSON(w, http.StatusUnauthorized, err.Render())
		return
  	
  	})

  	n := negroni.Classic()
  	n.UseHandler(mux)
  	n.Run(":3000")
}

For the above example, the web server will respond with a HTTP Status Code of 401 (Status Unauthorized), Content-Type as application/json and a JSON response:

{"code":"12","error":"Unauthorized Access","message":"Please log in first to access this site"}

FAQ

What is the domain parameter?

The domain parameter is optional. It allows you to distinguish between same error codes. That way different packages (or different parts of your own project) can use the same error codes (for different purposes) and still be differentiated by the domain identifier.

NB: The domain parameter is not outputted by Render() (for generating JSON formatted output)

How do I use this package?

When you want to return an error (e.g. from a function), just return a JE struct. See the example code above.

Or you can use it with panic().

panic(jsonerror.New(1, "error", "message"))

What are the error codes?

You make them up for your particular project! By fiat, you arbitrarily set each error code to mean a different type of error.

Final Notes

If you found this package useful, please Star it on github. Feel free to fork or provide pull requests. Any bug reports will be warmly received.

PJ Engineering and Business Solutions Pty. Ltd.