command.hpp

Go to the documentation of this file.

#pragma once
 
#include "aria/subscription.hpp"
#include "aria/diagnostics.hpp"
#include "aria/detail/typed_signal.hpp"
#include "aria/reactive/reactive.hpp"  // Effect -- auto-tracks reads in predicate()
 
#include <functional>
#include <memory>
#include <optional>
#include <utility>
 
namespace aria {
 
namespace binding { class BindingEngine; }

template<typename... Args>
class Command {
public:
    using Action = std::function<void(Args...)>;
    using Predicate = std::function<bool(const Args&...)>;
    using CanExecuteSignal = detail::TypedSignal<bool>;
 
    template<std::invocable<Args...> A>
    explicit Command(A&& action)
        : action_(std::forward<A>(action)),
          predicate_([](const Args&...) noexcept { return true; }),
          can_signal_(std::make_shared<CanExecuteSignal>()) {}
 
    template<std::invocable<Args...> A, std::predicate<const Args&...> P>
    Command(A&& action, P&& predicate)
        : action_(std::forward<A>(action)),
          predicate_(std::forward<P>(predicate)),
          can_signal_(std::make_shared<CanExecuteSignal>()) {}
 
    Command(const Command&) = delete;
    Command& operator=(const Command&) = delete;
    // Non-movable: a Command's identity is tied to its `can_signal_` and
    // (for Command<>) the auto-tracking Effect, which captures a *copy* of
    // the predicate at construction. Allowing moves would let the moved-to
    // Command's `predicate_` diverge from the copy the Effect still calls,
    // and silently re-home reactive plumbing. ViewModels hold Commands as
    // direct members (never moved), exactly like Property / Computed, so
    // deleting move costs nothing and removes a footgun.
    Command(Command&&) = delete;
    Command& operator=(Command&&) = delete;
 
    ~Command() { lifetime_.reset(); }

    void execute(const Args&... args) {
        if (predicate_(args...)) {
            if (::aria::has_trace_sink()) {
                ::aria::publish_trace_unchecked(::aria::TraceCategory::Command,
                    ::aria::trace::Command{"execute"});
            }
            action_(args...);
        } else if (::aria::has_trace_sink()) {
            ::aria::publish_trace_unchecked(::aria::TraceCategory::Command,
                ::aria::trace::Command{"rejected_can_execute"});
        }
    }
 
    void operator()(const Args&... args) { execute(args...); }
 
    [[nodiscard]] bool can_execute(const Args&... args) const {
        return predicate_(args...);
    }

    void notify_can_execute_changed(const Args&... args) const {
        if (::aria::has_trace_sink()) {
            ::aria::publish_trace_unchecked(::aria::TraceCategory::Command, 
                ::aria::trace::Command{"can_execute_changed"});
        }
        can_signal_->emit(predicate_(args...));
    }
 
    [[nodiscard]] Subscription observe_can_execute(std::function<void(bool)> fn) {
        return can_signal_->connect(std::move(fn));
    }
 
private:
    friend class binding::BindingEngine;
    std::weak_ptr<void> lifetime_token_() {
        if (!lifetime_) lifetime_ = std::make_shared<char>();
        return lifetime_;
    }
    Action action_;
    Predicate predicate_;
    std::shared_ptr<CanExecuteSignal> can_signal_;
    std::shared_ptr<void> lifetime_;
};
 
// ----------------------------------------------------------------------------
//  Command<> specialisation: parameterless predicate can be auto-tracked.
//
//  The predicate is wrapped in an `Effect`; every reactive read inside it
//  becomes an upstream edge, and the `Effect` re-fires whenever any of
//  those upstreams changes, emitting the fresh `can_execute()` on the
//  signal. As a result `BindingEngine::bind_command(cmd, button)` is
//  enough for the button's `enabled` to stay in sync with model state —
//  callers no longer need to sprinkle `notify_can_execute_changed()` in
//  their setters. This is the behaviour the docs describe.
// ----------------------------------------------------------------------------
template<>
class Command<> {
public:
    using Action = std::function<void()>;
    using Predicate = std::function<bool()>;
    using CanExecuteSignal = detail::TypedSignal<bool>;
 
    template<std::invocable<> A>
    explicit Command(A&& action)
        : action_(std::forward<A>(action)),
          predicate_([]() noexcept { return true; }),
          can_signal_(std::make_shared<CanExecuteSignal>()) {
        // `can_execute` is a constant `true`; no Effect needed.
    }
 
    template<std::invocable<> A, std::predicate<> P>
    Command(A&& action, P&& predicate)
        : action_(std::forward<A>(action)),
          predicate_(std::forward<P>(predicate)),
          can_signal_(std::make_shared<CanExecuteSignal>()) {
        // ── Eager auto-tracking contract ─────────────────────────────
        // We install a reactive `Effect` right here in the constructor.
        // The Effect runs the predicate exactly once synchronously, under
        // a TrackingContext, so every reactive value it reads becomes an
        // upstream edge. Subsequent changes to any of those upstreams
        // re-fire the Effect, which then emits on `can_signal_` **only
        // when the truth value actually flips** (equality gate).
        //
        // What this means for callers:
        //   * The predicate executes **once** during construction.
        //     It must therefore be safe to run at that moment — every
        //     Property / Computed it touches via `this->member` must
        //     already be fully constructed. Because C++ initialises
        //     non-static data members in declaration order, this is
        //     satisfied iff the Command<> is declared **after** every
        //     Property / Computed whose values its predicate reads.
        //     (Standard MVVM style already does this.)
        //   * Predicate should be side-effect free. Tracking is eager
        //     rather than lazy so that `can_execute()` is authoritative
        //     from the moment the Command exists and observers attached
        //     later do not need a priming emit.
        //   * The Effect stays alive for the lifetime of the Command,
        //     independent of any UI binding. This is intentional: a
        //     Command owns its own reactive plumbing so a ViewModel
        //     doesn't have to wire / unwire it in activate / deactivate.
        //     The cost is O(deps) shared_ptr / edge nodes; there is NO
        //     per-change work while upstreams stay stable.
        auto signal = can_signal_;
        auto last   = std::make_shared<bool>();
        effect_.emplace(
            [pred = predicate_, signal, last,
             primed = std::make_shared<bool>(false)]() mutable {
                const bool now = pred();
                if (!*primed) {
                    // First (eager) run: seed the cache and register
                    // every tracked source, but do NOT emit — no one
                    // can have observed us yet, and callers that
                    // connect later should read `can_execute()`
                    // synchronously to get the current state.
                    *primed = true;
                    *last   = now;
                    return;
                }
                if (*last != now) {
                    *last = now;
                    signal->emit(now);
                }
            });
    }
 
    Command(const Command&) = delete;
    Command& operator=(const Command&) = delete;
    // Non-movable — see the primary template. The auto-tracking Effect
    // captures a copy of the predicate, so a move would desync it.
    Command(Command&&) = delete;
    Command& operator=(Command&&) = delete;
 
    ~Command() { lifetime_.reset(); }
 
    void execute() {
        if (predicate_()) {
            if (::aria::has_trace_sink()) {
                ::aria::publish_trace_unchecked(::aria::TraceCategory::Command,
                    ::aria::trace::Command{"execute"});
            }
            action_();
        } else if (::aria::has_trace_sink()) {
            ::aria::publish_trace_unchecked(::aria::TraceCategory::Command,
                ::aria::trace::Command{"rejected_can_execute"});
        }
    }
 
    void operator()() { execute(); }
 
    [[nodiscard]] bool can_execute() const { return predicate_(); }

    void notify_can_execute_changed() const {
        if (::aria::has_trace_sink()) {
            ::aria::publish_trace_unchecked(::aria::TraceCategory::Command,
                ::aria::trace::Command{"can_execute_changed"});
        }
        can_signal_->emit(predicate_());
    }
 
    [[nodiscard]] Subscription observe_can_execute(std::function<void(bool)> fn) {
        return can_signal_->connect(std::move(fn));
    }
 
private:
    friend class binding::BindingEngine;
    std::weak_ptr<void> lifetime_token_() {
        if (!lifetime_) lifetime_ = std::make_shared<char>();
        return lifetime_;
    }
    Action action_;
    Predicate predicate_;
    std::shared_ptr<CanExecuteSignal> can_signal_;
    // Effect owns the reactive node. `std::optional<Effect>` rather than a
    // bare `Effect` so the default-true-predicate constructor can leave it
    // empty (no auto-tracking node installed) without paying for a dummy
    // Effect. The `std::nullopt` state represents "no auto-tracking effect
    // was installed".
    std::optional<reactive::Effect> effect_;
    std::shared_ptr<void> lifetime_;
};
 
}  // namespace aria