xerrors

package
v0.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisableDebugMode 

func DisableDebugMode()

DisableDebugMode disables technical error details for the whole package.

It resets the package-wide debug flag so formatted errors remain concise and user-oriented when the application is running in standard mode.

func EnableDebugMode 

func EnableDebugMode()

EnableDebugMode enables technical error details for the whole package.

It stores a persistent runtime flag that causes formatted errors to include component traces and wrapped cause information during rendering.

func GetDebugMode 

func GetDebugMode() bool

GetDebugMode returns the current runtime state of the debug flag.

It exposes a thread-safe read of the package-wide debug toggle used by the error rendering engine to decide whether to show technical details.

func Print 

func Print(err error)

Print writes the supplied error to the standard error stream.

It acts as a lightweight helper for terminal diagnostics and emits the error text to os.Stderr when the provided value is non-nil.

func RegisterDomainErrors 

func RegisterDomainErrors(pkgCtx ErrorCode, customRegistry map[ErrorCode]MetaMessage)

RegisterDomainErrors injects custom domain error configurations into the centralized core registry. It uses sync.Map capabilities to safely register codes even if called concurrently during uptime.

func ToggleDebugMode 

func ToggleDebugMode()

ToggleDebugMode flips the global debug flag to its opposite state.

It uses an atomic compare-and-swap loop to preserve thread safety while switching between technical and sanitized error output modes.

func TraceCallerLocation 

func TraceCallerLocation(skip int) string

TraceCallerLocation resolves a package-qualified function name from the runtime stack.

It inspects the call stack using the supplied skip depth and returns a stable package::function identifier, falling back to safe "unknown" values when the runtime metadata is unavailable.

Types

type ErrorCode 

type ErrorCode string

ErrorCode defines a domain-specific string representation for error classification. 

const (
	XERR_NONE   ErrorCode = ""
	XERR_PKGCTX ErrorCode = "ERR_XERR"

	// XERR_UNKNOWN serves as the general fallback categorization for untracked exceptions.
	XERR_UNKNOWN ErrorCode = "E0001"

	// XERR_FIELD_REQUIRED belongs to Group 1 (Presence & Nullity).
	// Targets missing parameters, empty payloads, or fields whose total absence matches an 'undefined' state.
	// Format expects: CTX, MSG, FIELD, [error]
	XERR_FIELD_REQUIRED ErrorCode = "E1001"

	// XERR_NIL_NOT_ALLOWED belongs to Group 1 (Presence & Nullity).
	// Targets cases where a field or reference pointer is explicitly supplied but contains a forbidden nil value.
	// Format expects: CTX, MSG, FIELD, [error]
	XERR_NIL_NOT_ALLOWED ErrorCode = "E1002"

	// XERR_EMPTY_NOT_ALLOWED belongs to Group 1 (Presence & Nullity).
	// Targets fields that are allocated and non-nil, but their textual contents resolve to an empty string ("").
	// Format expects: CTX, MSG, FIELD, [error]
	XERR_EMPTY_NOT_ALLOWED ErrorCode = "E1003"

	// XERR_ZERO_NOT_ALLOWED belongs to Group 1 (Presence & Nullity).
	// Targets scenarios where numeric primitives, lengths, or uninitialized value types resolve to a forbidden zero state (0).
	// Format expects: CTX, MSG, FIELD, [error]
	XERR_ZERO_NOT_ALLOWED ErrorCode = "E1004"

	// XERR_ALREADY_EXISTS belongs to Group 1 (Presence & Nullity).
	// Targets uniqueness constraint violations where a valid field value cannot be accepted because it duplicates an active record.
	// Format expects: CTX, MSG, FIELD, VALUE, [error]
	XERR_ALREADY_EXISTS ErrorCode = "E1005"

	// XERR_NOT_FOUND belongs to Group 1 (Presence & Nullity).
	// Targets cases where a perfectly valid field lookup identifier fails to map to an active resource or file path.
	// Format expects: CTX, MSG, FIELD, TGT, [error]
	XERR_NOT_FOUND ErrorCode = "E1006"

	// XERR_PERMISSION_DENIED belongs to Group 1 (Presence & Nullity).
	// Targets security contract breaches where the application lacks the OS credentials, RBAC tokens,
	// or read/write privileges required to interact with the target resource.
	// Format expects: CTX, MSG, FIELD, TGT, [error]
	XERR_PERMISSION_DENIED ErrorCode = "E1007"

	// XERR_RESOURCE_UNAVAILABLE belongs to Group 1 (Presence & Nullity).
	// Targets IO blockages, hardware failures, timeout sequences, or networking disruptions
	// that prevent communication with an otherwise structurally valid target endpoint or file stream.
	// Format expects: CTX, MSG, FIELD, TGT, [error]
	XERR_RESOURCE_UNAVAILABLE ErrorCode = "E1008"

	// XERR_RESOURCE_CORRUPTED belongs to Group 1 (Presence & Nullity).
	// Targets integrity structural failures where the resource (file, payload, or state)
	// is physically present but its inner bytes break syntax rules, cryptographic checksums, or validation schemas.
	// Format expects: CTX, MSG, FIELD, TGT, [error]
	XERR_RESOURCE_CORRUPTED ErrorCode = "E1009"

	// XERR_RESOURCE_NOT_FOUND belongs to Group 1 (Presence & Nullity).
	// Targets system I/O, file systems, or directories that do not exist at the specified target path.
	// Format expects: CTX, MSG, FIELD, TGT, [error]
	XERR_RESOURCE_NOT_FOUND ErrorCode = "E1010"

	// XERR_INVALID_VALUE belongs to Group 2 (Numeric & Boundaries).
	// General fallback for values that satisfy basic structural parsing but fail specialized domain business rules.
	// Format expects: CTX, MSG, FIELD, VALUE, RULES, [error]
	XERR_INVALID_VALUE ErrorCode = "E2001"

	// XERR_INVALID_VALUE_GT_ZERO belongs to Group 2 (Numeric & Boundaries).
	// Enforces that an evaluated mathematical property must be strictly greater than zero (> 0).
	// Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error]
	XERR_INVALID_VALUE_GT_ZERO ErrorCode = "E2002"

	// XERR_INVALID_VALUE_GE_ZERO belongs to Group 2 (Numeric & Boundaries).
	// Enforces that an evaluated mathematical property must be greater than or equal to zero (>= 0).
	// Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error]
	XERR_INVALID_VALUE_GE_ZERO ErrorCode = "E2003"

	// XERR_INVALID_VALUE_LT_ZERO belongs to Group 2 (Numeric & Boundaries).
	// Enforces that an evaluated mathematical property must be strictly less than zero (< 0).
	// Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error]
	XERR_INVALID_VALUE_LT_ZERO ErrorCode = "E2004"

	// XERR_INVALID_VALUE_LE_ZERO belongs to Group 2 (Numeric & Boundaries).
	// Enforces that an evaluated mathematical property must be less than or equal to zero (<= 0).
	// Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error]
	XERR_INVALID_VALUE_LE_ZERO ErrorCode = "E2005"

	// XERR_INVALID_VALUE_OUT_OF_RANGE belongs to Group 2 (Numeric & Boundaries).
	// Enforces that numbers, calendar dates, or generic offsets must stay enclosed within explicit low-high thresholds.
	// Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error]
	XERR_INVALID_VALUE_OUT_OF_RANGE ErrorCode = "E2006"

	// XERR_SELECTION_LIMIT_EXCEEDED belongs to Group 2 (Numeric & Boundaries).
	// Targets scenarios where the number of selected items breaks cardinality boundaries or exceeds the maximum quantity constraints.
	// Format expects: CTX, MSG, FIELD, OPT, COUNT, LIMIT, [error]
	XERR_SELECTION_LIMIT_EXCEEDED ErrorCode = "E2007"

	// XERR_INVALID_FORMAT belongs to Group 3 (Structure & Choices).
	// Targets syntax anomalies where string shapes break regex validations, structural encoding, or lexical requirements.
	// Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error]
	XERR_INVALID_FORMAT ErrorCode = "E3001"

	// XERR_INVALID_FORMAT_MARSHAL belongs to Group 3 (Structure & Choices).
	// Targets serialization anomalies where structural objects or typed domain entities fail to transform into target data shapes.
	// Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error]
	XERR_INVALID_FORMAT_MARSHAL ErrorCode = "E3002"

	// XERR_INVALID_FORMAT_UNMARSHAL belongs to Group 3 (Structure & Choices).
	// Targets deserialization anomalies where raw payload inputs break type structural specifications during structural unmarshaling.
	// Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error]
	XERR_INVALID_FORMAT_UNMARSHAL ErrorCode = "E3003"

	// XERR_INVALID_FORMAT_PARSE belongs to Group 3 (Structure & Choices).
	// Targets conversion anomalies where string primitives or unstructured slices fail lexical conversion into valid data primitives.
	// Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error]
	XERR_INVALID_FORMAT_PARSE ErrorCode = "E3004"

	// XERR_INVALID_TYPE belongs to Group 3 (Structure & Choices).
	// Targets type mismatch exceptions triggered during interface assertions, reflection mapping, or payload unmarshaling.
	// Format expects: CTX, MSG, FIELD, VALUE, EXPECTED_TYPE, [error]
	XERR_INVALID_TYPE ErrorCode = "E3005"

	// XERR_INVALID_OPTION belongs to Group 3 (Structure & Choices).
	// Targets invalid parameters outside a restrictive list of valid options or mutual exclusivity boundary contract violations.
	// Format expects: CTX, MSG, FIELD, OPT, OPTIONS, [error]
	XERR_INVALID_OPTION ErrorCode = "E3006"

	// XERR_MUTUAL_EXCLUSIVITY_VIOLATION belongs to Group 3 (Structure & Choices).
	// Targets structural contract breaches where choosing a specific field or option strictly invalidates the co-existence of others.
	// Format expects: CTX, MSG, FIELD, OPT, OPTIONS, [error]
	XERR_MUTUAL_EXCLUSIVITY_VIOLATION ErrorCode = "E3007"

	// XERR_ASYMMETRIC_SIZES belongs to Group 3 (Structure & Choices).
	// Targets structural contract breaches where interdependent collections fail to match linear sequence length.
	// Format expects: CTX, MSG, FIELDS, [error]
	XERR_ASYMMETRIC_SIZES ErrorCode = "E3008"

	// XERR_UNEXPECTED_FAIL belongs to Group 4 (Generic Operational Fallbacks).
	// Targets severe, non-deterministic system breakdowns, unmapped runtime panic states, or logic violations
	// that breach system stability invariants. Designed to act as a global strategic catch-all mechanism.
	// Format expects: CTX, MSG, DATA, [error]
	XERR_UNEXPECTED_FAIL ErrorCode = "E4001"

	// XERR_OPERATION_FAILED belongs to Group 4 (Generic Operational Fallbacks).
	// Targets state machine disruptions, unexecutable business commands, or processing
	// sequences that fail to complete their logic due to internal routine faults.
	// Format expects: CTX, MSG, FIELD, DATA, [error]
	XERR_OPERATION_FAILED ErrorCode = "E4002"
)

type IError400 

type IError400 interface {
	// Code returns the categorical failure domain classification.
	Code() ErrorCode

	// WithArgs appends dynamic contextual payloads to map sequentially into metadata extraTags.
	WithArgs(args ...any) IError400

	// error ensures native alignment with Go standard library error handling semantics.
	error
}

IError400 standardizes validation and client-side failures, allowing transport layers to seamlessly extract error codes without string parsing.

func NewError400 

func NewError400(args ...any) IError400

NewError400 creates an IError400 instance from a flexible set of arguments.

It recognizes registered error-code tokens, plain formatted text, and empty input, then returns a compatible adapter with the appropriate context and message payload for validation failures.

type IError500 

type IError500 interface {
	// CTX extracts the entry point operational flow boundary metadata.
	CTX() ErrorCode

	// Code returns the categorical failure domain classification.
	Code() ErrorCode

	// Component pinpoints the reflective architectural package or execution function path.
	Component() string

	// WithCallerSkip dynamically shifts the stack frame runtime collection depth.
	WithCallerSkip(skip int) IError500

	// WithArgs appends dynamic contextual payloads to map sequentially into metadata extraTags.
	WithArgs(args ...any) IError500

	// Message extracts the human-readable summary detailing the specific failure.
	Message() string

	// Info returns secondary raw debugging contextual payloads.
	Info() string

	// error ensures native integration with Go standard library error semantics.
	error
}

IError500 standardizes server-side, operational diagnostic payloads.

func NewError500 

func NewError500(
	errCTX ErrorCode,
	errCode ErrorCode,
	err error,
	message string,
	info string,
) IError500

NewError500 creates an operational IError500 instance with underlying error context.

It preserves the supplied context, error code, cause, summary message, and additional debugging payload while enabling component tracing for the error.

type IErrorCLI 

type IErrorCLI interface {
	// error implements the native Go error interface.
	error

	// SetMessage overrides the current technical diagnostic text and the current end-user friendly instruction.
	SetMessage(format string, args ...any) IErrorCLI

	// SetDevMessage overrides the current technical diagnostic text.
	SetDevMessage(format string, args ...any) IErrorCLI

	// SetUserMessage overrides the current end-user friendly instruction.
	SetUserMessage(format string, args ...any) IErrorCLI

	// AppendDevMessage concatenates a text payload into the current developer message.
	AppendDevMessage(format string, args ...any) IErrorCLI

	// AppendUserMessage concatenates a text payload into the current end-user message.
	AppendUserMessage(format string, args ...any) IErrorCLI

	// AppendLNDevMessage concatenates a text payload appending an explicit newline character at the end.
	AppendLNDevMessage(format string, args ...any) IErrorCLI

	// AppendLNUserMessage concatenates a text payload appending an explicit newline character at the end.
	AppendLNUserMessage(format string, args ...any) IErrorCLI

	// ClearDevMessage purges the developer message content, resetting it to empty string.
	ClearDevMessage() IErrorCLI

	// ClearUserMessage purges the end-user message content, resetting it to empty string.
	ClearUserMessage() IErrorCLI

	// WithDepth forces the engine to recalculate the runtime trace stack location using an offset.
	WithDepth(additionalDepth int) IErrorCLI

	// GetFunction returns the qualified target name tracking the package and functional scope.
	GetFunction() string

	// GetDevMessage returns the technical diagnostics text string.
	GetDevMessage() string

	// GetUserMessage returns the actionable text instruction designed for human end-users.
	GetUserMessage() string

	// HasDevMessage verifies if a technical message payload has been populated.
	HasDevMessage() bool

	// HasUserMessage verifies if a human-friendly instruction payload has been populated.
	HasUserMessage() bool

	// HasErrors checks if any descriptive message fields contain active content tracking failures.
	HasErrors() bool
}

IErrorCLI defines the structural behavioral contract for light, terminal-friendly errors.

func NewErrorCLI 

func NewErrorCLI() IErrorCLI

NewErrorCLI creates a new CLI-oriented error with automatic location tracking.

It captures the immediate caller metadata from the runtime stack so the new error can report the originating function when rendered.

func NewErrorCLIWithFunc 

func NewErrorCLIWithFunc(functionName string) IErrorCLI

NewErrorCLIWithFunc creates a CLI-oriented error with an explicit function location.

Arguments:

  • functionName: The static text representation of the target scope location (for example, "pkgname::FunctionName").

type MetaMessage 

type MetaMessage struct {
	// contains filtered or unexported fields
}

MetaMessage stores fallback message text, field-rule metadata, and extra tag names.

It provides the package with reusable, structured formatting details that can be attached to error codes for predictable rendering.

func NewMetaMessage 

func NewMetaMessage(
	message string,
	fieldRule string,
	extraTags []string,
) MetaMessage

NewMetaMessage creates and returns a populated MetaMessage instance.

It exposes a simple constructor for registering fallback metadata that can be reused by the package when an error code requires a standard message layout.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.