errors.go

package jsonstat

import (
	"errors"
	"fmt"
)

// Sentinel errors. All public errors returned by this package are either one
// of these (testable with errors.Is) or wrap one of them, so callers can
// branch on cause without parsing error strings. See
// https://pkg.go.dev/errors#Is.
//
// The numeric codes are stable and match the vocabulary documented in the
// plan: <https://json-stat.org/> wiki's validator page lists the same rule
// categories. They are deliberately small integers, not magic strings, so
// they fit in a single line of slog output.

// ErrDatasetNotFound is returned when a requested dataset is not present in
// the document (for example, doc.Dataset(99) on a single-dataset document).
var ErrDatasetNotFound = errors.New("jsonstat: dataset not found")

// ErrDimensionNotFound is returned when a requested dimension ID is not
// declared in the dataset.
var ErrDimensionNotFound = errors.New("jsonstat: dimension not found")

// ErrCategoryNotFound is returned when a requested category ID is not present
// in a dimension.
var ErrCategoryNotFound = errors.New("jsonstat: category not found")

// ErrItemNotFound is returned when a collection item lookup fails.
var ErrItemNotFound = errors.New("jsonstat: item not found")

// ErrIndexOutOfRange is returned when a numeric index (dataset index,
// category index, or cell coordinate) is out of range.
var ErrIndexOutOfRange = errors.New("jsonstat: index out of range")

// ErrCoordLenMismatch is returned when a coordinate vector length does not
// match the dataset's dimension count.
var ErrCoordLenMismatch = errors.New("jsonstat: coordinate length mismatch")

// ErrInvalidSize is returned by decode/validate when the size array is
// inconsistent (negative entries, length mismatch with id, etc.).
var ErrInvalidSize = errors.New("jsonstat: invalid size")

// ErrValueShape is returned by decode when the "value" property is neither an
// array nor an object, or by traverse when the resolved flat index is out of
// range for the value store.
var ErrValueShape = errors.New("jsonstat: invalid value shape")

// ErrSparseValueLength is returned by validate when a sparse value object
// contains a key ≥ the dataset's total cell count.
var ErrSparseValueLength = errors.New("jsonstat: sparse value key out of range")

// ErrStatusShape is returned by decode when the "status" property is neither
// a string, an array, nor an object.
var ErrStatusShape = errors.New("jsonstat: invalid status shape")

// ErrMissingRequired is returned by validate when a JSON-stat 2.0 required
// property is absent.
var ErrMissingRequired = errors.New("jsonstat: missing required property")

// ErrUnknownClass is returned by decode when the document's "class" is not
// one of the JSON-stat 2.0 response classes.
var ErrUnknownClass = errors.New("jsonstat: unknown response class")

// ErrUnsupportedVersion is returned by decode when the document's "version"
// is below 2.0 and the document does not appear to be a tolerated pre-2.0
// bundle. Pre-2.0 bundles are accepted (see Decode) but never re-emitted by
// Encode.
var ErrUnsupportedVersion = errors.New("jsonstat: unsupported version")

// ErrEmptyDocument is returned by decode when the input is empty or only
// whitespace.
var ErrEmptyDocument = errors.New("jsonstat: empty document")

// ErrBuildIncomplete is returned by Builder.Build when the cube is missing
// required pieces (dimensions, categories, or values).
var ErrBuildIncomplete = errors.New("jsonstat: incomplete cube definition")

// CellMissing reports that the requested cell has no value (a JSON null in a
// dense value array, or an absent key in a sparse value object). It is not an
// error: callers should use [Cell.Missing] to test rather than errors.Is, but
// the sentinel is exported so that error-returning helpers can wrap it.
var ErrCellMissing = errors.New("jsonstat: cell has no value")

// ValueError carries context about where in the cube an error occurred. It
// is the structured wrapping type used by Decode, Validate, and the traversal
// methods. Callers can use errors.As to recover the structured context.
type ValueError struct {
	// Op is the operation that failed (e.g. "Decode", "Dataset.Dimension").
	Op string
	// Dim is the dimension ID involved, if any.
	Dim string
	// Cat is the category ID involved, if any.
	Cat string
	// Flat is the flat row-major cell index involved, if any. -1 means
	// "not applicable".
	Flat int
	// Err is the wrapped sentinel or underlying error.
	Err error
}

// Error implements error.
func (v *ValueError) Error() string {
	if v == nil || v.Err == nil {
		return "jsonstat: no error"
	}
	s := v.Op
	switch {
	case v.Dim != "" && v.Cat != "":
		s += ": dim=" + v.Dim + " cat=" + v.Cat
	case v.Dim != "":
		s += ": dim=" + v.Dim
	case v.Cat != "":
		s += ": cat=" + v.Cat
	}
	if v.Flat >= 0 {
		s += fmt.Sprintf(" flat=%d", v.Flat)
	}
	return s + ": " + v.Err.Error()
}

// Unwrap allows errors.Is / errors.As to reach the wrapped sentinel.
func (v *ValueError) Unwrap() error {
	if v == nil {
		return nil
	}
	return v.Err
}

// wrapErr returns a *ValueError wrapping err with the given op and context.
// If err is nil it returns nil.
func wrapErr(op string, err error, dim, cat string, flat int) error {
	if err == nil {
		return nil
	}
	return &ValueError{Op: op, Dim: dim, Cat: cat, Flat: flat, Err: err}
}