aria Namespace Reference

Namespaces
namespace	abi
namespace	adapters
namespace	async
namespace	binding
namespace	reactive
namespace	runtime
namespace	testing
namespace	trace
namespace	validation_dsl

Classes
class	bad_inplace_function_call
class	BatchScope
	RAII batch guard: { BatchScope b; ...; } or use batch([&]{...}). More...
struct	CallbackFailure
	Payload passed to a callback-failure sink. More...
class	CircularDependencyError
	Thrown when flush detects a dependency cycle. More...
class	Command
	Encapsulated user action with an optional CanExecute predicate. More...
class	Command<>
class	Computed
class	DistinctList
class	Effect
struct	Error
	One uniform error record. More...
class	FilteredList
class	function_ref
class	function_ref< R(Args...)>
class	GraphInspector
	Lightweight diagnostics entry point. More...
struct	Group
	One bucket in a GroupedList<T, Key>. More...
class	GroupedList
class	IDelayedScheduler
	Tiny interface — anything that can post a function to run after a delay. More...
class	inplace_function
class	inplace_function< R(Args...), Capacity, Alignment >
class	IProperty
	Type-erased Property surface. More...
class	IScheduler
struct	ListChange
	An owning event in a sequential list edit stream. More...
class	Loadable
	Standard loadable view-model. More...
class	MappedList
class	MultiSelection
class	ObservableList
	Observable sequence of owning element handles. More...
class	PagedList
class	Property
class	ScopedTraceSink
	Installs a sink for the lifetime of the scope, restoring whatever was previously installed (possibly nothing) on destruction. More...
class	Selection
class	SortedList
class	Subscription
	RAII handle to a single subscription. More...
class	SubscriptionBag
	Aggregate holder: owns multiple Subscriptions and drops them together. More...
struct	TraceEvent
	One trace event. More...
class	unsupported_capability
	Thrown when a caller invokes a capability the scheduler did not advertise (e.g. More...
class	UntrackedScope
	RAII: within the scope, every dep() behaves like a plain get(). More...
struct	ValidationKey
	(field_path, rule_id) locator for a validation message. More...
struct	ValidationResult
struct	ValidationState
class	Validator

Concepts
concept	EqualityComparable
	Type that supports == and != (required for change detection).
concept	InvocableR
	Anything that can be invoked with Args... and returns convertible-to-Ret.
concept	ListSource
concept	ListSourceOf
concept	Observable
	A read-only observable: has .get() and exposes its value_type.
concept	PropertyValue
	Type usable as a Property value:
concept	ReactiveNode
	Type that participates in the reactive graph: inherits from aria::reactive::Node.
concept	ReadOnlyReactive
	A reactive cell that can be read and observed, but not written: exactly the surface a one-way (VM→View) binding needs.
concept	ReadOnlyReactiveOf
	ReadOnlyReactive pinned to a specific value type — the constraint for the typed scalar binders (bind_text_oneway wants value_type to be exactly std::string, bind_visible wants bool, ...).
concept	ReadOnlyReactiveOptional
	A ReadOnlyReactive whose value_type is some std::optional<U> — the shape of AsyncCommand::last_result, and the constraint for BindingEngine::bind_optional_text.

Typedefs
using	CallbackFailureSink = void (*)(const CallbackFailure&)
	Sink type.
using	TracePayload
	Heterogeneous payload. Order matches TraceCategory.
using	TraceSink = std::function<void(const TraceEvent&)>
	User-facing sink shape: a callable that receives every published event.
template<typename L>
using	list_source_value_t
	Element type for a list source.

Enumerations
enum class	TraceCategory : std::uint8_t {   Reactive = 0 , Async = 1 , Binding = 2 , Command = 3 ,   Validation = 4 , List = 5 }
	Coarse subsystem label. More...
enum class	ErrorKind : std::uint8_t {   UserError = 0 , Validation = 1 , AsyncFailure = 2 , Cancellation = 3 ,   Timeout = 4 , BindingFailure = 5 , GraphCycle = 6 , InvariantViolation = 7 }
	Coarse classification of every error Aria can surface. More...
enum class	ListChangeKind {   Insert , Remove , Replace , ItemChanged ,   Reset , Move }
enum class	LoadState : unsigned char {   Idle = 0 , Loading = 1 , Refreshing = 2 , Success = 3 ,   Error = 4 }
	Discriminator for Loadable<T>. More...
enum class	SchedulerCaps : std::uint32_t {   None = 0 , Post = 1u << 0 , Delay = 1u << 1 , MainThread = 1u << 2 ,   Pumpable = 1u << 3 , GraphSafe = 1u << 4 , WorkerSafe = 1u << 5 , Autonomous = 1u << 6 }
enum class	Severity : std::uint8_t { Error = 0 , Warning = 1 }
	Severity of a single error / warning. More...

Functions
CallbackFailureSink	set_callback_failure_sink (CallbackFailureSink sink) noexcept
	Install a global callback-failure sink.
CallbackFailureSink	current_callback_failure_sink () noexcept
	Read the currently installed sink.
void	report_callback_failure (std::string_view category, std::exception_ptr exception, std::string_view message={}) noexcept
	Report a callback failure.
void	report_callback_failure (std::string_view category, std::string_view message) noexcept
	Convenience overload taking a precomputed message and no exception pointer (e.g.
template<typename Key, typename Source, typename KeyFn, typename T = list_source_value_t<Source>> requires ListSourceOf<Source, T>
std::shared_ptr< DistinctList< T, Key, Source > >	distinct (std::shared_ptr< Source > source, KeyFn key_of)
template<typename Source, typename Predicate, typename T = list_source_value_t<Source>> requires ListSourceOf<Source, T>
std::shared_ptr< FilteredList< T, Source > >	filtered (std::shared_ptr< Source > source, Predicate predicate)
template<typename Key, typename Source, typename KeyFn, typename T = list_source_value_t<Source>> requires ListSourceOf<Source, T>
std::shared_ptr< GroupedList< T, Key, Source > >	grouped (std::shared_ptr< Source > source, KeyFn key_of)
template<typename Target, typename SourceList, typename MapFn, typename Source = list_source_value_t<SourceList>> requires ListSourceOf<SourceList, Source>
std::shared_ptr< MappedList< Source, Target, SourceList > >	mapped (std::shared_ptr< SourceList > source, MapFn mapper, bool remap_on_change=false)
template<typename Source, typename T = list_source_value_t<Source>> requires ListSourceOf<Source, T>
std::shared_ptr< PagedList< T, Source > >	paged (std::shared_ptr< Source > source, std::size_t page_size, std::size_t page_index=0)
template<typename Source, typename Comparator, typename T = list_source_value_t<Source>> requires ListSourceOf<Source, T>
std::shared_ptr< SortedList< T, Source > >	sorted (std::shared_ptr< Source > source, Comparator comparator)
std::string_view	to_string (TraceCategory c) noexcept
void	install_trace_sink (TraceSink sink)
	Install (or replace) the global sink.
void	clear_trace_sink () noexcept
	Tear down the global sink.
bool	has_trace_sink () noexcept
	True iff a sink is currently installed.
void	publish_trace_unchecked (const TraceEvent &event) noexcept
	Publish an already-built event using one owning sink snapshot.
void	publish_trace (const TraceEvent &event) noexcept
	Publish an already-built event.
template<detail::TracePayloadType Payload>
void	publish_trace_unchecked (TraceCategory category, Payload payload, std::optional<::aria::Error > error=std::nullopt)
	Build an event after taking one owning sink snapshot.
template<detail::TracePayloadType Payload>
void	publish_trace (TraceCategory category, Payload payload, std::optional<::aria::Error > error=std::nullopt)
	Convenience form for callers that already have a payload.
std::string_view	to_string (ErrorKind k) noexcept
std::string_view	to_string (Severity s) noexcept
bool	operator== (const Error &a, const Error &b) noexcept
bool	operator!= (const Error &a, const Error &b) noexcept
std::ostream &	operator<< (std::ostream &os, const Error &e)
template<class R, class... Args>
	function_ref (R(*)(Args...)) -> function_ref< R(Args...)>
template<PropertyValue T>
std::shared_ptr< Property< T > >	distinct_until_changed (Property< T > &source)
template<PropertyValue T>
std::shared_ptr< Property< T > >	debounce (Property< T > &source, std::chrono::milliseconds quiet, IDelayedScheduler &timer)
template<PropertyValue T>
std::shared_ptr< Property< T > >	throttle (Property< T > &source, std::chrono::milliseconds cooldown, IDelayedScheduler &timer)
template<PropertyValue T, PropertyValue Acc, typename Reducer>
std::shared_ptr< Property< Acc > >	scan (Property< T > &source, Acc seed, Reducer reduce)
template<PropertyValue A, PropertyValue B, typename Combiner>
auto	combine_latest (Property< A > &a, Property< B > &b, Combiner combine) -> std::shared_ptr< Property< std::invoke_result_t< Combiner &, const A &, const B & > > >
constexpr SchedulerCaps	operator| (SchedulerCaps a, SchedulerCaps b) noexcept
constexpr SchedulerCaps	operator& (SchedulerCaps a, SchedulerCaps b) noexcept
constexpr SchedulerCaps &	operator|= (SchedulerCaps &a, SchedulerCaps b) noexcept
constexpr SchedulerCaps &	operator&= (SchedulerCaps &a, SchedulerCaps b) noexcept
constexpr bool	has_any (SchedulerCaps a, SchedulerCaps b) noexcept
constexpr bool	has_all (SchedulerCaps a, SchedulerCaps b) noexcept
bool	has_caps (const IScheduler &s, SchedulerCaps required) noexcept
void	require_caps (const IScheduler &s, SchedulerCaps required, const char *context="scheduler")
	Throwing accessor — useful at component construction time when missing a capability is a programmer error.
bool	operator== (const ValidationKey &a, const ValidationKey &b) noexcept
bool	operator!= (const ValidationKey &a, const ValidationKey &b) noexcept
std::ostream &	operator<< (std::ostream &os, const ValidationKey &k)
validation_dsl::FieldPart	field (std::string path) noexcept
validation_dsl::RulePart	rule_id (std::string id) noexcept
ValidationKey	operator/ (validation_dsl::FieldPart f, validation_dsl::RulePart r)
bool	operator== (const ValidationResult &a, const ValidationResult &b) noexcept
bool	operator!= (const ValidationResult &a, const ValidationResult &b) noexcept
bool	operator== (const ValidationState &a, const ValidationState &b) noexcept
bool	operator!= (const ValidationState &a, const ValidationState &b) noexcept
template<class Fn>
auto	batch (Fn &&fn) -> decltype(fn())
	Sugar: batch([&]{ firstName = "..."; lastName = "..."; }).
template<class Fn>
auto	untracked (Fn &&fn) -> decltype(fn())
	Sugar: untracked([&]{ ... }).
template<class Reactive>
requires ::aria::ReactiveNode< Reactive > void	dep (Reactive &r)

Typedef Documentation

CallbackFailureSink

using aria::CallbackFailureSink = void (*)(const CallbackFailure&)

Sink type.

The framework wraps every invocation in try / catch (...), so a sink that throws will not crash the noexcept reporter — the framework swallows the secondary failure and falls through to the stderr fallback. By contract the sink should still be noexcept; non-noexcept is allowed only because we cannot make exception safety observable on a function-pointer type alone.

TracePayload

using aria::TracePayload

Initial value:

std::variant<
   trace::Reactive,
   trace::Async,
   trace::Binding,
   trace::Command,
   trace::Validation,
   trace::List>

Heterogeneous payload. Order matches TraceCategory.

TraceSink

using aria::TraceSink = std::function<void(const TraceEvent&)>

User-facing sink shape: a callable that receives every published event.

Implementations should be cheap on the happy path: the publish call site is on the framework's hot path (every Property flush, every list mutation) so any non-trivial work in the sink must be pushed off-thread by the user themselves.

list_source_value_t

template<typename L>

using aria::list_source_value_t

Initial value:

typename detail::list_source_value_impl<
   std::remove_cvref_t<L>>::type

Element type for a list source.

Resolves value_type (preferred) then element_type. Both ObservableList<T> and the derived list types expose one or the other via the Signal parametrisation, but for the adapter contract we just need a stable name.

Enumeration Type Documentation

TraceCategory

enum class aria::TraceCategory : std::uint8_t

strong

Coarse subsystem label.

Routers / filters discriminate on this before looking at any other field. Stable enumerator order; never re-ordered, only appended at the end.

Enumerator
Reactive	Graph flush, push-color, pull-evaluate.
Async	AsyncCommand / AsyncResource lifecycle.
Binding	BindingEngine VM<->View dispatch.
Command	Synchronous Command<Args...> execution.
Validation	Validator / FormValidator rule runs.
List	ObservableList / FilteredList / SortedList / MappedList.

ErrorKind

enum class aria::ErrorKind : std::uint8_t

strong

Coarse classification of every error Aria can surface.

Designed so that a UI router can route on kind alone before inspecting any other field. Stable enumerator order; never re-ordered, only appended at the end.

Enumerator
UserError	Caller passed something the API explicitly forbids (null view model, out-of-range index, ...). Maps std::invalid_argument and std::out_of_range.
Validation	A validator rule failed. The accompanying Error::key is populated; Error::source is "Validator" or "FormValidator".
AsyncFailure	An asynchronous body threw a non-cancellation, non-timeout exception. Error::inner carries the original exception_ptr when available.
Cancellation	An OperationCancelled propagated through the async pipeline. Cancellation is a normal control-flow path; UI typically renders nothing for this kind.
Timeout	A with_timeout deadline elapsed (either Race or Fail mode).
BindingFailure	View / adapter side-effect failed (e.g. native widget setter threw). Currently reserved for future binding-side reporting; today binding errors propagate as exceptions.
GraphCycle	A reactive dependency cycle or non-converging flush was detected. Maps aria::CircularDependencyError.
InvariantViolation	A documented framework invariant was violated at runtime (reserved for stress / fuzz reporting; never thrown from the happy path).

ListChangeKind

enum class aria::ListChangeKind

strong

Enumerator
Insert
Remove
Replace
ItemChanged
Reset
Move

LoadState

enum class aria::LoadState : unsigned char

strong

Discriminator for Loadable<T>.

See file-level docs for the semantic of each tag (LO-1).

Enumerator
Idle
Loading
Refreshing
Success
Error

SchedulerCaps

enum class aria::SchedulerCaps : std::uint32_t

strong

Enumerator
None
Post	Can submit "fire now" work. Every conforming IScheduler supplies this (the pure virtual schedule()); declared as a capability for symmetry / introspection.
Delay	Can submit work after a wall-clock or virtual-time delay. Implementation must override schedule_after.
MainThread	Submitted work runs on a single, identifiable "main" thread that is consistent across calls. is_main_thread() is meaningful.
Pumpable	Posted work is held in a queue until a pump-style call drains it (e.g. pump/drain/run_one). Components that need deterministic test-driven progress should require this.
GraphSafe	Safe to use as the graph-thread executor — i.e. work posted here will not race the reactive graph's owner-thread invariant. Equivalent to the historical is_safe_graph_executor().
WorkerSafe	Safe to host blocking worker tasks (e.g. backed by a thread pool). Equivalent to the historical is_safe_worker_executor().
Autonomous	Implementation does not require any external pump and runs work on background threads autonomously. Useful for tests that want to assert "this is a thread pool, not a UI dispatcher".

Severity

enum class aria::Severity : std::uint8_t

strong

Severity of a single error / warning.

Carried on aria::Error; also pre-declared here so consumers that only need ValidationKey + Severity (without the whole Error machinery) can stay lightweight.

Enumerator
Error
Warning

Function Documentation

set_callback_failure_sink()

CallbackFailureSink aria::set_callback_failure_sink ( CallbackFailureSink sink )

inlinenoexcept

Install a global callback-failure sink.

Pass nullptr to revert to the stderr fallback. Returns the previously installed sink (nullptr if none).

current_callback_failure_sink()

CallbackFailureSink aria::current_callback_failure_sink ( )

inlinenodiscardnoexcept

Read the currently installed sink.

Returns nullptr if the stderr fallback is active. Mostly for diagnostics / introspection.

report_callback_failure() [1/2]

void aria::report_callback_failure ( std::string_view category, std::exception_ptr exception, std::string_view message = {} )

noexcept

Report a callback failure.

Always succeeds (never throws). The reporter will:

1. Try the installed sink first (if any).
2. If the sink throws, swallow it and fall through to the default.
3. Otherwise route to the stderr fallback. Recursive reports use a minimal stderr message without invoking user code again.

report_callback_failure() [2/2]

void aria::report_callback_failure ( std::string_view category, std::string_view message )

inlinenoexcept

Convenience overload taking a precomputed message and no exception pointer (e.g.

when the framework observed a contract violation it does not wish to model as an exception).

distinct()

template<typename Key, typename Source, typename KeyFn, typename T = list_source_value_t<Source>>
requires ListSourceOf<Source, T>

std::shared_ptr< DistinctList< T, Key, Source > > aria::distinct ( std::shared_ptr< Source > source, KeyFn key_of )

nodiscard

filtered()

template<typename Source, typename Predicate, typename T = list_source_value_t<Source>>
requires ListSourceOf<Source, T>

std::shared_ptr< FilteredList< T, Source > > aria::filtered ( std::shared_ptr< Source > source, Predicate predicate )

nodiscard

grouped()

template<typename Key, typename Source, typename KeyFn, typename T = list_source_value_t<Source>>
requires ListSourceOf<Source, T>

std::shared_ptr< GroupedList< T, Key, Source > > aria::grouped ( std::shared_ptr< Source > source, KeyFn key_of )

nodiscard

mapped()

template<typename Target, typename SourceList, typename MapFn, typename Source = list_source_value_t<SourceList>>
requires ListSourceOf<SourceList, Source>

std::shared_ptr< MappedList< Source, Target, SourceList > > aria::mapped ( std::shared_ptr< SourceList > source, MapFn mapper, bool remap_on_change = false )

nodiscard

paged()

template<typename Source, typename T = list_source_value_t<Source>>
requires ListSourceOf<Source, T>

std::shared_ptr< PagedList< T, Source > > aria::paged ( std::shared_ptr< Source > source, std::size_t page_size, std::size_t page_index = 0 )

nodiscard

sorted()

template<typename Source, typename Comparator, typename T = list_source_value_t<Source>>
requires ListSourceOf<Source, T>

std::shared_ptr< SortedList< T, Source > > aria::sorted ( std::shared_ptr< Source > source, Comparator comparator )

nodiscard

to_string() [1/3]

std::string_view aria::to_string ( TraceCategory c )

inlinenodiscardnoexcept

install_trace_sink()

void aria::install_trace_sink ( TraceSink sink )

inline

Install (or replace) the global sink.

Safe to call from any thread. Pass {} to clear; identical to clear_trace_sink().

clear_trace_sink()

void aria::clear_trace_sink ( )

inlinenoexcept

Tear down the global sink.

After this returns, publish() is a pure no-op until the next install.

has_trace_sink()

bool aria::has_trace_sink ( )

inlinenodiscardnoexcept

True iff a sink is currently installed.

Cheap; useful for sites that want to skip building a payload entirely when no one is listening.

publish_trace_unchecked() [1/2]

void aria::publish_trace_unchecked ( const TraceEvent & event )

inlinenoexcept

Publish an already-built event using one owning sink snapshot.

Callers normally gate expensive payload construction with has_trace_sink(). This overload remains safe if the sink is removed after that check.

publish_trace() [1/2]

void aria::publish_trace ( const TraceEvent & event )

inlinenoexcept

Publish an already-built event.

With no sink, only the atomic presence flag is read. An enabled sink is retained under the registry mutex and invoked outside it. Recursive traces are suppressed; sink exceptions are reported through the callback-failure boundary.

publish_trace_unchecked() [2/2]

template<detail::TracePayloadType Payload>

void aria::publish_trace_unchecked ( TraceCategory category, Payload payload, std::optional<::aria::Error > error = std::nullopt )

inline

Build an event after taking one owning sink snapshot.

Use after a has_trace_sink() gate to avoid building expensive payloads when disabled.

publish_trace() [2/2]

template<detail::TracePayloadType Payload>

void aria::publish_trace ( TraceCategory category, Payload payload, std::optional<::aria::Error > error = std::nullopt )

inline

Convenience form for callers that already have a payload.

To defer its construction, place has_trace_sink() before constructing the argument.

to_string() [2/3]

std::string_view aria::to_string ( ErrorKind k )

inlinenodiscardnoexcept

to_string() [3/3]

std::string_view aria::to_string ( Severity s )

inlinenodiscardnoexcept

operator==() [1/4]

bool aria::operator== ( const Error & a, const Error & b )

inlinenoexcept

operator!=() [1/4]

bool aria::operator!= ( const Error & a, const Error & b )

inlinenoexcept

operator<<() [1/2]

std::ostream & aria::operator<< ( std::ostream & os, const Error & e )

inline

function_ref()

template<class R, class... Args>

aria::function_ref

(

R(*

)(Args...)

)

-> function_ref< R(Args...)>

distinct_until_changed()

template<PropertyValue T>

std::shared_ptr< Property< T > > aria::distinct_until_changed ( Property< T > & source )

nodiscard

debounce()

template<PropertyValue T>

std::shared_ptr< Property< T > > aria::debounce ( Property< T > & source, std::chrono::milliseconds quiet, IDelayedScheduler & timer )

nodiscard

throttle()

template<PropertyValue T>

std::shared_ptr< Property< T > > aria::throttle ( Property< T > & source, std::chrono::milliseconds cooldown, IDelayedScheduler & timer )

nodiscard

scan()

template<PropertyValue T, PropertyValue Acc, typename Reducer>

std::shared_ptr< Property< Acc > > aria::scan ( Property< T > & source, Acc seed, Reducer reduce )

nodiscard

combine_latest()

template<PropertyValue A, PropertyValue B, typename Combiner>

auto aria::combine_latest ( Property< A > & a, Property< B > & b, Combiner combine ) -> std::shared_ptr< Property< std::invoke_result_t< Combiner &, const A &, const B & > > >

nodiscard

operator|()

SchedulerCaps aria::operator| ( SchedulerCaps a, SchedulerCaps b )

nodiscardconstexprnoexcept

operator&()

SchedulerCaps aria::operator& ( SchedulerCaps a, SchedulerCaps b )

nodiscardconstexprnoexcept

operator|=()

SchedulerCaps & aria::operator|= ( SchedulerCaps & a, SchedulerCaps b )

constexprnoexcept

operator&=()

SchedulerCaps & aria::operator&= ( SchedulerCaps & a, SchedulerCaps b )

constexprnoexcept

has_any()

bool aria::has_any ( SchedulerCaps a, SchedulerCaps b )

nodiscardconstexprnoexcept

has_all()

bool aria::has_all ( SchedulerCaps a, SchedulerCaps b )

nodiscardconstexprnoexcept

has_caps()

bool aria::has_caps ( const IScheduler & s, SchedulerCaps required )

inlinenodiscardnoexcept

require_caps()

void aria::require_caps ( const IScheduler & s, SchedulerCaps required, const char * context = "scheduler" )

inline

Throwing accessor — useful at component construction time when missing a capability is a programmer error.

operator==() [2/4]

bool aria::operator== ( const ValidationKey & a, const ValidationKey & b )

inlinenoexcept

operator!=() [2/4]

bool aria::operator!= ( const ValidationKey & a, const ValidationKey & b )

inlinenoexcept

operator<<() [2/2]

std::ostream & aria::operator<< ( std::ostream & os, const ValidationKey & k )

inline

field()

validation_dsl::FieldPart aria::field ( std::string path )

inlinenodiscardnoexcept

rule_id()

validation_dsl::RulePart aria::rule_id ( std::string id )

inlinenodiscardnoexcept

operator/()

ValidationKey aria::operator/ ( validation_dsl::FieldPart f, validation_dsl::RulePart r )

inlinenodiscard

operator==() [3/4]

bool aria::operator== ( const ValidationResult & a, const ValidationResult & b )

inlinenoexcept

operator!=() [3/4]

bool aria::operator!= ( const ValidationResult & a, const ValidationResult & b )

inlinenoexcept

operator==() [4/4]

bool aria::operator== ( const ValidationState & a, const ValidationState & b )

inlinenoexcept

operator!=() [4/4]

bool aria::operator!= ( const ValidationState & a, const ValidationState & b )

inlinenoexcept

batch()

template<class Fn>

auto aria::reactive::batch

(

Fn &&

fn

)

-> decltype(fn())

Sugar: batch([&]{ firstName = "..."; lastName = "..."; }).

untracked()

template<class Fn>

auto aria::reactive::untracked

(

Fn &&

fn

)

-> decltype(fn())

Sugar: untracked([&]{ ... }).

Matches the MobX/SolidJS naming so users coming from those ecosystems feel at home.

dep()

template<class Reactive>

requires ::aria::ReactiveNode< Reactive > void aria::reactive::dep

(

Reactive &

r

)