structecs 0.4.0

use std::{
    fmt::Debug,
    ops::Deref,
    ptr::NonNull,
    sync::{Arc, Weak},
};

use crate::{Extractable, entity::EntityData};

/// A smart pointer to a component that keeps the entity data alive.
///
/// `Acquirable<T>` provides transparent access to component `T` through `Deref`,
/// while maintaining ownership of the underlying entity data via reference counting.
///
/// # Thread Safety
///
/// `Acquirable<T>` implements `Send` and `Sync` when `T: Send + Sync`, allowing
/// safe sharing across threads. The internal reference counting is handled by `Arc`,
/// which provides thread-safe access to immutable data.
///
/// # Examples
///
/// ```
/// use structecs::*;
///
/// #[derive(Extractable)]
/// struct Player {
///     name: String,
///     health: u32,
/// }
///
/// let player = Acquirable::new(Player {
///     name: "Alice".to_string(),
///     health: 100,
/// });
///
/// // Access via Deref
/// assert_eq!(player.name, "Alice");
/// ```
pub struct Acquirable<T: Extractable> {
    target: NonNull<T>,
    pub(crate) inner: Arc<EntityData>,
}

/// A weak reference to an entity's component.
///
/// `WeakAcquirable<T>` does not keep the entity alive and must be upgraded
/// to an `Acquirable<T>` to access the component data.
///
/// This is useful for preventing circular references and implementing
/// cache-like structures.
///
/// # Thread Safety
///
/// `WeakAcquirable<T>` implements `Send` and `Sync` when `T: Send + Sync`,
/// allowing weak references to be safely shared and transferred across threads.
///
/// # Examples
///
/// ```
/// use structecs::*;
///
/// #[derive(Extractable)]
/// struct Entity {
///     id: u32,
/// }
///
/// let entity = Acquirable::new(Entity { id: 42 });
/// let weak = entity.downgrade();
///
/// // Entity is still alive
/// assert!(weak.upgrade().is_some());
///
/// drop(entity);
///
/// // Entity has been dropped
/// assert!(weak.upgrade().is_none());
/// ```
pub struct WeakAcquirable<T: Extractable> {
    inner: Weak<EntityData>,
    _marker: std::marker::PhantomData<T>,
}

impl<T: Extractable> Acquirable<T> {
    pub fn new(target: T) -> Self {
        let data = Arc::new(EntityData::new(target, crate::get_extractor::<T>()));
        Acquirable::new_raw(data.data.cast(), data)
    }

    /// Create an `Acquirable<T>` from a value of type `U` that contains `T`.
    ///
    /// This is a compile-time checked version that validates the type relationship
    /// between `U` and `T` at compile time (in debug builds).
    ///
    /// # Compile-time Guarantees
    ///
    /// In debug builds, this function includes a compile-time check that ensures
    /// `U` contains `T` as an extractable component. The check is based on type
    /// metadata generated by the `#[derive(Extractable)]` macro.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity { id: u32 }
    ///
    /// #[derive(Extractable)]
    /// #[extractable(entity)]
    /// struct Player {
    ///     entity: Entity,
    ///     name: String
    /// }
    ///
    /// let player_data = Player {
    ///     entity: Entity { id: 42 },
    ///     name: "Steve".to_string(),
    /// };
    ///
    /// // Create Acquirable<Entity> from Player
    /// let entity: Acquirable<Entity> = Acquirable::new_checked(player_data);
    /// assert_eq!(entity.id, 42);
    /// ```
    ///
    /// # Panics
    ///
    /// In debug builds, panics at compile-time if `U` does not contain `T`
    /// as an extractable component.
    pub fn new_checked<U: Extractable>(target: U) -> Acquirable<T> {
        #[cfg(debug_assertions)]
        const {
            if !crate::ExtractionMetadata::is_has::<U, T>() {
                panic!("Type U must contain T as extractable component")
            }
        }
        let data = Arc::new(EntityData::new(target, crate::get_extractor::<U>()));
        // SAFETY: unwrap_unchecked is safe here because:
        // 1. The compile-time check above (in debug builds) ensures U contains T in its metadata
        // 2. extract_ptr returns None only when the type is not found in the metadata
        // 3. Since U contains T by construction (verified at compile-time), extract_ptr<T>()
        //    will always return Some(ptr)
        // 4. In release builds, incorrect usage is caught by the debug build tests
        let extracted = unsafe { data.extract_ptr::<T>().unwrap_unchecked() };
        Acquirable::new_raw(extracted, data)
    }

    #[inline(always)]
    pub(crate) fn new_raw(target: NonNull<T>, inner: Arc<EntityData>) -> Self {
        Self { target, inner }
    }

    /// Extract a component with compile-time type relationship checking.
    ///
    /// This is a compile-time checked version of [`extract`](Self::extract) that
    /// validates the type relationship at compile time (in debug builds) and panics
    /// instead of returning `None`.
    ///
    /// # Compile-time Guarantees
    ///
    /// In debug builds, this function includes a compile-time check that ensures
    /// `T` contains `U` as an extractable component. The check is based on type
    /// metadata generated by the `#[derive(Extractable)]` macro.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Health { value: u32 }
    ///
    /// #[derive(Extractable)]
    /// #[extractable(health)]
    /// struct Player {
    ///     name: String,
    ///     health: Health,
    /// }
    ///
    /// let player = Acquirable::new(Player {
    ///     name: "Alice".to_string(),
    ///     health: Health { value: 100 },
    /// });
    ///
    /// // Compile-time checked extraction
    /// let health: Acquirable<Health> = player.extract_checked::<Health>();
    /// assert_eq!(health.value, 100);
    ///
    /// // This would cause a compile-time panic in debug builds:
    /// // let other = player.extract_checked::<OtherType>();
    /// ```
    ///
    /// # Panics
    ///
    /// In debug builds, panics at compile-time if `T` does not contain `U`
    /// as an extractable component.
    ///
    /// # See Also
    ///
    /// - [`extract`](Self::extract) - Returns `Option<Acquirable<U>>` for runtime checking
    pub fn extract_checked<U: Extractable>(&self) -> Acquirable<U> {
        #[cfg(debug_assertions)]
        const {
            if !crate::ExtractionMetadata::is_has::<T, U>() {
                panic!("Type T must contain U as extractable component")
            }
        }
        // SAFETY: unwrap_unchecked is safe here because:
        // 1. The compile-time check above (in debug builds) ensures T contains U in its metadata
        // 2. The EntityData was created with an Extractor that knows about all extractable types
        // 3. extract_ptr returns None only when the type is not in the metadata
        // 4. Since T contains U (verified at compile-time), extract_ptr<U>() always returns Some(ptr)
        // 5. The pointer is valid as long as `self.inner` is alive, which is guaranteed by Arc
        let extracted = unsafe { self.inner.extract_ptr::<U>().unwrap_unchecked() };
        Acquirable::new_raw(extracted, self.inner.clone())
    }

    /// Extract a different component type from the same entity.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Health {
    ///     value: u32,
    /// }
    ///
    /// #[derive(Extractable)]
    /// #[extractable(health)]
    /// struct Player {
    ///     name: String,
    ///     health: Health,
    /// }
    ///
    /// let player = Acquirable::new(Player {
    ///     name: "Alice".to_string(),
    ///     health: Health { value: 100 },
    /// });
    ///
    /// let health = player.extract::<Health>().unwrap();
    /// assert_eq!(health.value, 100);
    /// ```
    #[inline(always)]
    pub fn extract<U: Extractable>(&self) -> Option<Acquirable<U>> {
        // SAFETY: extract_ptr performs type checking via the Extractor
        // and only returns a pointer if type U exists in the entity.
        let extracted = unsafe { self.inner.extract_ptr::<U>()? };
        Some(Acquirable::new_raw(extracted, self.inner.clone()))
    }

    /// Create a weak reference to this entity's component.
    ///
    /// The weak reference does not keep the entity alive and can be upgraded
    /// back to an `Acquirable` if the entity still exists.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity {
    ///     id: u32,
    /// }
    ///
    /// let entity = Acquirable::new(Entity { id: 42 });
    /// let weak = entity.downgrade();
    ///
    /// assert!(weak.upgrade().is_some());
    /// ```
    #[inline(always)]
    pub fn downgrade(&self) -> WeakAcquirable<T> {
        WeakAcquirable {
            inner: Arc::downgrade(&self.inner),
            _marker: std::marker::PhantomData,
        }
    }

    /// Check if two `Acquirable` pointers point to the same entity data.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity {
    ///     id: u32,
    /// }
    ///
    /// let entity1 = Acquirable::new(Entity { id: 42 });
    /// let entity2 = entity1.clone();
    /// let entity3 = Acquirable::new(Entity { id: 42 });
    ///
    /// assert!(entity1.ptr_eq(&entity2));
    /// assert!(!entity1.ptr_eq(&entity3));
    /// ```
    #[inline(always)]
    pub fn ptr_eq<U: Extractable>(&self, other: &Acquirable<U>) -> bool {
        Arc::ptr_eq(&self.inner, &other.inner)
    }

    /// Get the number of strong references to the entity data.
    ///
    /// This is only available in debug builds for debugging purposes.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity {
    ///     id: u32,
    /// }
    ///
    /// let entity = Acquirable::new(Entity { id: 42 });
    ///
    /// #[cfg(debug_assertions)]
    /// {
    ///     assert_eq!(entity.strong_count(), 1);
    ///     let entity2 = entity.clone();
    ///     assert_eq!(entity.strong_count(), 2);
    /// }
    /// ```
    #[cfg(debug_assertions)]
    #[inline(always)]
    pub fn strong_count(&self) -> usize {
        Arc::strong_count(&self.inner)
    }

    /// Get the number of weak references to the entity data.
    ///
    /// This is only available in debug builds for debugging purposes.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity {
    ///     id: u32,
    /// }
    ///
    /// let entity = Acquirable::new(Entity { id: 42 });
    ///
    /// #[cfg(debug_assertions)]
    /// {
    ///     assert_eq!(entity.weak_count(), 0);
    ///     let weak = entity.downgrade();
    ///     assert_eq!(entity.weak_count(), 1);
    /// }
    /// ```
    #[cfg(debug_assertions)]
    #[inline(always)]
    pub fn weak_count(&self) -> usize {
        Arc::weak_count(&self.inner)
    }
}

impl<T: Extractable> WeakAcquirable<T> {
    /// Upgrade the weak reference to an `Acquirable` if the entity is still alive.
    ///
    /// Returns `None` if the entity has been dropped.
    ///
    /// # Examples
    ///
    /// ```
    /// use structecs::*;
    ///
    /// #[derive(Extractable)]
    /// struct Entity {
    ///     id: u32,
    /// }
    ///
    /// let entity = Acquirable::new(Entity { id: 42 });
    /// let weak = entity.downgrade();
    ///
    /// // Entity is still alive
    /// assert!(weak.upgrade().is_some());
    ///
    /// drop(entity);
    ///
    /// // Entity has been dropped
    /// assert!(weak.upgrade().is_none());
    /// ```
    #[inline(always)]
    pub fn upgrade(&self) -> Option<Acquirable<T>> {
        let inner = self.inner.upgrade()?;
        // SAFETY: unwrap_unchecked is safe here because:
        // 1. WeakAcquirable<T> was created from an Acquirable<T> via downgrade()
        // 2. The original Acquirable<T> was created with EntityData that contains type T
        // 3. EntityData is immutable after creation - its type structure never changes
        // 4. Therefore, if upgrade() succeeds (Arc is still alive), extract_ptr<T>()
        //    will always find T in the same location it was originally stored
        // 5. The returned pointer is valid for the lifetime of the upgraded Arc
        Some(Acquirable::new_raw(
            unsafe { inner.extract_ptr::<T>().unwrap_unchecked() },
            inner,
        ))
    }
}

impl<T: Extractable> Clone for Acquirable<T> {
    #[inline(always)]
    fn clone(&self) -> Self {
        Self {
            target: self.target,
            inner: self.inner.clone(),
        }
    }
}

impl<T: Extractable> Deref for Acquirable<T> {
    type Target = T;

    #[inline(always)]
    fn deref(&self) -> &Self::Target {
        unsafe { self.target.as_ref() }
    }
}

impl<T: Extractable + Debug> Debug for Acquirable<T> {
    #[inline(always)]
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Acquirable")
            .field("target", &**self)
            .finish()
    }
}

// SAFETY: Acquirable<T> can be safely sent between threads if T: Send + Sync.
//
// Thread-safety guarantees:
// - The `target` field is a NonNull<T> pointer that points into EntityData's heap allocation.
//   The data is immutable after creation (no interior mutability), so shared references
//   are safe across threads when T: Sync.
// - The `inner` field is an Arc<EntityData>, which provides thread-safe reference counting.
//   Arc already implements Send when T: Send + Sync.
// - Since T is accessed only through shared references (via Deref), we require T: Sync.
// - We also require T: Send because the underlying data may be moved between threads
//   when the last Arc is dropped on a different thread than where it was created.
unsafe impl<T: Extractable + Send + Sync> Send for Acquirable<T> {}
unsafe impl<T: Extractable + Send + Sync> Sync for Acquirable<T> {}

impl<T: Extractable> Clone for WeakAcquirable<T> {
    #[inline(always)]
    fn clone(&self) -> Self {
        Self {
            inner: self.inner.clone(),
            _marker: std::marker::PhantomData,
        }
    }
}

// SAFETY: WeakAcquirable<T> can be safely sent between threads if T: Send + Sync.
//
// Thread-safety guarantees:
// - The `inner` field is a Weak<EntityData>, which provides thread-safe weak reference counting.
//   Weak already implements Send when T: Send + Sync.
// - WeakAcquirable does not directly hold any data; it only holds a weak reference.
//   When upgraded to Acquirable<T>, the same Send + Sync bounds apply.
// - The PhantomData<T> marker is zero-sized and does not affect thread safety.
// - We require T: Send + Sync for the same reasons as Acquirable<T>: the underlying
//   data must be safely transferable and shareable across threads.
unsafe impl<T: Extractable + Send + Sync> Send for WeakAcquirable<T> {}
unsafe impl<T: Extractable + Send + Sync> Sync for WeakAcquirable<T> {}