tserr

README

tserr

The package tserr is a simple error interface in Go. The interface provides standardized error messages of type error by function calls. Errors may contain verbs, which are provided by the function arguments.

• Simple: Without configuration, just function calls
• Easy to parse: All error messages in JSON format.
• Tested: Unit tests with high code coverage
• Dependencies: Only depends on the Go Standard Library

Usage

In the Go app, the package is imported with

import "github.com/thorstenrie/tserr"

An error is called by a specific, corresponding function call, e.g.,

err1 := tserr.NilPtr()

The output of fmt.Println(err1) is

{"error":{"id":0,"code":500,"message":"nil pointer"}}

The error message may contain verbs to be filled by arguments, e.g., with one argument:

f := "foo.txt"
err2 := tserr.NotExistent(f)

The output of fmt.Println(err2) is

{"error":{"id":2,"code":404,"message":"foo.txt does not exist"}}

A function may hold multiple arguments used for more than one verb in the error message. Multiple arguments are passed to a function as a pointer to a struct, e.g.,

err3 := tserr.NotEqualStr(&tserr.NotEqualStrArgs{X: "a", Y: "b"})

The output of fmt.Println(err3) is

{"error":{"id":6,"code":500,"message":"a does not equal b"}}

All error functions with multiple arguments first check, if the pointer to the argument struct is nil. If it is nil, the error function returns NilPtr. If the argument struct contains a field of type error, it is checked next. If the error field is nil, then the error function returns nil. Otherwise, it returns the corresponding error message.

JSON format

The error messages are fomatted in the JSON format. The root element is named "error". Each error message has an "id" which is consecutively numbered. "code" is a relating HTTP status code. "message" contains the actual pre-defined error message.

{"error":{"id":<int>,"code":<int>,"message":"<string>"}}

Example

package main

import (
	"fmt"

	"github.com/thorstenrie/tserr"
)

func main() {
	err1 := tserr.NilPtr()
	fmt.Println(err1)

	f := "foo.txt"
	err2 := tserr.NotExistent(f)
	fmt.Println(err2)

	err3 := tserr.NotEqualStr(&tserr.NotEqualStrArgs{X: "a", Y: "b"})
	fmt.Println(err3)
}

Links

Godoc

Gocover.io

Go Report Card

Open Source Insights

Documentation

Overview

Package tserr provides a simple API for standardized error messages in the JSON format.

The tserr package provides easy-to-use functions to get standardized error messages for typical errors. The error messages are fomatted in the JSON format:

{"error":{"id":<int>,"code":<int>,"message":"<string>"}}

The root element is named "error". "id" is a consecutively numbered id. "code" is a relating HTTP status code. "message" contains the actual pre-defined error message.

The error message may contain verbs to be filled by arguments. The arguments for the verbs are provided as function arguments. A function may hold one argument used as one verb in the error message. A function may hold multiple arguments used for more than one verb in the error message. Multiple arguments are passed to a function as a pointer to a struct, e.g.,

err := tserr.NotEqualStr(&tserr.NotEqualStrArgs{X: "test1", Y: "test2"})

Output with fmt.Println(err):

{"error":{"id":6,"code":500,"message":"test1 does not equal test2"}}

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

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

Index

• func Check(a *CheckArgs) error
• func Empty(f string) error
• func Equal(a *EqualArgs) error
• func Forbidden(f string) error
• func Higher(a *HigherArgs) error
• func NilFailed(op string) error
• func NilPtr() error
• func NotEqualStr(a *NotEqualStrArgs) error
• func NotExistent(f string) error
• func NotSet(f string) error
• func Op(a *OpArgs) error
• func Return(a *ReturnArgs) error
• func TypeNotMatching(a *TypeNotMatchingArgs) error
• type CheckArgs
• type EqualArgs
• type HigherArgs
• type NotEqualStrArgs
• type OpArgs
• type ReturnArgs
• type TypeNotMatchingArgs

Functions

func Check

func Check(a *CheckArgs) error

Check can be used for negative validations on an object

func Empty

func Empty(f string) error

Empty can be used if an required object is empty but not allowed to be empty, e.g., an input argument of type string. Argument f is the name of the empty object, e.g., filename

func Equal

func Equal(a *EqualArgs) error

Equal can be used if an integer fails to be equal to an expected value.

func Forbidden

func Forbidden(f string) error

Forbidden can be used if an operation on an object is forbidden Argument f is the name of the forbidden object, e.g., directory or filename

func Higher

func Higher(a *HigherArgs) error

Higher can be used if an integer fails to at least be equal or be higher than a defined lower bound.

func NilFailed

func NilFailed(op string) error

NilFailed can be used if the function implementing an operation returns nil, but an error is expected. A default use case are Test functions. Argument op is the name of the operation, e.g., ExistsFile

func NilPtr

func NilPtr() error

NilPtr just provides the error message and does not have arguments.

func NotEqualStr

func NotEqualStr(a *NotEqualStrArgs) error

NotEqualStr can be used if two strings are not equal, but expected to be equal. A default use case are Test functions.

func NotExistent

func NotExistent(f string) error

NotExistent can be used if an required object does not exist, e.g., a file. Argument f is the name of the object, e.g., filename

func NotSet

func NotSet(f string) error

NotSet can be used if an required object is not set, e.g., an environment variable. Argument f is the name of the object, e.g., the name of the environment variable

func Op

func Op(a *OpArgs) error

Op can be used for failed operations on an object

func Return

func Return(a *ReturnArgs) error

Return can be used if an operation returns an actual value, but another return value is expected. A default use case are Test functions.

func TypeNotMatching

func TypeNotMatching(a *TypeNotMatchingArgs) error

TypeNotMatching can be used if the type of an object does not match the expected type

Types

type CheckArgs

type CheckArgs struct {
	// F is the name of the object causing the failed check, e.g., a filename
	F string
	// Err is the error causing the failed check, e.g., file is a directory
	Err error
}

CheckArgs holds the required arguments for the error function Check

type EqualArgs

type EqualArgs struct {
	// Var is the name of the variable
	Var string
	// Actual is the actual value of Var
	Actual int64
	// Want is the expected value of Var.
	Want int64
}

EqualArgs holds the required arguments for the error function Higher

type HigherArgs

type HigherArgs struct {
	// Var is the name of the variable
	Var string
	// Actual is the actual value of Var
	Actual int64
	// LowerBound is the lower bound. Actual is expected to be equal or higher than LowerBound.
	LowerBound int64
}

HigherArgs holds the required arguments for the error function Higher

type NotEqualStrArgs

type NotEqualStrArgs struct {
	// X is the string not matching Y
	X string
	// Y is the string not matching X
	Y string
}

NotEqualStrArgs holds the required arguments for the error function NotEqualStr

type OpArgs

type OpArgs struct {
	// Op is the name of the failed operation, e.g., WriteStr
	Op string
	// Fn is the name of the object passed to the operation, e.g., a filename
	Fn string
	// Err is the error retrieved from the failed operation, e.g., file does not exist
	Err error
}

OpArgs holds the required arguments for the error function Op

type ReturnArgs

type ReturnArgs struct {
	// Op is the operation
	Op string
	// Actual is the actual return value returned by Op
	Actual string
	// Want is the expected return value from Op
	Want string
}

ReturnArgs holds the required arguments for the error function Return

type TypeNotMatchingArgs

type TypeNotMatchingArgs struct {
	// Act is the name of the actual type of the object, e.g., file
	Act string
	// Want is the name of the expected, wanted or required type the object should be, e.g., directory
	Want string
}

TypeNotMatchingArgs holds the required arguments for the error function TypeNotMatching