using ZB.MOM.WW.ScadaBridge.Commons.Entities.Schemas;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;

/// <summary>
/// Data access for the central <c>SharedSchemas</c> JSON-Schema library table.
/// One row per named schema; the
/// unique <see cref="SharedSchema.Name"/> is the lookup key used by the <c>lib:Name</c>
/// <c>$ref</c> resolver.
/// </summary>
public interface ISharedSchemaRepository
{
    /// <summary>
    /// Inserts <paramref name="schema"/> and returns the store-generated
    /// <see cref="SharedSchema.Id"/>.
    /// </summary>
    /// <param name="schema">The schema to persist.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to the generated identity of the inserted row.</returns>
    Task<int> AddAsync(SharedSchema schema, CancellationToken ct = default);

    /// <summary>
    /// Returns the row for the given id, or <c>null</c> if none exists.
    /// </summary>
    /// <param name="id">The identity to look up.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to the matching <see cref="SharedSchema"/>, or <c>null</c>.</returns>
    Task<SharedSchema?> GetByIdAsync(int id, CancellationToken ct = default);

    /// <summary>
    /// Returns the row whose <see cref="SharedSchema.Name"/> matches
    /// <paramref name="name"/>, or <c>null</c> if none exists.
    /// </summary>
    /// <param name="name">The unique schema name to look up.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to the matching <see cref="SharedSchema"/>, or <c>null</c>.</returns>
    Task<SharedSchema?> GetByNameAsync(string name, CancellationToken ct = default);

    /// <summary>
    /// Returns all schemas ordered by <see cref="SharedSchema.Name"/>.
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to every library entry, name-ordered.</returns>
    Task<IReadOnlyList<SharedSchema>> ListAsync(CancellationToken ct = default);

    /// <summary>
    /// Persists the current state of <paramref name="schema"/> (matched by
    /// <see cref="SharedSchema.Id"/>).
    /// </summary>
    /// <param name="schema">The entity whose changes to persist.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task UpdateAsync(SharedSchema schema, CancellationToken ct = default);

    /// <summary>
    /// Deletes the row with the given id; a no-op if none exists.
    /// </summary>
    /// <param name="id">The identity to delete.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task DeleteAsync(int id, CancellationToken ct = default);
}
