Merge pull request #3199 from Nexus-Mods/replace-mod-in-place-v2

Added: Replace Library Items Atomically in Place & Other Library Refactorings

Author: Al12rs

src/NexusMods.Abstractions.Jobs/IJobMonitor.cs

@@ -12,15 +12,15 @@ public interface IJobMonitor
     /// Starts a job given the job definition and the code to run as part of the job.
     /// </summary>
     IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(TJobType job, Func<IJobContext<TJobType>, ValueTask<TResultType>> task)
-        where TJobType : IJobDefinition<TResultType> 
+        where TJobType : IJobDefinition<TResultType>
         where TResultType : notnull;
-    
-    
+
+
     /// <summary>
     /// Starts a job given the job definition.
     /// </summary>
     IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(TJobType job)
-        where TJobType : IJobDefinitionWithStart<TJobType, TResultType> 
+        where TJobType : IJobDefinitionWithStart<TJobType, TResultType>
         where TResultType : notnull;
 
     /// <summary>

src/NexusMods.Abstractions.Library/ILibraryService.cs

@@ -13,7 +13,8 @@
 namespace NexusMods.Abstractions.Library;
 
 /// <summary>
-/// Represents the library.
+/// Represents the library, this class provides access to various functionalities
+/// that are accessible from within a 'library' related view.
 /// </summary>
 [PublicAPI]
 public interface ILibraryService
@@ -28,30 +29,171 @@ public interface ILibraryService
     /// </summary>
     IJobTask<IAddLocalFile, LocalFile.ReadOnly> AddLocalFile(AbsolutePath absolutePath);
 
+    /// <summary>
+    /// Returns all loadouts that contain the given library item.
+    /// </summary>
+    /// <param name="libraryItem">The item to search for.</param>
+    /// <remarks>
+    ///     The loadout and linked item to the current item.
+    /// </remarks>
+    IEnumerable<(Loadout.ReadOnly loadout, LibraryLinkedLoadoutItem.ReadOnly linkedItem)> LoadoutsWithLibraryItem(LibraryItem.ReadOnly libraryItem);
+
     /// <summary>
     /// Adds a library file.
     /// </summary>
     Task<LibraryFile.New> AddLibraryFile(ITransaction transaction, AbsolutePath source);
 
     /// <summary>
     /// Installs a library item into a target loadout.
+    /// To remove an installed item, use <see cref="RemoveLinkedItemFromLoadout"/>.
     /// </summary>
     /// <param name="libraryItem">The item to install.</param>
     /// <param name="targetLoadout">The target loadout.</param>
     /// <param name="parent">If specified the installed item will be placed in this group, otherwise it will default to the user's local collection</param>
     /// <param name="installer">The Library will use this installer to install the item</param>
-    /// <param name="fallbackInstaller">Fallback installer instead of the default advanced installer</param>
-    IJobTask<IInstallLoadoutItemJob, LoadoutItemGroup.ReadOnly> InstallItem(
+    /// <param name="fallbackInstaller">The installer to use if the default installer fails</param>
+    /// <param name="transaction">The transaction to attach the installation to. Install is only completed when transaction is completed.</param>
+    /// <remarks>
+    /// Job returns a result with null <see cref="LoadoutItemGroup.ReadOnly"/> after
+    /// if supplied an external transaction via <paramref name="transaction"/>,
+    /// since it is the caller's responsibility to complete that transaction.
+    /// </remarks>
+    IJobTask<IInstallLoadoutItemJob, InstallLoadoutItemJobResult> InstallItem(
         LibraryItem.ReadOnly libraryItem,
         LoadoutId targetLoadout,
         Optional<LoadoutItemGroupId> parent = default,
         ILibraryItemInstaller? installer = null,
-        ILibraryItemInstaller? fallbackInstaller = null);
+        ILibraryItemInstaller? fallbackInstaller = null,
+        ITransaction? transaction = null);
 
     /// <summary>
     /// Removes a number of items from the library.
+    /// This will automatically unlink the loadouts from the items are part of.
     /// </summary>
     /// <param name="libraryItems">The items to remove from the library.</param>
     /// <param name="gcRunMode">Defines how the garbage collector should be run</param>
-    Task RemoveItems(IEnumerable<LibraryItem.ReadOnly> libraryItems, GarbageCollectorRunMode gcRunMode = GarbageCollectorRunMode.RunAsynchronously);
+    Task RemoveLibraryItems(IEnumerable<LibraryItem.ReadOnly> libraryItems, GarbageCollectorRunMode gcRunMode = GarbageCollectorRunMode.RunAsynchronously);
+
+    /// <summary>
+    /// Removes a single linked loadout item from its loadout,
+    /// managing the transaction automatically.
+    /// </summary>
+    /// <param name="itemId">The ID of the linked loadout item to remove from the loadout.</param>
+    Task RemoveLinkedItemFromLoadout(LibraryLinkedLoadoutItemId itemId);
+
+    /// <summary>
+    /// Removes multiple linked loadout items from their loadout,
+    /// managing the transaction automatically.
+    /// </summary>
+    /// <param name="itemIds">The IDs of the linked loadout items to remove from their loadout.</param>
+    Task RemoveLinkedItemsFromLoadout(IEnumerable<LibraryLinkedLoadoutItemId> itemIds);
+
+    /// <summary>
+    /// Removes a single linked loadout item from a loadout,
+    /// using the provided transaction.
+    /// </summary>
+    /// <param name="itemId">The ID of the linked loadout item to remove from its loadout.</param>
+    /// <param name="tx">Existing transaction to use for this operation.</param>
+    void RemoveLinkedItemFromLoadout(LibraryLinkedLoadoutItemId itemId, ITransaction tx);
+
+    /// <summary>
+    /// Removes multiple linked loadout items from their loadout,
+    /// using the provided transaction.
+    /// </summary>
+    /// <param name="itemIds">The IDs of the linked loadout items to remove from their loadout.</param>
+    /// <param name="tx">Existing transaction to use for this operation.</param>
+    void RemoveLinkedItemsFromLoadout(IEnumerable<LibraryLinkedLoadoutItemId> itemIds, ITransaction tx);
+
+    /// <summary>
+    /// Removes all linked loadout items from all loadouts,
+    /// using the provided transaction.
+    /// </summary>
+    /// <param name="libraryItems">The library items whose associated linked loadout items should be removed.</param>
+    /// <param name="tx">Existing transaction to use for this operation.</param>
+    void RemoveLinkedItemsFromAllLoadouts(IEnumerable<LibraryItem.ReadOnly> libraryItems, ITransaction tx);
+
+    /// <summary>
+    /// Removes all linked loadout items from all loadouts,
+    /// managing the transaction automatically.
+    /// </summary>
+    /// <param name="libraryItems">The library items whose associated linked loadout items should be removed.</param>
+    Task RemoveLinkedItemsFromAllLoadouts(IEnumerable<LibraryItem.ReadOnly> libraryItems);
+
+    /// <summary>
+    /// Replaces linked loadout items across all loadouts with installations of a different library item.   
+    /// </summary>
+    /// <param name="oldItem">The library item whose linked loadout items should be replaced.</param>
+    /// <param name="newItem">The replacement library item from which to install the new linked loadout items from.</param>
+    /// <param name="options">Options controlling how to replace the linked loadout items.</param>
+    /// <param name="tx">The transaction to use for this operation.</param>
+    /// <returns>
+    ///     A result indicating success or failure of the replacement operation.
+    /// </returns>
+    ValueTask<LibraryItemReplacementResult> ReplaceLinkedItemsInAllLoadouts(LibraryItem.ReadOnly oldItem, LibraryItem.ReadOnly newItem, ReplaceLibraryItemOptions options, ITransaction tx);
+
+    /// <summary>
+    /// Replaces multiple sets of linked loadout items across all loadouts with new versions.
+    /// </summary>
+    /// <param name="replacements">The pairs of library items (old and new) whose linked loadout items should be replaced.</param>
+    /// <param name="options">Options controlling how to replace the linked loadout items.</param>
+    /// <param name="tx">The transaction to use for this operation.</param>
+    /// <returns>
+    ///     A result indicating success or failure of the replacement operation.
+    /// </returns>
+    ValueTask<LibraryItemReplacementResult> ReplaceLinkedItemsInAllLoadouts(IEnumerable<(LibraryItem.ReadOnly oldItem, LibraryItem.ReadOnly newItem)> replacements, ReplaceLibraryItemsOptions options, ITransaction tx);
+    
+    /// <summary>
+    /// Replaces multiple sets of linked loadout items across all loadouts with new versions,
+    /// managing the transaction automatically.
+    /// </summary>
+    /// <param name="replacements">The pairs of library items (old and new) whose linked loadout items should be replaced.</param>
+    /// <param name="options">Options controlling how to replace the linked loadout items.</param>
+    /// <returns>
+    ///     A result indicating success or failure of the replacement operation.
+    /// </returns>
+    ValueTask<LibraryItemReplacementResult> ReplaceLinkedItemsInAllLoadouts(IEnumerable<(LibraryItem.ReadOnly oldItem, LibraryItem.ReadOnly newItem)> replacements, ReplaceLibraryItemsOptions options);
+}
+
+/// <summary>
+/// Represents the result of a <see cref="ILibraryService.ReplaceLinkedItemsInAllLoadouts(NexusMods.Abstractions.Library.Models.LibraryItem.ReadOnly,NexusMods.Abstractions.Library.Models.LibraryItem.ReadOnly,NexusMods.Abstractions.Library.ReplaceLibraryItemOptions,NexusMods.MnemonicDB.Abstractions.ITransaction)"/> operation.
+/// </summary>
+public enum LibraryItemReplacementResult
+{
+    /// <summary>
+    /// The operation was successful.
+    /// </summary>
+    Success,
+
+    /// <summary>
+    /// The operation failed (unknown reason).
+    /// </summary>
+    FailedUnknownReason,
+}
+
+/// <summary>
+/// Options for the <see cref="ILibraryService.ReplaceLinkedItemsInAllLoadouts(NexusMods.Abstractions.Library.Models.LibraryItem.ReadOnly,NexusMods.Abstractions.Library.Models.LibraryItem.ReadOnly,NexusMods.Abstractions.Library.ReplaceLibraryItemOptions,NexusMods.MnemonicDB.Abstractions.ITransaction)"/>
+/// API.
+/// </summary>
+public struct ReplaceLibraryItemOptions
+{
+    /// <summary>
+    /// Skips items in ReadOnly collections such as collections from Nexus Mods.
+    /// </summary>
+    public bool IgnoreReadOnlyCollections { get; set; }
+}
+
+/// <summary>
+/// Options controlling how multiple sets of linked loadout items are replaced across loadouts.
+/// </summary>
+public struct ReplaceLibraryItemsOptions
+{
+    /// <summary>
+    /// Skips items in ReadOnly collections such as collections from Nexus Mods.
+    /// </summary>
+    public bool IgnoreReadOnlyCollections { get; set; }
+    
+    /// <summary>
+    /// Gets the <see cref="ReplaceLibraryItemOptions"/> for this <see cref="ReplaceLibraryItemsOptions"/>
+    /// </summary>
+    public ReplaceLibraryItemOptions ToReplaceLibraryItemOptions() => new() { IgnoreReadOnlyCollections = IgnoreReadOnlyCollections };
 }

src/NexusMods.Abstractions.Library/Jobs/IInstallLoadoutItemJob.cs

@@ -2,13 +2,14 @@
 using NexusMods.Abstractions.Library.Installers;
 using NexusMods.Abstractions.Library.Models;
 using NexusMods.Abstractions.Loadouts;
+using NexusMods.MnemonicDB.Abstractions;
 
 namespace NexusMods.Abstractions.Library.Jobs;
 
 /// <summary>
 /// A job that installs a library item to a loadout
 /// </summary>
-public interface IInstallLoadoutItemJob : IJobDefinition<LoadoutItemGroup.ReadOnly>
+public interface IInstallLoadoutItemJob : IJobDefinition<InstallLoadoutItemJobResult>
 {
     /// <summary>
     /// The library item to install
@@ -30,3 +31,15 @@ public interface IInstallLoadoutItemJob : IJobDefinition<LoadoutItemGroup.ReadOn
     /// </summary>
     public ILibraryItemInstaller? Installer { get; }
 }
+
+/// <summary>
+/// The result of installing a loadout item via the <see cref="IInstallLoadoutItemJob"/>.
+/// This struct holds a <see cref="LoadoutItemGroup"/> for the item which was just installed.
+///
+/// If the value is 'null' then the job was attached to an existing, external transaction
+/// to be part of a larger atomic operation.
+/// (Done by passing an <see cref="ITransaction"/> transaction to the job.)
+/// This is because the value is not yet available; as the transaction
+/// needs to be externally committed by the caller.
+/// </summary>
+public record struct InstallLoadoutItemJobResult(LoadoutItemGroup.ReadOnly? LoadoutItemGroup);

src/NexusMods.Abstractions.Loadouts/Models/LibraryLinkedLoadoutItem.cs

@@ -21,4 +21,13 @@ public partial class LibraryLinkedLoadoutItem : IModelDefinition
     /// The linked library item.
     /// </summary>
     public static readonly ReferenceAttribute<LibraryItem> LibraryItem = new(Namespace, nameof(LibraryItem)) { IsIndexed = true };
+
+    public readonly partial struct ReadOnly
+    {
+        /// <summary>
+        /// Tries converting this entity to a <see cref="LoadoutItem"/> entity,
+        /// if the entity is not a <see cref="LoadoutItem"/> entity, it returns false.
+        /// </summary>
+        public LoadoutItem.ReadOnly AsLoadoutItem() => new(Db, Id);
+    }
 }

src/NexusMods.App.UI/Pages/Library/LibraryItemRemover.cs

@@ -1,57 +1,31 @@
-using Microsoft.Extensions.DependencyInjection;
 using NexusMods.Abstractions.Library;
 using NexusMods.Abstractions.Library.Models;
-using NexusMods.Abstractions.Loadouts;
 using NexusMods.App.UI.Overlays;
 using NexusMods.App.UI.Overlays.LibraryDeleteConfirmation;
 using NexusMods.MnemonicDB.Abstractions;
-using NexusMods.MnemonicDB.Abstractions.IndexSegments;
-using NexusMods.MnemonicDB.Abstractions.TxFunctions;
 namespace NexusMods.App.UI.Pages.Library;
 
 /// <summary>
 ///     Utility helper class for removing a set of library items from inside a ViewModel.
 /// </summary>
 /// <remarks>
-///     This is here to help easier migration to new LoadoutItems based library UI
-///     when the time comes.
+///     This wraps the actual removal from loadouts and user facing UI confirmation
+///     into a single operation, so you can call this from anywhere and not have to
+///     worry too much about it.
 /// </remarks>
 public static class LibraryItemRemover
 {
     public static async Task RemoveAsync(
         IConnection conn,
         IOverlayController overlayController,
         ILibraryService libraryService,
-        LibraryItem.ReadOnly[] toRemove,
-        CancellationToken cancellationToken = default)
+        LibraryItem.ReadOnly[] toRemove)
     {
         var warnings = LibraryItemDeleteWarningDetector.Process(conn, toRemove);
         var alphaWarningViewModel = LibraryItemDeleteConfirmationViewModel.FromWarningDetector(warnings);
         alphaWarningViewModel.Controller = overlayController;
         var result = await overlayController.EnqueueAndWait(alphaWarningViewModel);
-        if (!result) return;
-
         if (result)
-        {
-            // Note(sewer) Can the person reviewing this code let me know their opinion of
-            // whether this should be inlined into LibraryService or not?
-            var loadouts = Loadout.All(conn.Db).ToArray();
-            using var tx = conn.BeginTransaction();
-            
-            // Note. A loadout may technically still be updated in the background via the CLI,
-            // However this is unlikelu, and the possibility of a concurrent update
-            // is always possible, as long as we show a blocking dialog to the user.
-            foreach (var itemInLoadout in warnings.ItemsInLoadouts)
-            {
-                foreach (var loadout in loadouts)
-                {
-                    foreach (var loadoutItem in loadout.GetLoadoutItemsByLibraryItem(itemInLoadout))
-                        tx.Delete(loadoutItem, recursive: true);
-                }
-            }
-            
-            await tx.Commit();
-            await libraryService.RemoveItems(toRemove);
-        }
+            await libraryService.RemoveLibraryItems(toRemove);
     }
 }

src/NexusMods.App.UI/Pages/LibraryPage/LibraryViewModel.cs

@@ -315,7 +315,7 @@ private async ValueTask RemoveSelectedItems(CancellationToken cancellationToken)
     {
         var db = _connection.Db;
         var toRemove = GetSelectedIds().Select(id => LibraryItem.Load(db, id)).ToArray();
-        await LibraryItemRemover.RemoveAsync(_connection, _serviceProvider.GetRequiredService<IOverlayController>(), _libraryService, toRemove, cancellationToken);
+        await LibraryItemRemover.RemoveAsync(_connection, _serviceProvider.GetRequiredService<IOverlayController>(), _libraryService, toRemove);
     }
 
     private async ValueTask AddFilesFromDisk(IStorageProvider storageProvider, CancellationToken cancellationToken)

src/NexusMods.App.UI/Pages/LoadoutPage/LoadoutViewModel.cs

@@ -7,6 +7,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using NexusMods.Abstractions.Collections;
 using NexusMods.Abstractions.Games;
+using NexusMods.Abstractions.Library;
 using NexusMods.Abstractions.Loadouts;
 using NexusMods.Abstractions.Loadouts.Extensions;
 using NexusMods.App.UI.Controls;
@@ -20,7 +21,6 @@
 using NexusMods.Icons;
 using NexusMods.MnemonicDB.Abstractions;
 using NexusMods.MnemonicDB.Abstractions.ElementComparers;
-using NexusMods.MnemonicDB.Abstractions.TxFunctions;
 using ObservableCollections;
 using OneOf;
 using R3;
@@ -39,6 +39,7 @@ public class LoadoutViewModel : APageViewModel<ILoadoutViewModel>, ILoadoutViewM
     public ReactiveCommand<Unit> CollectionToggleCommand { get; }
 
     public LoadoutTreeDataGridAdapter Adapter { get; }
+    public ILibraryService _LibraryService;
 
     [Reactive] public bool IsCollection { get; private set; } 
     [Reactive] public bool IsCollectionEnabled { get; private set; }
@@ -65,6 +66,7 @@ public LoadoutViewModel(
 
         Adapter = new LoadoutTreeDataGridAdapter(serviceProvider, loadoutFilter);
 
+        _LibraryService = serviceProvider.GetRequiredService<ILibraryService>();
         var connection = serviceProvider.GetRequiredService<IConnection>();
 
         if (collectionGroupId.HasValue)
@@ -177,17 +179,11 @@ public LoadoutViewModel(
                     .SelectMany(static itemModel => GetLoadoutItemIds(itemModel))
                     .ToHashSet()
                     .Where(id => !IsRequired(id, connection))
+                    .Select(x => (LibraryLinkedLoadoutItemId)x.Value)
                     .ToArray();
 
                 if (ids.Length == 0) return;
-                using var tx = connection.BeginTransaction();
-
-                foreach (var id in ids)
-                {
-                    tx.Delete(id, recursive: true);
-                }
-
-                await tx.Commit();
+                await _LibraryService.RemoveLinkedItemsFromLoadout(ids);
             },
             awaitOperation: AwaitOperation.Sequential,
             initialCanExecute: false,

src/NexusMods.App.UI/Pages/MyGames/MyGamesViewModel.cs

@@ -236,7 +236,7 @@ private async Task RemoveGame(GameInstallation installation, bool shouldDeleteDo
         await installation.GetGame().Synchronizer.UnManage(installation);
 
         if (!shouldDeleteDownloads) return;
-        await _libraryService.RemoveItems(filesToDelete.Select(file => file.AsLibraryItem()));
+        await _libraryService.RemoveLibraryItems(filesToDelete.Select(file => file.AsLibraryItem()));
 
         foreach (var collection in collections)
         {