using System;

namespace Svrnty.CQRS.Events.Abstractions.Models;

/// <summary>
/// Metadata about a persistent event stream.
/// </summary>
/// <remarks>
/// Provides information about the stream's current state, including its length,
/// retention policy, and the oldest event still available in the stream.
/// </remarks>
public sealed record StreamMetadata
{
    /// <summary>
    /// The name of the stream.
    /// </summary>
    public required string StreamName { get; init; }

    /// <summary>
    /// The current length of the stream (total number of events).
    /// </summary>
    /// <remarks>
    /// This represents the highest offset + 1. For example, if the stream has events
    /// at offsets 0-99, the length is 100.
    /// </remarks>
    public required long Length { get; init; }

    /// <summary>
    /// The offset of the oldest event still available in the stream.
    /// </summary>
    /// <remarks>
    /// Due to retention policies, older events may have been deleted.
    /// This indicates the earliest offset that can still be read.
    /// </remarks>
    public required long OldestEventOffset { get; init; }

    /// <summary>
    /// The timestamp of the oldest event still available in the stream.
    /// </summary>
    /// <remarks>
    /// Useful for monitoring retention policy effectiveness and data age.
    /// Null if the stream is empty.
    /// </remarks>
    public DateTimeOffset? OldestEventTimestamp { get; init; }

    /// <summary>
    /// The timestamp of the newest (most recent) event in the stream.
    /// </summary>
    /// <remarks>
    /// Null if the stream is empty.
    /// </remarks>
    public DateTimeOffset? NewestEventTimestamp { get; init; }

    /// <summary>
    /// The retention policy for this stream, if configured.
    /// </summary>
    /// <remarks>
    /// Specifies how long events should be retained before deletion.
    /// Null means no time-based retention (events retained indefinitely or until other policies apply).
    /// </remarks>
    public TimeSpan? RetentionPolicy { get; init; }

    /// <summary>
    /// Indicates whether this is an empty stream.
    /// </summary>
    public bool IsEmpty => Length == 0;

    /// <summary>
    /// The total number of events that have been deleted from this stream due to retention policies.
    /// </summary>
    /// <remarks>
    /// Helps track data retention and compliance with data lifecycle policies.
    /// </remarks>
    public long DeletedEventCount { get; init; }
}