pgsql-jellyfin/MediaBrowser.Controller/Persistence/IItemRepository.cs

// <copyright file="IItemRepository.cs" company="PlaceholderCompany">
// Copyright (c) PlaceholderCompany. All rights reserved.
// </copyright>

#nullable disable

#pragma warning disable CS1591

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Data.Enums;
using Jellyfin.Database.Implementations.Entities;
using MediaBrowser.Controller.Entities;
using MediaBrowser.Controller.Entities.Audio;
using MediaBrowser.Model.Dto;
using MediaBrowser.Model.Querying;

namespace MediaBrowser.Controller.Persistence;

/// <summary>
/// Provides an interface to implement an Item repository.
/// </summary>
public interface IItemRepository
{
    /// <summary>
    /// Deletes the item.
    /// </summary>
    /// <param name="ids">The identifier to delete.</param>
    void DeleteItem(params IReadOnlyList<Guid> ids);

    /// <summary>
    /// Deletes the item asynchronously.
    /// </summary>
    /// <param name="ids">The identifier to delete.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the async operation.</returns>
    Task DeleteItemAsync(IReadOnlyList<Guid> ids, CancellationToken cancellationToken = default);

    /// <summary>
    /// Saves the items.
    /// </summary>
    /// <param name="items">The items.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    void SaveItems(IReadOnlyList<BaseItem> items, CancellationToken cancellationToken);

    /// <summary>
    /// Saves the items asynchronously.
    /// </summary>
    /// <param name="items">The items.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the async operation.</returns>
    Task SaveItemsAsync(IReadOnlyList<BaseItem> items, CancellationToken cancellationToken = default);

    Task SaveImagesAsync(BaseItem item, CancellationToken cancellationToken = default);

    /// <summary>
    /// Reattaches the user data to the item.
    /// </summary>
    /// <param name="item">The item.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task that represents the asynchronous reattachment operation.</returns>
    Task ReattachUserDataAsync(BaseItem item, CancellationToken cancellationToken);

    /// <summary>
    /// Retrieves the item.
    /// </summary>
    /// <param name="id">The id.</param>
    /// <returns>BaseItem.</returns>
    BaseItem RetrieveItem(Guid id);

    /// <summary>
    /// Retrieves the item asynchronously.
    /// </summary>
    /// <param name="id">The id.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the async operation.</returns>
    Task<BaseItem> RetrieveItemAsync(Guid id, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the items.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <returns>QueryResult&lt;BaseItem&gt;.</returns>
    QueryResult<BaseItem> GetItems(InternalItemsQuery filter);

    /// <summary>
    /// Gets the items asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>QueryResult&lt;BaseItem&gt;.</returns>
    Task<QueryResult<BaseItem>> GetItemsAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the item ids list.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <returns>List&lt;Guid&gt;.</returns>
    IReadOnlyList<Guid> GetItemIdsList(InternalItemsQuery filter);

    /// <summary>
    /// Gets the item ids list asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>List&lt;Guid&gt;.</returns>
    Task<IReadOnlyList<Guid>> GetItemIdsListAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the item list.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <returns>List&lt;BaseItem&gt;.</returns>
    IReadOnlyList<BaseItem> GetItemList(InternalItemsQuery filter);

    /// <summary>
    /// Gets the item list asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>List&lt;BaseItem&gt;.</returns>
    Task<IReadOnlyList<BaseItem>> GetItemListAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the item list. Used mainly by the Latest api endpoint.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="collectionType">Collection Type.</param>
    /// <returns>List&lt;BaseItem&gt;.</returns>
    IReadOnlyList<BaseItem> GetLatestItemList(InternalItemsQuery filter, CollectionType collectionType);

    /// <summary>
    /// Gets the item list asynchronously. Used mainly by the Latest api endpoint.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="collectionType">Collection Type.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the async operation.</returns>
    Task<IReadOnlyList<BaseItem>> GetLatestItemListAsync(InternalItemsQuery filter, CollectionType collectionType, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the list of series presentation keys for next up.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="dateCutoff">The minimum date for a series to have been most recently watched.</param>
    /// <returns>The list of keys.</returns>
    IReadOnlyList<string> GetNextUpSeriesKeys(InternalItemsQuery filter, DateTime dateCutoff);

    /// <summary>
    /// Gets the list of series presentation keys for next up asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="dateCutoff">The minimum date for a series to have been most recently watched.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the async operation.</returns>
    Task<IReadOnlyList<string>> GetNextUpSeriesKeysAsync(InternalItemsQuery filter, DateTime dateCutoff, CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates the inherited values.
    /// </summary>
    void UpdateInheritedValues();

    int GetCount(InternalItemsQuery filter);

    /// <summary>
    /// Gets the count of items asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The count.</returns>
    Task<int> GetCountAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    ItemCounts GetItemCounts(InternalItemsQuery filter);

    /// <summary>
    /// Gets the item counts asynchronously.
    /// </summary>
    /// <param name="filter">The query.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The item counts.</returns>
    Task<ItemCounts> GetItemCountsAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetGenres(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetGenresAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetMusicGenres(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetMusicGenresAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetStudios(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetStudiosAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetArtists(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetArtistsAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAlbumArtists(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetAlbumArtistsAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAllArtists(InternalItemsQuery filter);

    Task<QueryResult<(BaseItem Item, ItemCounts ItemCounts)>> GetAllArtistsAsync(InternalItemsQuery filter, CancellationToken cancellationToken = default);

    IReadOnlyList<string> GetMusicGenreNames();

    Task<IReadOnlyList<string>> GetMusicGenreNamesAsync(CancellationToken cancellationToken = default);

    IReadOnlyList<string> GetStudioNames();

    Task<IReadOnlyList<string>> GetStudioNamesAsync(CancellationToken cancellationToken = default);

    IReadOnlyList<string> GetGenreNames();

    Task<IReadOnlyList<string>> GetGenreNamesAsync(CancellationToken cancellationToken = default);

    IReadOnlyList<string> GetAllArtistNames();

    Task<IReadOnlyList<string>> GetAllArtistNamesAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if an item has been persisted to the database.
    /// </summary>
    /// <param name="id">The id to check.</param>
    /// <returns>True if the item exists, otherwise false.</returns>
    Task<bool> ItemExistsAsync(Guid id);

    /// <summary>
    /// Gets a value indicating wherever all children of the requested Id has been played.
    /// </summary>
    /// <param name="user">The userdata to check against.</param>
    /// <param name="id">The Top id to check.</param>
    /// <param name="recursive">Whever the check should be done recursive. Warning expensive operation.</param>
    /// <returns>A value indicating whever all children has been played.</returns>
    bool GetIsPlayed(User user, Guid id, bool recursive);

    /// <summary>
    /// Gets all artist matches from the db.
    /// </summary>
    /// <param name="artistNames">The names of the artists.</param>
    /// <returns>A map of the artist name and the potential matches.</returns>
    IReadOnlyDictionary<string, MusicArtist[]> FindArtists(IReadOnlyList<string> artistNames);
}