errors

Documentation

Overview

Package errors provides structured error codes and error handling for pulse.

Index

• func HasCode(err error, code Code) bool
• type Code
  • func AllCodes() []Code
  • func ParseCode(s string) (Code, bool)
• type CodedError
  • func NewCodedError(code Code, message string) *CodedError
  • func NewCodedErrorWithDetails(code Code, message string, details map[string]any) *CodedError
  • func WrapCodedError(err error, code Code, message string) *CodedError
  • func (e *CodedError) Error() string
  • func (e *CodedError) MarshalJSON() ([]byte, error)
  • func (e *CodedError) Unwrap() error

Functions

func HasCode

func HasCode(err error, code Code) bool

HasCode traverses the error chain to determine if any CodedError in the chain carries the specified code. Returns false if err is nil or no CodedError in the chain matches.

Types

type Code

type Code string

Code is a typed string representing categorical error codes. Each code identifies a specific error category within a domain.

const (
	// ENCODING_INVALID indicates invalid data format or structure.
	ENCODING_INVALID Code = "ENCODING_INVALID"

	// ENCODING_IO indicates I/O failures during read/write operations.
	ENCODING_IO Code = "ENCODING_IO"

	// ENCODING_TYPE_MISMATCH indicates type conversion or casting errors.
	ENCODING_TYPE_MISMATCH Code = "ENCODING_TYPE_MISMATCH"

	// ENCODING_INTERNAL indicates unexpected errors in encoding layer.
	ENCODING_INTERNAL Code = "ENCODING_INTERNAL"
)

ENCODING domain - Binary format and data encoding operations

const (
	// PROCESSING_CONFIG indicates component configuration errors.
	PROCESSING_CONFIG Code = "PROCESSING_CONFIG"

	// PROCESSING_STATE indicates context state management errors.
	PROCESSING_STATE Code = "PROCESSING_STATE"

	// PROCESSING_RUNTIME indicates runtime execution errors.
	PROCESSING_RUNTIME Code = "PROCESSING_RUNTIME"

	// PROCESSING_GROUP indicates group-related processing errors.
	PROCESSING_GROUP Code = "PROCESSING_GROUP"

	// PROCESSING_INTERNAL indicates unexpected errors in processing layer.
	PROCESSING_INTERNAL Code = "PROCESSING_INTERNAL"
)

PROCESSING domain - Processing engine and pipeline operations

const (
	// SERVICE_VALIDATION indicates request validation failures.
	SERVICE_VALIDATION Code = "SERVICE_VALIDATION"

	// SERVICE_RESOURCE indicates resource loading or access failures.
	SERVICE_RESOURCE Code = "SERVICE_RESOURCE"

	// SERVICE_REGISTRY indicates registry lookup failures.
	SERVICE_REGISTRY Code = "SERVICE_REGISTRY"

	// SERVICE_INTERNAL indicates unexpected errors in service layer.
	SERVICE_INTERNAL Code = "SERVICE_INTERNAL"
)

SERVICE domain - HTTP/API layer and service operations

const (
	// DATA_FILE indicates file access or format errors.
	DATA_FILE Code = "DATA_FILE"

	// DATA_PARSE indicates data parsing or deserialization errors.
	DATA_PARSE Code = "DATA_PARSE"

	// DATA_CONFIG indicates data configuration errors.
	DATA_CONFIG Code = "DATA_CONFIG"

	// DATA_CALCULATION indicates errors during data field access or calculation.
	DATA_CALCULATION Code = "DATA_CALCULATION"

	// DATA_INTERNAL indicates unexpected errors in data layer.
	DATA_INTERNAL Code = "DATA_INTERNAL"
)

DATA domain - Data file and dataset management operations

const (
	// CLI_INPUT indicates command input or argument errors.
	CLI_INPUT Code = "CLI_INPUT"

	// CLI_OUTPUT indicates output generation or file write errors.
	CLI_OUTPUT Code = "CLI_OUTPUT"

	// CLI_COMMAND indicates command execution errors.
	CLI_COMMAND Code = "CLI_COMMAND"

	// CLI_INTERNAL indicates unexpected errors in CLI layer.
	CLI_INTERNAL Code = "CLI_INTERNAL"
)

CLI domain - Command-line interface operations

const (
	// PULSE_IMPORT_SCHEMA_AMBIGUOUS indicates type ambiguity during schema inference.
	PULSE_IMPORT_SCHEMA_AMBIGUOUS Code = "PULSE_IMPORT_SCHEMA_AMBIGUOUS"

	// PULSE_IMPORT_ROW_ERROR indicates a per-row import error.
	PULSE_IMPORT_ROW_ERROR Code = "PULSE_IMPORT_ROW_ERROR"

	// PULSE_EXPORT_ROW_ERROR indicates a per-row export error.
	PULSE_EXPORT_ROW_ERROR Code = "PULSE_EXPORT_ROW_ERROR"

	// PULSE_IMPORT_CATEGORICAL_OVERFLOW indicates dictionary exceeds width capacity.
	PULSE_IMPORT_CATEGORICAL_OVERFLOW Code = "PULSE_IMPORT_CATEGORICAL_OVERFLOW"

	// PULSE_IMPORT_CATEGORICAL_UNBOUNDED indicates sample suggests unbounded cardinality.
	PULSE_IMPORT_CATEGORICAL_UNBOUNDED Code = "PULSE_IMPORT_CATEGORICAL_UNBOUNDED"

	// PULSE_IMPORT_DESCRIPTION_TOO_LONG indicates description exceeds 1000 bytes.
	PULSE_IMPORT_DESCRIPTION_TOO_LONG Code = "PULSE_IMPORT_DESCRIPTION_TOO_LONG"

	// PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL indicates a numeric aggregation
	// was requested on a categorical field.
	PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL Code = "PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL"

	// PULSE_FIELD_DESCRIPTION_LOW_QUALITY indicates a field description quality warning.
	PULSE_FIELD_DESCRIPTION_LOW_QUALITY Code = "PULSE_FIELD_DESCRIPTION_LOW_QUALITY"
)

PULSE domain - Pulse-specific error codes for I/O pipelines, categorical handling, description validation, and aggregation warnings.

func AllCodes

func AllCodes() []Code

AllCodes returns a copy of all defined error codes.

func ParseCode

func ParseCode(s string) (Code, bool)

ParseCode attempts to parse a string into a known Code. Returns the Code and true if found, or the zero value and false otherwise.

type CodedError

type CodedError struct {
	// Code identifies the error category.
	Code Code

	// Message provides a human-readable description.
	Message string

	// Details holds arbitrary key-value context (row number, field name, etc.).
	Details map[string]any

	// Cause is the underlying error, if any.
	Cause error
}

CodedError wraps an error code with context. It is the primary structured error type for Pulse, supporting JSON serialization for --json CLI output and error chain traversal via Unwrap.

func NewCodedError

func NewCodedError(code Code, message string) *CodedError

NewCodedError creates a new CodedError with no details or cause.

func NewCodedErrorWithDetails

func NewCodedErrorWithDetails(code Code, message string, details map[string]any) *CodedError

NewCodedErrorWithDetails creates a new CodedError with pre-populated details. The details map is defensively copied.

func WrapCodedError

func WrapCodedError(err error, code Code, message string) *CodedError

WrapCodedError wraps an existing error with a CodedError layer.

func (*CodedError) Error

func (e *CodedError) Error() string

Error implements the error interface. Format: "CODE: message"

func (*CodedError) MarshalJSON

func (e *CodedError) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, producing the --json envelope shape. When Details is nil, the "details" key is omitted entirely. When Details is non-nil (even if empty), the "details" key is included.

func (*CodedError) Unwrap

func (e *CodedError) Unwrap() error

Unwrap returns the underlying cause for errors.Is / errors.As traversal.