namespace MxGateway.Client;

/// <summary>
/// Server-side filters and shape options for
/// <see cref="GalaxyRepositoryClient.DiscoverHierarchyAsync(DiscoverHierarchyOptions, System.Threading.CancellationToken)"/>.
/// Each property maps directly to the corresponding field on the
/// <c>DiscoverHierarchyRequest</c> proto so the gateway can narrow the
/// hierarchy walk before serializing it back to the client.
/// </summary>
public sealed record DiscoverHierarchyOptions
{
    /// <summary>
    /// Root Galaxy object id to start the walk from. When set, takes
    /// precedence over <see cref="RootTagName"/> and <see cref="RootContainedPath"/>.
    /// </summary>
    public int? RootGobjectId { get; init; }

    /// <summary>
    /// Root tag (assigned) name to start the walk from. Used when
    /// <see cref="RootGobjectId"/> is null.
    /// </summary>
    public string? RootTagName { get; init; }

    /// <summary>
    /// Root contained-name dotted path to start the walk from. Used when
    /// neither <see cref="RootGobjectId"/> nor <see cref="RootTagName"/> are set.
    /// </summary>
    public string? RootContainedPath { get; init; }

    /// <summary>
    /// Maximum traversal depth below the root, inclusive. Leave null for the
    /// server default (unbounded).
    /// </summary>
    public int? MaxDepth { get; init; }

    /// <summary>
    /// Galaxy category ids to include. Empty means all categories.
    /// </summary>
    public IReadOnlyList<int> CategoryIds { get; init; } = Array.Empty<int>();

    /// <summary>
    /// Template tag names that must appear somewhere in each returned
    /// object's template chain. Empty means no template filter.
    /// </summary>
    public IReadOnlyList<string> TemplateChainContains { get; init; } = Array.Empty<string>();

    /// <summary>
    /// Optional glob (e.g. <c>"Tank*"</c>) matched against each object's tag name.
    /// </summary>
    public string? TagNameGlob { get; init; }

    /// <summary>
    /// When set, overrides whether each returned <c>GalaxyObject</c> includes
    /// its dynamic attribute list. Leave null to use the server default.
    /// </summary>
    public bool? IncludeAttributes { get; init; }

    /// <summary>
    /// When true, restrict results to objects that bear at least one configured alarm.
    /// </summary>
    public bool AlarmBearingOnly { get; init; }

    /// <summary>
    /// When true, restrict results to objects that have at least one historized attribute.
    /// </summary>
    public bool HistorizedOnly { get; init; }
}