using System;

namespace Quadarax.Foundation.Core.Object.Dynamic
{
    /// <summary>
    /// Defines the interface for dynamic objects that support runtime property management.
    /// </summary>
    /// <remarks>
    /// This interface provides a contract for objects that can have their properties
    /// dynamically added, accessed, and modified at runtime.
    /// </remarks>
    public interface IDyna : ICloneable
    {
        /// <summary>
        /// Gets the value of a property as a specified type.
        /// </summary>
        /// <typeparam name="TValue">The type to convert the property value to.</typeparam>
        /// <param name="propertyName">The name of the property to get the value from.</param>
        /// <returns>The value of the property cast to the specified type, or null if the property value is null.</returns>
        /// <exception cref="ArgumentOutOfRangeException">Thrown when the property does not exist.</exception>
        TValue? GetValue<TValue>(string propertyName);
        
        /// <summary>
        /// Sets the value of a property.
        /// </summary>
        /// <typeparam name="TValue">The type of the value being set.</typeparam>
        /// <param name="propertyName">The name of the property to set.</param>
        /// <param name="value">The value to set the property to.</param>
        /// <exception cref="ArgumentOutOfRangeException">Thrown when the property does not exist.</exception>
        void SetValue<TValue>(string propertyName, TValue? value);
        
        /// <summary>
        /// Clears all property values, setting them to null.
        /// </summary>
        void Clear();
        
        /// <summary>
        /// Copies all property values from this instance to a target instance.
        /// </summary>
        /// <param name="target">The target instance to copy values to.</param>
        /// <remarks>
        /// This method only copies values for properties that exist in both instances.
        /// It does not create new properties in the target instance.
        /// </remarks>
        void CopyTo(IDyna target);
    }
}