HasOneThrough.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../SqlStatement.hpp"
#include "../Utils.hpp"
#include "Error.hpp"
#include "Record.hpp"
 
#include <compare>
#include <memory>
#include <type_traits>
 
namespace Lightweight
{
 
/// @brief Represents a one-to-one relationship through a join table.
///
/// The `OtherTable` parameter is the record reached through the join table.
/// The `ThroughSpec` parameter is the join table, which references the current record. It is named
/// with the @ref Through marker, so that the reader can tell it apart from the referenced record:
///
/// @code
/// struct Account;
/// struct AccountHistory;
/// struct Supplier
/// {
///     Field<int, PrimaryKey::AutoAssign> id;
///     HasOneThrough<AccountHistory, Through<Account>> accountHistory;
/// };
/// @endcode
///
/// Both foreign keys are located by matching the relationship *type*. When either record holds more
/// than one foreign key into the same table, name the column to single one out - see
/// the RelationSelector concept and the example on @ref HasManyThrough.
///
/// @tparam OtherTable The record type reached through the join table.
/// @tparam ThroughSpec The join record, wrapped as `Through<T>`. Naming the record bare is deprecated.
/// @tparam TheOwnerSelector Singles out the join record's foreign key pointing at the *owning* record.
/// @tparam TheThroughSelector Singles out @p OtherTable's foreign key pointing at the join record.
///
/// @see DataMapper, Field, HasManyThrough, Through, RelationSelector
/// @ingroup DataMapper
template <typename OtherTable,
          typename ThroughSpec,
          auto TheOwnerSelector = AutoDetectRelation,
          auto TheThroughSelector = AutoDetectRelation>
class HasOneThrough
{
    static_assert(RelationSelector<TheOwnerSelector> && RelationSelector<TheThroughSelector>,
                  "The selector template arguments of HasOneThrough must be foreign key column names "
                  "(a SqlRealName) or std::nullopt to resolve the relationship automatically.");
 
    static_assert(!IsThrough<OtherTable>,
                  "The referenced record of HasOneThrough must not be wrapped in Through<>, "
                  "only the join record is.");
 
  public:
    /// The record type of the "through" side of the relationship.
    using ThroughRecord = ThroughRecordOf<ThroughSpec>;
 
    /// The record type of the "Other" side of the relationship.
    using ReferencedRecord = OtherTable;
 
    /// Singles out the join record's foreign key pointing at the record owning this relationship.
    static constexpr auto OwnerSelector = TheOwnerSelector;
 
    /// Singles out @ref ReferencedRecord's foreign key pointing at @ref ThroughRecord.
    static constexpr auto ThroughSelector = TheThroughSelector;
 
    // clang-format off
 
    /// Emplaces the given record into this relationship.
    LIGHTWEIGHT_FORCE_INLINE constexpr void EmplaceRecord(std::shared_ptr<ReferencedRecord> record) { _record = std::move(record); }
 
    /// Retrieves the record in this relationship.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord& Record() noexcept { RequireLoaded(); return *_record.get(); }
 
    /// Retrieves the record in this relationship.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord const& Record() const noexcept { RequireLoaded(); return *_record.get(); }
 
    /// Checks if the record is loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr bool IsLoaded() const noexcept { return _record.get() != nullptr; }
 
    /// Unloads the record from memory.
    LIGHTWEIGHT_FORCE_INLINE void Unload() noexcept { _record.reset(); }
 
    /// @brief Retrieves the record in this relationship.
    /// @note On-demand loads the record if it is not already loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord& operator*() noexcept { RequireLoaded(); return *_record; }
 
    /// @brief Retrieves the record in this relationship.
    /// @note On-demand loads the record if it is not already loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord const& operator*() const noexcept { RequireLoaded(); return *_record; }
 
    /// @brief Retrieves the record in this relationship.
    /// @note On-demand loads the record if it is not already loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord* operator->() noexcept { RequireLoaded(); return _record.get(); }
 
    /// @brief Retrieves the record in this relationship.
    /// @note On-demand loads the record if it is not already loaded.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ReferencedRecord const* operator->() const noexcept { RequireLoaded(); return _record.get(); }
    // clang-format on
 
    /// Default three-way comparison operator.
    std::weak_ordering operator<=>(HasOneThrough const& other) const noexcept = default;
 
    struct Loader
    {
        std::function<std::shared_ptr<ReferencedRecord>()> loadReference {};
    };
 
    /// Used internally to configure on-demand loading of the record.
    void SetAutoLoader(Loader loader)
    {
        _loader = std::move(loader);
    }
 
  private:
    void RequireLoaded() const
    {
        if (IsLoaded())
            return;
 
        if (_loader.loadReference)
            _record = _loader.loadReference();
 
        if (!IsLoaded())
            throw SqlRequireLoadedError { Reflection::TypeNameOf<std::remove_cvref_t<decltype(*this)>> };
    }
 
    Loader _loader {};
 
    // We use shared_ptr to not require ReferencedRecord to be declared before HasOneThrough.
    mutable std::shared_ptr<ReferencedRecord> _record {};
};
 
namespace detail
{
    template <typename T>
    struct IsHasOneThrough: std::false_type
    {
    };
 
    template <typename OtherTable, typename ThroughSpec, auto OwnerSelector, auto ThroughSelector>
    struct IsHasOneThrough<HasOneThrough<OtherTable, ThroughSpec, OwnerSelector, ThroughSelector>>: std::true_type
    {
    };
} // namespace detail
 
template <typename T>
constexpr bool IsHasOneThrough = detail::IsHasOneThrough<std::remove_cvref_t<T>>::value;
 
} // namespace Lightweight