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/thorsphere/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.EqualStr(&tserr.EqualStrArgs{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. Otherwise, it returns the corresponding error message.

JSON format

The error messages are formatted 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/thorsphere/tserr"
)

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

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

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

Run in Go Playground

Output:

{"error":{"id":0,"code":500,"message":"nil pointer"}}
{"error":{"id":2,"code":404,"message":"foo.txt does not exist"}}
{"error":{"id":6,"code":400,"message":"a does not equal b"}}

Links

Godoc

Go Report Card

Open Source Insights

Documentation

Overview

Package tserr provides a small, opinionated toolkit for structured error messages in JSON format, with an HTTP-status-code-aligned code.

Each function returns an error whose string is JSON like:

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

- `id` is a package-level error identifier (incremental, `0` = nil pointer). - `code` is a related HTTP status code (e.g. 400, 404, 409, 500). - `message` is a pre-defined message template (supports fmt-style verbs).

Two patterns exist: 1. Single-arg errors via direct function params, e.g. `tserr.Empty("path")`. 2. Multi-arg errors via struct pointer args, e.g.:

err := tserr.EqualStr(&tserr.EqualStrArgs{
    Var: "name", Actual: "foo", Want: "bar",
})

If a multi-arg struct pointer is nil, `tserr.NilPtr()` is returned. Otherwise the template is formatted and wrapped as JSON.

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.

All exported error functions are implemented here, with the exception of NilPtr, which exists in a separate source file. If the function has one argument it is directly provided as function argument. If the function has more than one argument, then the arguments are provided as a struct, e.g.,

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

All error functions first check, if the pointer to the argument struct is nil. If it is nil, the error function returns NilPtr, e.g.,

if a == nil {
    return NilPtr()
}

Otherwise, it returns the corresponding error message, e.g.,

return errorf(&errmsgEqualStr, a.X, a.Y)

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.

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 AlreadyExistent(F string) error
• func Check(a *CheckArgs) error
• func Duplicate(F string) error
• func Empty(F string) error
• func Equal(a *EqualArgs) error
• func EqualStr(a *EqualStrArgs) error
• func Equalf(a *EqualfArgs) error
• func Forbidden(F string) error
• func Higher(a *HigherArgs) error
• func Locked(S string) error
• func Lower(a *LowerArgs) error
• func NilExpected(Op string) error
• func NilFailed(Op string) error
• func NilPtr() error
• func NonPrintable(F string) error
• func NotAvailable(a *NotAvailableArgs) error
• func NotEqual(a *NotEqualArgs) 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 EqualStrArgs
• type EqualfArgs
• type HigherArgs
• type LowerArgs
• type NotAvailableArgs
• type NotEqualArgs
• type OpArgs
• type ReturnArgs
• type TypeNotMatchingArgs

Functions

func AlreadyExistent

func AlreadyExistent(F string) error

AlreadyExistent can be used if a required object already exists, for example, a file, but is not expected to exist. F is the name of the object, for example, file name

func Check

func Check(a *CheckArgs) error

Check can be used for negative validations on an object.

func Duplicate

func Duplicate(F string) error

Duplicate can be used if an object already exists, but is only allowed to exist once, for example, a key. F is the name of the object which already exists, for example, the name of a key

func Empty

func Empty(F string) error

Empty can be used if a required object is empty but not allowed to be empty, for example, an input argument of type string. F is the name of the empty object, for example, filename

func Equal

func Equal(a *EqualArgs) error

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

func EqualStr

func EqualStr(a *EqualStrArgs) error

EqualStr can be used if a string fails to be equal to an expected string.

func Equalf

func Equalf(a *EqualfArgs) error

Equalf can be used if a float value is not equal to an expected value

func Forbidden

func Forbidden(F string) error

Forbidden can be used if an operation on an object is forbidden. F is the name of the forbidden object, for example, a 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 Locked

func Locked(S string) error

Locked can be used if a service is locked, for example, because it is still running. S is the name of the service which is locked

func Lower

func Lower(a *LowerArgs) error

Lower can be used if an integer fails to be lower than a defined higher bound.

func NilExpected

func NilExpected(Op string) error

NilExpected can be used if the function implementing an operation does not return nil, but nil is expected. A default use case are Test functions. Op is the name of the operation, for example, ExistsFile

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. Op is the name of the operation, for example, ExistsFile

func NilPtr

func NilPtr() error

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

func NonPrintable

func NonPrintable(F string) error

NonPrintable can be used if a string is allowed to only contain printable runes, but actually contains non-printable runes. F is the name of the string allowed to only contain printable runes

func NotAvailable

func NotAvailable(a *NotAvailableArgs) error

NotAvailable can be used if a service is not available.

func NotEqual

func NotEqual(a *NotEqualArgs) error

NotEqual can be used if two variables are equal but not expected to be equal.

func NotExistent

func NotExistent(F string) error

NotExistent can be used if a required object does not exist, for example, a file. F is the name of the object, for example, file name

func NotSet

func NotSet(F string) error

NotSet can be used if a required object is not set, for example, an environment variable. F is the name of the object, for example, 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.

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, for example, a filename
	F string
	// Err is the error causing the failed check, for example, 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 Equal

type EqualStrArgs

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

EqualStrArgs holds the required arguments for the error function EqualStr

type EqualfArgs

type EqualfArgs struct {
	// Var is the name of the variable
	Var string
	// Actual is the actual value of Var
	Actual float64
	// Want is the expected value of Var
	Want float64
}

EqualfArgs holds the required arguments for the error function Equalf

type HigherArgs

type HigherArgs struct {
	// Var is the name of the variable
	Var string
	// Actual is the actual 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 LowerArgs

type LowerArgs 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
}

LowerArgs holds the required arguments for the error function Lower

type NotAvailableArgs

type NotAvailableArgs struct {
	// S is the name of the service not available
	S string
	// Err is the error provided by the service
	Err error
}

NotAvailableArgs holds the required arguments for the error function NotAvailable

type NotEqualArgs

type NotEqualArgs struct {
	// Name of the variable equal to Y
	X string
	// Name of the variable equal to X
	Y string
}

NotEqualArgs holds the required arguments for the error function NotEqual

type OpArgs

type OpArgs struct {
	// Op is the name of the failed operation, for example, WriteStr
	Op string
	// Fn is the name of the object passed to the operation, for example, a filename
	Fn string
	// Err is the error retrieved from the failed operation, for example, 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 {
	// Actual is the name of the actual type of the object, for example, a file
	Actual string
	// Want is the name of the expected, wanted or required type the object should be, for example, a directory
	Want string
}

TypeNotMatchingArgs holds the required arguments for the error function TypeNotMatching