Skip to main content

HasErrorType

Give a context one shared, abstract Error type, so fallible generic code never names a concrete error.

Overview​

In Context-Generic Programming (CGP), HasErrorType lets generic code fail without committing to a concrete error type. CGP enables pluggable trait implementations in Rust, and HasErrorType is the component that lets a context plug in its error type. A provider that may error has to produce some error, but it runs against a context, the type that implements the trait, and it cannot know whether that context wants anyhow::Error, std::io::Error, or an enum of its own. HasErrorType resolves this by giving the context one abstract Self::Error type that every fallible operation refers to. Generic code returns Result<T, Self::Error>, and the concrete error is decided once, at wiring time, by whichever error backend the context plugs in.

Putting the error type on one component also keeps errors composable. If each fallible trait declared its own associated Error, a context bounded by several of them would face several unrelated Self::Error types with no way to unify them. Because the fallible components all supertrait HasErrorType, every one of them names the same Self::Error, so their results combine. This single shared abstract error is the anchor that CanRaiseError and CanWrapError build on.

Definition​

HasErrorType is defined as:

#[cgp_type]
#[prefix(@cgp.core.error in DefaultNamespace)]
pub trait HasErrorType {
type Error: Debug;
}

pub type ErrorOf<Context> = <Context as HasErrorType>::Error;

Its attributes:

  • #[cgp_type] — makes this an abstract-type component rather than a plain trait: it generates the provider trait, the component marker, and a UseType impl, so a context binds the concrete type by wiring.
  • #[prefix] — registers the component in DefaultNamespace under the path @cgp.core.error, so a context that joins that namespace binds its provider at @cgp.core.error.ErrorTypeProviderComponent rather than at the bare key.

Usage​

HasErrorType is in the prelude, so use cgp::prelude::*; is enough to name it. It is an abstract-type component: a trait with one associated type, Error, carrying a Debug bound. A context supplies its error type in one of two ways.

The direct way is an ordinary trait impl, which shows that HasErrorType is a plain associated-type trait:

impl HasErrorType for App {
type Error = anyhow::Error;
}

The wired way, and the common one, delegates the component's key to a provider that supplies the type. Because HasErrorType is defined with #[cgp_type], a context can name the concrete error directly with UseType<E>:

delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
}
}

The wiring key is ErrorTypeProviderComponent, not the trait name, and it lives under cgp::core::error rather than in the prelude, so a context that wires it imports the key. Whatever concrete error is chosen must implement Debug, because that bound is carried through every generated construct. The standalone backend crates cgp-error-anyhow, cgp-error-eyre, and cgp-error-std supply ready-made providers that set Error to their respective types.

Generic code names the abstract error with the #[use_type] attribute, which imports it as the bare name Error, or through the ErrorOf<Context> alias, which spells <Context as HasErrorType>::Error. ErrorOf, the provider trait ErrorTypeProvider, and the key ErrorTypeProviderComponent all come from cgp::core::error.

The same module carries ErrorOnly<E>, a zero-sized context whose one trait is HasErrorType, with Error = E for any E: Debug. It implements Default, so ErrorOnly::<String>::default() stands in wherever code needs a context that has an error type and nothing else, such as a test of a fallible function that reads nothing from its context:

use cgp::core::error::{ErrorOf, ErrorOnly};
use cgp::prelude::*;

pub fn parse_port<Context: HasErrorType<Error = String>>(
_context: &Context,
raw: &str,
) -> Result<u16, ErrorOf<Context>> {
raw.parse().map_err(|_| format!("bad port: {raw}"))
}

pub fn demo() {
let context = ErrorOnly::<String>::default();
assert_eq!(parse_port(&context, "80"), Ok(80));
assert_eq!(parse_port(&context, "x"), Err("bad port: x".to_owned()));
}

Examples​

A context declares its abstract error, and generic code returns it without naming a concrete type:

use cgp::core::error::ErrorTypeProviderComponent;
use cgp::prelude::*;

#[cgp_component(Validator)]
#[use_type(HasErrorType.Error)]
pub trait CanValidate {
fn validate(&self) -> Result<(), Error>;
}

pub struct App;

delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
}
}

check_components! {
App {
ErrorTypeProviderComponent,
}
}

Here #[use_type(HasErrorType.Error)] adds HasErrorType as a supertrait of CanValidate and rewrites the bare Error to <Self as HasErrorType>::Error, so validate returns the context's shared error without spelling Self::Error. App wires its error type to String, which satisfies the Debug bound. App is an environmental context, a type that stands for the application and carries its choices, and the component targets that context rather than a value.

When to use it​

Reach for HasErrorType in any fallible component whose error type the context should choose. It is the foundation of CGP's error handling and is a supertrait of every other fallible trait, so a component that returns a Result almost always wants the context's abstract error rather than a concrete one. Import it with #[use_type(HasErrorType.Error)] rather than writing a : HasErrorType supertrait and a Self::Error path by hand.

Do not reach for it when a component genuinely wants one fixed error type for the whole program with no per-context choice, where a concrete error in the signature is simpler. And where a provider must pin the abstract error to a concrete type, use the equality form #[use_type(HasErrorType.{Error = AppError})] rather than a hand-written where Self: HasErrorType<Error = AppError> clause.

  • #[cgp_type] — the macro HasErrorType is defined with, which generates its UseType provider.
  • HasType / TypeProvider — the tag-indexed abstract-type component; a TypeProvider can back this component through the WithProvider impl #[cgp_type] generates.
  • CanRaiseError — raises a source error into this abstract error.
  • CanWrapError — wraps detail onto this abstract error.
  • #[use_type] — imports the abstract error into a definition as the bare name Error.
  • Error providers — the interchangeable strategies that construct the error.

The ideas behind it:

  • Modular error handling — the abstract error type, its construction, and its detail as three independent wiring decisions.
  • Abstract types — the associated types a context chooses for itself.

Source​


An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.