BelongsTo.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../DataBinder/Core.hpp"
#include "../DataBinder/SqlNullValue.hpp"
#include "../SqlColumnTypeDefinitions.hpp"
#include "../Utils.hpp"
#include "Error.hpp"
#include "Field.hpp"
 
namespace Lightweight
{
class SqlStatement;
}
 
#include <compare>
#include <functional>
#include <memory>
#include <optional>
#include <string_view>
#include <type_traits>
 
namespace Lightweight
{
 
/// @brief Helper function to use with std::optional<std::reference_wrapper<T>>
/// like this .transform(Unwrap).value_or({})
auto inline Unwrap = [](auto v) {
    return v.get();
};
 
/// @brief Represents the many-to-one side of a foreign-key relationship.
///
/// This is the record that *owns* the foreign-key column: many records holding a `BelongsTo` may
/// reference the same target record. For a one-to-one relation through a join table, see
/// `HasOneThrough`; for the inverse (one-to-many) side, see `HasMany`.
///
/// The `TheReferencedField` parameter is the field in the other record that references the current record,
/// in the form of `&OtherRecord::Field`.
/// Other Field must be a primary key.
///
/// @tparam TheReferencedField The field in the other record that references the current record.
/// @tparam ColumnNameOverrideString If not an empty string, this value will be used as the column name in the database.
///
/// @ingroup DataMapper
///
/// @code
/// struct User {
///     Field<SqlGuid, PrimaryKey::AutoAssign> id;
///     Field<SqlAnsiString<30>> name;
/// };
/// struct Email {
///     Field<SqlGuid, PrimaryKey::AutoAssign> id;
///     Field<SqlAnsiString<40>> address;
///     BelongsTo<&User::id> user;
///     // Also possible to customize the column name
///     BelongsTo<&User::id, SqlRealName<"the_user_id">, SqlNullable::Null> maybe_user;
/// };
/// @endcode
template <auto TheReferencedField, auto ColumnNameOverrideString = std::nullopt, SqlNullable Nullable = SqlNullable::NotNull>
class BelongsTo
{
  public:
    /// The field in the other record that references the current record.
    static constexpr auto ReferencedField = TheReferencedField;
 
    /// If not an empty string, this value will be used as the column name in the database.
    static constexpr std::string_view ColumnNameOverride = []() consteval {
        if constexpr (!std::same_as<decltype(ColumnNameOverrideString), std::nullopt_t>)
            return std::string_view { ColumnNameOverrideString };
        else
            return std::string_view {};
    }();
 
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
    /// Represents the record type of the other field.
    using ReferencedRecord = MemberClassType<TheReferencedField>;
 
    /// Represents the base column type of the foreign key, matching the primary key of the other record.
    using BaseType = typename[:std::meta::type_of(ReferencedField):] ::ValueType;
 
    static_assert(std::remove_cvref_t<decltype(std::declval<ReferencedRecord>().[:ReferencedField:])>::IsPrimaryKey,
                  "The referenced field must be a primary key.");
#else
    /// Represents the record type of the other field.
    using ReferencedRecord = MemberClassType<decltype(TheReferencedField)>;
 
    static_assert(std::remove_cvref_t<decltype(std::declval<ReferencedRecord>().*ReferencedField)>::IsPrimaryKey,
                  "The referenced field must be a primary key.");
 
    /// Represents the base column type of the foreign key, matching the primary key of the other record.
    using BaseType = std::remove_cvref_t<decltype(std::declval<ReferencedRecord>().*ReferencedField)>::ValueType;
#endif
 
    /// Represents the value type of the foreign key,
    /// which can be either an optional or a non-optional type of the referenced field,
    using ValueType = std::conditional_t<Nullable == SqlNullable::Null, std::optional<BaseType>, BaseType>;
 
    /// Indicates whether this relationship is optional (nullable).
    static constexpr auto IsOptional = Nullable == SqlNullable::Null;
    /// Indicates whether this relationship is mandatory (non-nullable).
    static constexpr auto IsMandatory = !IsOptional;
    /// Indicates that a BelongsTo field is never a primary key.
    static constexpr auto IsPrimaryKey = false;
    /// Indicates that a BelongsTo field is never an auto-increment primary key.
    static constexpr auto IsAutoIncrementPrimaryKey = false;
 
    /// Constructs a new BelongsTo with the given value(s) forwarded to the underlying value type.
    template <typename... S>
        requires std::constructible_from<ValueType, S...>
    constexpr BelongsTo(S&&... value) noexcept:
        _referencedFieldValue(std::forward<S>(value)...)
    {
    }
 
    /// Constructs a new BelongsTo from the given referenced record, copying its primary key.
    constexpr BelongsTo(ReferencedRecord const& other) noexcept:
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
        _referencedFieldValue { (other.[:ReferencedField:]).Value() },
#else
        _referencedFieldValue { (other.*ReferencedField).Value() },
#endif
        _loaded { true },
        _record { std::make_unique<ReferencedRecord>(other) }
    {
    }
 
    /// Copy constructor.
    constexpr BelongsTo(BelongsTo const& other) noexcept:
        _referencedFieldValue(other._referencedFieldValue),
        _loader(std::move(other._loader)),
        _loaded(other._loaded),
        _modified(other._modified),
        _record(other._record ? std::make_unique<ReferencedRecord>(*other._record) : nullptr),
        _loadError(other._loadError)
    {
    }
 
    /// Move constructor.
    constexpr BelongsTo(BelongsTo&& other) noexcept:
        _referencedFieldValue(std::move(other._referencedFieldValue)),
        _loader(std::move(other._loader)),
        _loaded(other._loaded),
        _modified(other._modified),
        _record(std::move(other._record)),
        _loadError(other._loadError)
    {
    }
 
    /// Assigns NULL to the relationship, clearing the loaded record.
    BelongsTo& operator=(SqlNullType /*nullValue*/) noexcept
    {
        if (!_referencedFieldValue)
            return *this;
        _loaded = false;
        _record.reset();
        _loadError.reset();
        _referencedFieldValue = {};
        _modified = true;
        return *this;
    }
 
    /// Assigns a bare foreign-key value, updating the foreign key and marking the field modified.
    ///
    /// This is the sibling of Field<T>::operator=(S&&). Without it, `record.fk = someKeyValue`
    /// would bind to the converting constructor plus move-assignment, and the temporary's
    /// default-constructed `_modified` (false) would be copied over this field — leaving the
    /// change invisible to DataMapper::Update(), which gates its SET clause on IsModified().
    ///
    /// Any previously loaded record is dropped, since it no longer corresponds to the new key.
    ///
    /// @param value The referenced record's primary-key value to point at.
    /// @return Reference to this field.
    template <typename S>
        requires(std::constructible_from<ValueType, S> && !std::same_as<std::remove_cvref_t<S>, BelongsTo>
                 && !std::same_as<std::remove_cvref_t<S>, ReferencedRecord>
                 && !std::same_as<std::remove_cvref_t<S>, SqlNullType>)
    constexpr BelongsTo& operator=(S&& value) noexcept
    {
        _referencedFieldValue = ValueType { std::forward<S>(value) };
        _loaded = false;
        _record.reset();
        _loadError.reset();
        _modified = true;
        return *this;
    }
 
    /// Assigns a referenced record, updating the foreign key and loaded state.
    BelongsTo& operator=(ReferencedRecord& other)
    {
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
        if (_referencedFieldValue == (other.[:ReferencedField:]).Value())
#else
        if (_referencedFieldValue == (other.*ReferencedField).Value())
#endif
            return *this;
        _loaded = true;
        _record = std::make_unique<ReferencedRecord>(other);
        _loadError.reset();
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
        _referencedFieldValue = (other.[:ReferencedField:]).Value();
#else
        _referencedFieldValue = (other.*ReferencedField).Value();
#endif
        _modified = true;
        return *this;
    }
 
    /// Copy assignment operator.
    BelongsTo& operator=(BelongsTo const& other)
    {
        if (this == &other)
            return *this;
 
        _referencedFieldValue = other._referencedFieldValue;
        _loader = std::move(other._loader);
        _loaded = other._loaded;
        _modified = other._modified;
        _record = other._record ? std::make_unique<ReferencedRecord>(*other._record) : nullptr;
        _loadError = other._loadError;
 
        return *this;
    }
 
    /// Move assignment operator.
    BelongsTo& operator=(BelongsTo&& other) noexcept
    {
        if (this == &other)
            return *this;
        _referencedFieldValue = std::move(other._referencedFieldValue);
        _loader = std::move(other._loader);
        _loaded = other._loaded;
        _modified = other._modified;
        _record = std::move(other._record);
        _loadError = other._loadError;
        other._loaded = false;
        return *this;
    }
 
    ~BelongsTo() noexcept = default;
 
    /// Marks the field as modified or unmodified.
    LIGHTWEIGHT_FORCE_INLINE constexpr void SetModified(bool value) noexcept
    {
        _modified = value;
    }
 
    /// Checks if the field is modified.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr bool IsModified() const noexcept
    {
        return _modified;
    }
 
    /// Retrieves the reference to the value of the field.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ValueType const& Value() const noexcept
    {
        return _referencedFieldValue;
    }
 
    /// Retrieves the mutable reference to the value of the field.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ValueType& MutableValue() noexcept
    {
        return _referencedFieldValue;
    }
 
    // NOLINTBEGIN(cppcoreguidelines-missing-std-forward)
 
    /// @brief Retrieves the referenced record, loading it on first access.
    ///
    /// Never throws for an unavailable record: the reason comes back as the error instead.
    ///
    /// @return The record; or @ref RelationError::NotFound when the foreign key is NULL or points at no
    ///         row, @ref RelationError::NotConfigured when there is no loader (a hand-built record, or
    ///         one read with `loadRelations = false`), @ref RelationError::Outdated when the default
    ///         connection string changed since the record was read, @ref RelationError::QueryFailed when
    ///         the load query failed.
    template <typename Self>
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr auto Record(this Self&& self) -> RelationResult<std::reference_wrapper<
        std::conditional_t<std::is_const_v<std::remove_reference_t<Self>>, ReferencedRecord const, ReferencedRecord>>>
    {
        using Target =
            std::conditional_t<std::is_const_v<std::remove_reference_t<Self>>, ReferencedRecord const, ReferencedRecord>;
        return self.Load().transform([&self] { return std::reference_wrapper<Target> { *self._record }; });
    }
 
    /// @brief Retrieves the referenced record. Only available when the relationship is mandatory.
    /// @throws SqlRequireLoadedError The record is unavailable; see @ref Record() for the reasons, which
    ///         reports them without throwing.
    template <typename Self>
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord& operator*(this Self&& self)
        requires(IsMandatory)
    {
        self.LoadOrThrow();
        return *self._record;
    }
 
    /// @brief Retrieves the referenced record. Only available when the relationship is mandatory.
    /// @throws SqlRequireLoadedError The record is unavailable; see @ref Record() for the reasons, which
    ///         reports them without throwing.
    template <typename Self>
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord* operator->(this Self&& self)
        requires(IsMandatory)
    {
        self.LoadOrThrow();
        return self._record.get();
    }
 
    // NOLINTEND(cppcoreguidelines-missing-std-forward)
 
    /// Checks if the field value is NULL.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr bool operator!() const noexcept
    {
        return !_referencedFieldValue;
    }
 
    /// Checks if the field value is not NULL.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr explicit operator bool() const noexcept
    {
        return static_cast<bool>(_referencedFieldValue);
    }
 
    /// @brief Returns the already-loaded referenced record, or `nullptr` when none is loaded.
    ///
    /// Unlike `Record()`, this never runs the on-demand loader: it reports what is present right
    /// now. That is what lets the batched relation loading walk one level deeper (`With<A, B>()`)
    /// without turning the walk itself into the N+1 it exists to remove.
    ///
    /// @return Pointer to the loaded record, or `nullptr` if the relation is unloaded or NULL.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord* LoadedRecord() noexcept
    {
        return _record.get();
    }
 
    /// @copydoc LoadedRecord()
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord const* LoadedRecord() const noexcept
    {
        return _record.get();
    }
 
    /// Emplaces a record into the relationship. This will mark the relationship as loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord& EmplaceRecord()
    {
        _loaded = true;
        _loadError.reset();
        _record = std::make_unique<ReferencedRecord>();
        return *_record;
    }
 
    /// Adopts an eagerly fetched referenced record, marking the relationship loaded.
    ///
    /// This is the sink for a record that was already read from the database, as opposed to
    /// `operator=(ReferencedRecord&)`, which *establishes* the relationship and therefore rewrites
    /// the foreign key and sets the modified flag. Here the foreign key is already whatever the row
    /// said it was, so it is deliberately left untouched and the field stays unmodified - adopting a
    /// fetched value is not a pending change to be written back.
    ///
    /// An empty @p record leaves the relationship unloaded rather than clearing the foreign key: a
    /// mandatory relationship whose target row is missing is a data-integrity problem to be
    /// surfaced by the accessor, not silently turned into NULL.
    ///
    /// @param record The fetched record, or `std::nullopt` if the referenced row was absent.
    LIGHTWEIGHT_FORCE_INLINE void AdoptFetchedRecord(std::optional<ReferencedRecord> record)
    {
        if (!record.has_value())
            return;
 
        _record = std::make_unique<ReferencedRecord>(std::move(record).value());
        _loaded = true;
        _loadError.reset();
    }
 
    /// Binds the foreign key value to the given output column index on the statement.
    template <typename Stmt>
    LIGHTWEIGHT_FORCE_INLINE void BindOutputColumn(SQLSMALLINT outputIndex, Stmt& stmt)
    {
        stmt.BindOutputColumn(outputIndex, &_referencedFieldValue);
    }
 
    /// Three-way comparison operator.
    std::weak_ordering operator<=>(BelongsTo const& other) const noexcept
    {
        return _referencedFieldValue <=> other.Value();
    }
 
    /// Three-way comparison operator with a Field.
    template <detail::FieldElementType T, PrimaryKey IsPrimaryKeyValue = PrimaryKey::No>
    std::weak_ordering operator<=>(Field<T, IsPrimaryKeyValue> const& other) const noexcept
    {
        return _referencedFieldValue <=> other.Value();
    }
 
    /// Equality comparison operator.
    bool operator==(BelongsTo const& other) const noexcept
    {
        return (_referencedFieldValue <=> other.Value()) == std::weak_ordering::equivalent;
    }
 
    /// Inequality comparison operator.
    bool operator!=(BelongsTo const& other) const noexcept
    {
        return (_referencedFieldValue <=> other.Value()) != std::weak_ordering::equivalent;
    }
 
    /// Equality comparison operator with a Field.
    template <detail::FieldElementType T, PrimaryKey IsPrimaryKeyValue = PrimaryKey::No>
    bool operator==(Field<T, IsPrimaryKeyValue> const& other) const noexcept
    {
        return (_referencedFieldValue <=> other.Value()) == std::weak_ordering::equivalent;
    }
 
    /// Inequality comparison operator with a Field.
    template <detail::FieldElementType T, PrimaryKey IsPrimaryKeyValue = PrimaryKey::No>
    bool operator!=(Field<T, IsPrimaryKeyValue> const& other) const noexcept
    {
        return (_referencedFieldValue <=> other.Value()) != std::weak_ordering::equivalent;
    }
 
    /// Carries the deferred load, installed by the DataMapper.
    struct Loader
    {
        /// Loads the referenced record: @ref RelationError::NotFound when there is none.
        std::function<RelationResult<ReferencedRecord>()> loadReference {};
    };
 
    /// Used internally to configure on-demand loading of the record.
    void SetAutoLoader(Loader loader) noexcept
    {
        _loader = std::move(loader);
    }
 
  private:
    /// Loads the record unless it already is, or its unavailability is already known.
    ///
    /// @ref RelationError::NotFound and @ref RelationError::Outdated are remembered - neither changes by
    /// asking again - until the foreign key is re-pointed; a failed query is retried on the next access.
    [[nodiscard]] RelationResult<void> Load() const
    {
        if (_loaded)
            return {};
        if (_loadError)
            return std::unexpected { *_loadError };
        if constexpr (IsOptional)
            if (!_referencedFieldValue)
                return std::unexpected { RelationError::NotFound };
        if (!_loader.loadReference)
            return std::unexpected { RelationError::NotConfigured };
 
        auto loaded = _loader.loadReference();
        if (!loaded)
        {
            if (loaded.error() != RelationError::QueryFailed)
                _loadError = loaded.error();
            return std::unexpected { loaded.error() };
        }
        _record = std::make_unique<ReferencedRecord>(std::move(*loaded));
        _loaded = true;
        return {};
    }
 
    void LoadOrThrow() const
    {
        if (auto const loaded = Load(); !loaded)
            throw SqlRequireLoadedError(Reflection::TypeNameOf<std::remove_cvref_t<decltype(*this)>>, loaded.error());
    }
 
    ValueType _referencedFieldValue {};
    Loader _loader {};
    mutable bool _loaded = false;
    bool _modified = false;
    mutable std::unique_ptr<ReferencedRecord> _record {};
    mutable std::optional<RelationError> _loadError {};
};
 
template <auto ReferencedField, auto ColumnNameOverrideString, SqlNullable Nullable>
std::ostream& operator<<(std::ostream& os, BelongsTo<ReferencedField, ColumnNameOverrideString, Nullable> const& belongsTo)
{
    return os << belongsTo.Value();
}
 
namespace detail
{
    template <typename T>
    struct IsBelongsToType: std::false_type
    {
    };
 
    template <auto ReferencedField, auto ColumnNameOverrideString, SqlNullable Nullable>
    struct IsBelongsToType<BelongsTo<ReferencedField, ColumnNameOverrideString, Nullable>>: std::true_type
    {
    };
 
} // namespace detail
 
template <typename T>
constexpr bool IsBelongsTo = detail::IsBelongsToType<std::remove_cvref_t<T>>::value;
 
template <typename T>
concept is_belongs_to = IsBelongsTo<T>;
 
template <typename T>
constexpr bool IsOptionalBelongsTo = false;
 
template <is_belongs_to T>
constexpr bool IsOptionalBelongsTo<T> = T::IsOptional;
 
template <auto ReferencedField, auto ColumnNameOverrideString, SqlNullable Nullable>
struct SqlDataBinder<BelongsTo<ReferencedField, ColumnNameOverrideString, Nullable>>
{
    using SelfType = BelongsTo<ReferencedField, ColumnNameOverrideString, Nullable>;
    using InnerType = SelfType::ValueType;
 
    static constexpr auto ColumnType = SqlDataBinder<InnerType>::ColumnType;
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN InputParameter(SQLHSTMT stmt,
                                                             SQLUSMALLINT column,
                                                             SelfType const& value,
                                                             SqlDataBinderCallback& cb)
    {
        return SqlDataBinder<InnerType>::InputParameter(stmt, column, value.Value(), cb);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN
    OutputColumn(SQLHSTMT stmt, SQLUSMALLINT column, SelfType* result, SQLLEN* indicator, SqlDataBinderCallback& cb)
    {
        auto const sqlReturn = SqlDataBinder<InnerType>::OutputColumn(stmt, column, &result->MutableValue(), indicator, cb);
        cb.PlanPostProcessOutputColumn([result]() { result->SetModified(true); });
        return sqlReturn;
    }
 
    /// @throws Whatever `SqlDataBinder<InnerType>::GetColumn` throws — this forwards to an arbitrary
    ///         binder and cannot promise more than the one it wraps.
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN
    GetColumn(SQLHSTMT stmt, SQLUSMALLINT column, SelfType* result, SQLLEN* indicator, SqlDataBinderCallback const& cb)
    {
        auto const sqlReturn = SqlDataBinder<InnerType>::GetColumn(stmt, column, &result->MutableValue(), indicator, cb);
        if (SQL_SUCCEEDED(sqlReturn))
            result->SetModified(true);
        return sqlReturn;
    }
};
 
} // namespace Lightweight