// Copyright (c) Microsoft. All rights reserved.

using System;
using System.Diagnostics.CodeAnalysis;
using Microsoft.Agents.AI.Workflows.Checkpointing;

namespace Microsoft.Agents.AI.Workflows;

/// <summary>
/// Represents a request from an external input port.
/// </summary>
/// <param name="PortInfo">The port invoked.</param>
/// <param name="RequestId">The unique identifier of the corresponding request.</param>
/// <param name="Data">The data contained in the response.</param>
public record ExternalResponse(RequestPortInfo PortInfo, string RequestId, PortableValue Data)
{
    /// <summary>
    /// Determines whether the underlying data is of the specified type.
    /// </summary>
    /// <typeparam name="TValue">The type to compare with the underlying data.</typeparam>
    /// <returns>true if the underlying data is of type TValue; otherwise, false.</returns>
    public bool IsDataOfType<TValue>() => this.Data.Is<TValue>();

    /// <summary>
    /// Determines whether the underlying data can be retrieved as the specified type.
    /// </summary>
    /// <typeparam name="TValue">The type to which the underlying data is to be cast if available.</typeparam>
    /// <param name="value">When this method returns, contains the value of type <typeparamref name="TValue"/> if the data is
    /// available and compatible.</param>
    /// <returns>true if the data is present and can be cast to <typeparamref name="TValue"/>; otherwise, false.</returns>
    public bool TryGetDataAs<TValue>([NotNullWhen(true)] out TValue? value) => this.Data.Is(out value);

    /// <summary>
    /// Attempts to retrieve the underlying data as the specified type.
    /// </summary>
    /// <param name="targetType">The type to which the data should be cast or converted.</param>
    /// <param name="value">When this method returns <see langword="true"/>, contains the value of type
    /// <paramref name="targetType"/> if the data is available and compatible.</param>
    /// <returns>true if the data is present and can be cast to <paramref name="targetType"/>; otherwise, false.</returns>
    public bool TryGetDataAs(Type targetType, [NotNullWhen(true)] out object? value) => this.Data.IsType(targetType, out value);
}
