using Jint.Native;

namespace Jint.Runtime.Interop
{
    /// <summary>
    /// Reference resolver allows customizing behavior for reference resolving. This can be useful in cases where
    /// you want to ignore long chain of property accesses that might throw if anything is null or undefined.
    /// An example of such is <code>var a = obj.field.subField.value</code>. Custom resolver could accept chain to return
    /// null/undefined on first occurrence. 
    /// </summary>
    public interface IReferenceResolver
    {
        /// <summary>
        /// When unresolvable reference occurs, check if another value can be provided instead of it. 
        /// </summary>
        /// <remarks>
        /// A reference error will be thrown if this method return false.
        /// </remarks>
        /// <param name="engine">The current engine instance.</param>
        /// <param name="reference">The reference that is being processed.</param>
        /// <param name="value">Value that should be used instead of undefined.</param>
        /// <returns>Whether to use <paramref name="value" /> instead of undefined.</returns>
        bool TryUnresolvableReference(Engine engine, Reference reference, out JsValue value);

        /// <summary>
        /// When property reference is being processed, resolve to other value if needed.  
        /// </summary>
        /// <param name="engine">The current engine instance.</param>
        /// <param name="reference">The reference that is being processed.</param>
        /// <param name="value">Value that should be used instead of reference target.</param>
        /// <returns>Whether to use <paramref name="value" /> instead of reference's value.</returns>
        bool TryPropertyReference(Engine engine, Reference reference, ref JsValue value);
        
        /// <summary>
        /// When evaluating a function call and a target that is not an object is encountered,
        /// custom implementation can return a value to call. 
        /// </summary>
        /// <remarks>
        /// A reference error will be thrown if this method return false.
        /// </remarks>
        /// <param name="engine">The current engine instance.</param>
        /// <param name="callee">The callee.</param>
        /// <param name="value">Value that should be used when this method return true. Should be <see cref="ICallable"/>.</param>
        /// <returns>Whether to use <paramref name="value" /> instead of undefined.</returns>
        bool TryGetCallable(Engine engine, object callee, out JsValue value);
        
        /// <summary>
        /// Check whether objects property value is valid.
        /// </summary>
        /// <param name="value">The value to check</param>
        /// <returns>Whether to accept the value.</returns>
        bool CheckCoercible(JsValue value);
    }
}