errpath

README

Error Path

Package errpath provides utilities for creating and managing detailed error paths. It allows users to construct error messages that include the full path to the error, which can be particularly useful when traversing complex data structures such as JSON or YAML files.

Example for an error in an OpenAPI: components.schemas["Pet"].allOf[0]: invalid schema

The package defines several error types that can be used to represent different kinds of errors, such as missing required values, invalid values, and errors occurring at specific fields, indices, or keys within a data structure. These error types implement a chaining mechanism that builds a detailed error path.

Installation

To use this package, import it as follows:

import "github.com/MarkRosemaker/errpath"

Creating Errors

There are several types of errors you can create with this package:

ErrRequired

Signals that a required value is missing.

	err := &errpath.ErrRequired{}

ErrInvalid

Signals that a value is invalid. You can optionally provide valid values and an explanatory message.

	err := &errpath.ErrInvalid[string]{
	    Value:   "invalid_value",
	    Enum:    []string{"valid1", "valid2"},
	    Message: "must be one of the valid values",
	}

ErrField

Represents an error that occurred in a specific field.

	err := &errpath.ErrField{
	    Field: "fieldName",
	    Err:   &errpath.ErrRequired{},
	}

ErrIndex

Represents an error that occurred at a specific index in a slice.

	err := &errpath.ErrIndex{
	    Index: 3,
	    Err:   &errpath.ErrInvalid[int]{Value: 42},
	}

ErrKey

Represents an error that occurred at a specific key in a map.

	err := &errpath.ErrKey{
	    Key: "keyName",
	    Err: &errpath.ErrRequired{},
	}

Error Chaining

Errors can be nested to form detailed error paths. For example:

	err := &errpath.ErrField{
	    Field: "foo",
	    Err: &errpath.ErrField{
	        Field: "bar",
	        Err: &errpath.ErrKey{
	            Key: "baz",
	            Err: &errpath.ErrField{
	                Field: "qux",
	                Err: &errpath.ErrIndex{
	                    Index: 3,
	                    Err: &errpath.ErrField{
	                        Field: "quux",
	                        Err: &errpath.ErrInvalid[string]{
	                            Value: "corge",
	                        },
	                    },
	                },
	            },
	        },
	    },
	}

This will produce an error message like:

	foo.bar["baz"].qux[3].quux ("corge") is invalid

Additional Information

• Go Reference: The Go reference documentation for the errpath package.
• Go Report Card: Check the code quality report.

Contributing

If you have any contributions to make, please submit a pull request or open an issue on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Overview

Package errpath provides utilities for creating and managing detailed error paths. It allows users to construct error messages that include the full path to the error, which can be particularly useful when traversing complex data structures such as JSON or YAML files.

The package defines several error types that can be used to represent different kinds of errors, such as missing required values, invalid values, and errors occurring at specific fields, indices, or keys within a data structure. These error types implement a chaining mechanism that builds a detailed error path.

Usage:

To use this package, import it as follows:

import "github.com/MarkRosemaker/errpath"

Creating Errors:

There are several types of errors you can create with this package:

1. ErrRequired: Signals that a required value is missing.

err := &errpath.ErrRequired{}

2. ErrInvalid: Signals that a value is invalid. You can optionally provide valid values and an explanatory message.

err := &errpath.ErrInvalid[string]{
    Value:   "invalid_value",
    Enum:    []string{"valid1", "valid2"},
    Message: "must be one of the valid values",
}

3. ErrField: Represents an error that occurred in a specific field.

err := &errpath.ErrField{
    Field: "fieldName",
    Err:   &errpath.ErrRequired{},
}

4. ErrIndex: Represents an error that occurred at a specific index in a slice.

err := &errpath.ErrIndex{
    Index: 3,
    Err:   &errpath.ErrInvalid[int]{Value: 42},
}

5. ErrKey: Represents an error that occurred at a specific key in a map.

err := &errpath.ErrKey{
    Key: "keyName",
    Err: &errpath.ErrRequired{},
}

Error Chaining:

Errors can be nested to form detailed error paths. For example:

err := &errpath.ErrField{
    Field: "foo",
    Err: &errpath.ErrField{
        Field: "bar",
        Err: &errpath.ErrKey{
            Key: "baz",
            Err: &errpath.ErrField{
                Field: "qux",
                Err: &errpath.ErrIndex{
                    Index: 3,
                    Err: &errpath.ErrField{
                        Field: "quux",
                        Err: &errpath.ErrInvalid[string]{
                            Value: "corge",
                        },
                    },
                },
            },
        },
    },
}

This will produce an error message like:

foo.bar["baz"].qux[3].quux ("corge") is invalid

Index

• type ErrField
  • func (e *ErrField) Error() string
  • func (e *ErrField) Unwrap() error
• type ErrIndex
  • func (e *ErrIndex) Error() string
  • func (e *ErrIndex) Unwrap() error
• type ErrInvalid
  • func (e *ErrInvalid[_]) Error() string
• type ErrKey
  • func (e *ErrKey) Error() string
  • func (e *ErrKey) Unwrap() error
• type ErrRequired
  • func (e *ErrRequired) Error() string

Types

type ErrField

type ErrField struct {
	// The name of the field where the error occurred.
	Field string
	// The underlying error.
	Err error
}

ErrField is an error that occurred in a field.

func (*ErrField) Error

func (e *ErrField) Error() string

Error returns the whole path to the field and the error message.

func (*ErrField) Unwrap

func (e *ErrField) Unwrap() error

Unwrap returns the wrapped error.

type ErrIndex

type ErrIndex struct {
	// The index of the slice where the error occurred.
	Index int
	// The underlying error.
	Err error
}

ErrIndex is an error that occurred in a slice. It contains the index of the element.

func (*ErrIndex) Error

func (e *ErrIndex) Error() string

Error returns the index and the error message. However, it makes sense to wrap `ErrIndex` in an `ErrField` so this method is rarely called.

func (*ErrIndex) Unwrap

func (e *ErrIndex) Unwrap() error

Unwrap returns the wrapped error.

type ErrInvalid

type ErrInvalid[T any] struct {
	// The value that is invalid.
	Value T
	// An optional list of valid values.
	Enum []T
	// An optional message that explains the error.
	Message string
}

ErrInvalid signals that a value is invalid.

func (*ErrInvalid[_]) Error

func (e *ErrInvalid[_]) Error() string

Error returns helpful information about the invalid field and how to fix it. Without a previous error path, it simply calls it "a value". It makes sense to wrap `ErrInvalid` in another error such as `ErrField` so the user knows that the field is invalid.

type ErrKey

type ErrKey struct {
	// The key of the map where the error occurred.
	Key string
	// The underlying error.
	Err error
}

ErrKey is an error that occurred in a map. It contains the key of the element.

func (*ErrKey) Error

func (e *ErrKey) Error() string

Error returns the key and the error message. However, it makes sense to wrap `ErrKey` in an `ErrField` so this method is rarely called.

func (*ErrKey) Unwrap

func (e *ErrKey) Unwrap() error

Unwrap returns the wrapped error.

type ErrRequired

type ErrRequired struct{}

ErrRequired signals that a required value is missing.

func (*ErrRequired) Error

func (e *ErrRequired) Error() string

Error fulfills the error interface. Without a previous error path, it simply says "a value is required". Naturally, this is not very helpful, so it makes sense to wrap `ErrRequired` in another error such as `ErrField` so the user knows that the field was required.