Moved from ISaveable to ISaveable<TState> to provide compile-time type safety, safer JSON deserialization (no type names), and clearer save/restore contracts.

Author: nickpettit

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.11.0] – 2025-09-22
+
+### Breaking Change
+Moved from `ISaveable` to `ISaveable<TState>` to provide compile-time type safety, safer JSON deserialization (no type names), and clearer save/restore contracts. All saveables must now define a serializable `TState` and implement `CaptureState(): TState` and `RestoreState(TState state)`.
+
+### Serialization & Safety
+
+- JSON now deserializes directly to each saveable’s `TState` (no type names emitted), reducing polymorphic-deserialization risk.
+- Existing save files that match the new `TState` shape should continue to load; files that relied on polymorphic `object` states will need a one-time migration.
+
+### Async/Awaitable & Concurrency
+
+- Replaced single-iteration “while not cancelled” wrappers with clear guard clauses.
+- Fixed a rare operation-queue race by making enqueue/start atomic behind a lock; `IsBusy` is reset in a `finally` block.
+- Broader cancellation: operations link `destroyCancellationToken` with `Application.exitCancellationToken`.
+- Exception surfacing: errors are logged and rethrown so callers can observe faults when awaiting.
+- Logging helpers include a Unity context only when on the main thread; background-thread logs remain safe.
+
+### Miscellaneous
+
+- `FileHandler` keeps the public API and formatting; small internal cleanups (consistent use of computed `fullPath`, clearer errors on delete).
+- Updated all Samples to the `ISaveable<TState>` pattern.
+
+### Migration notes
+
+1. Replace ISaveable with `ISaveable<TState>` and define a serializable `TState` (struct or class).
+2. Update methods to `TState CaptureState()` and `void RestoreState(TState state)`.
+
+
 ## [0.10.1] - 2025-08-08
 - Background threads are now disabled by default. Exceptions are not always logged properly when using background threads, causing SaveManager methods to sometimes fail silently if bad data gets passed in (such as a `NullReferenceException` inside of an ISaveable.CaptureState() method). While background threads do increase performance, this should be considered an experimental feature until it's possible to properly catch exceptions while on a background thread.
 - Added try/catch blocks around SaveManager methods to ensure exceptions are logged for async methods.

Runtime/FileHandler.cs

@@ -14,7 +14,7 @@ public class FileHandler : ScriptableObject
         /// Stores the persistent data path for later use, which can only be accessed on the main thread.
         /// </summary>
         protected string m_persistentDataPath;
-        
+
         /// <summary>
         /// The suffix to append to the filename. By default, it is "_editor" when in the Unity Editor, and an empty string in builds.
         /// </summary>
@@ -24,15 +24,15 @@ protected virtual string FilenameSuffix
 #else
             => string.Empty;
 #endif
-        
+
         /// <summary>
         /// The file extension to use for the files. By default, it is ".dat".
         /// </summary>
         protected virtual string FileExtension => ".dat";
-        
+
         protected virtual void OnEnable()
             => m_persistentDataPath = Application.persistentDataPath;
-        
+
         /// <summary>
         /// Validates that the given path or filename is safe and well-formed.
         /// Throws an exception if the path contains invalid characters, is absolute, or attempts directory traversal.
@@ -44,15 +44,13 @@ protected virtual void ValidatePath(string pathOrFilename)
             if (string.IsNullOrWhiteSpace(pathOrFilename))
                 throw new ArgumentException("[Save Async] FileHandler.ValidatePath() - Path or filename cannot be null, empty, or whitespace.", nameof(pathOrFilename));
 
-            // Prevent directory traversal
             if (pathOrFilename.Contains("..") || Path.IsPathRooted(pathOrFilename))
                 throw new ArgumentException("[Save Async] FileHandler.ValidatePath() - Path contains invalid characters or is absolute.", nameof(pathOrFilename));
 
-            // Check for invalid path characters instead of filename characters
             if (pathOrFilename.IndexOfAny(Path.GetInvalidPathChars()) >= 0)
                 throw new ArgumentException("[Save Async] FileHandler.ValidatePath() - Path contains invalid characters.", nameof(pathOrFilename));
         }
-        
+
         /// <summary>
         /// Returns the path to a file using the given path or filename and appends the <see cref="FilenameSuffix"/> and 
         /// <see cref="FileExtension"/> but does not include the persistent data path.
@@ -66,15 +64,15 @@ protected virtual void ValidatePath(string pathOrFilename)
         protected string GetPartialPath(string pathOrFilename)
         {
             ValidatePath(pathOrFilename);
-            
+
             string path = $"{pathOrFilename}{FilenameSuffix}{FileExtension}";
-            
+
             if (SaveManager.SaveSlotIndex > -1)
                 return Path.Combine($"slot{SaveManager.SaveSlotIndex}", path);
 
             return path;
         }
-        
+
         /// <summary>
         /// Returns the full path to a file in the persistent data path using the given path or filename.
         /// <code>
@@ -112,16 +110,14 @@ public virtual async Task WriteFile(string pathOrFilename, string content, Cance
         {
             string fullPath = GetFullPath(pathOrFilename);
 
-            // Get the directory path from the full file path
             string directoryPath = Path.GetDirectoryName(fullPath);
 
-            // Create the directory structure if it doesn't exist
             if (!string.IsNullOrEmpty(directoryPath))
                 Directory.CreateDirectory(directoryPath);
-    
+
             await File.WriteAllTextAsync(fullPath, content, cancellationToken).ConfigureAwait(false);
         }
-        
+
         /// <summary>
         /// Writes the given content to a file at the given path or filename.
         /// <code>
@@ -145,44 +141,29 @@ public virtual async Task WriteFile(string pathOrFilename, string content)
         /// <param name="cancellationToken">The cancellation token should be the same one from the calling MonoBehaviour.</param>
         public virtual async Task<string> ReadFile(string pathOrFilename, CancellationToken cancellationToken)
         {
-            try
-            {
-                string fullPath = GetFullPath(pathOrFilename);
-                
-                // If the file does not exist, return an empty string and log a warning.
-                if (!Exists(pathOrFilename))
-                {
-                    Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - File does not exist at path \"{fullPath}\". This may be expected if the file has not been created yet.");
-                    return string.Empty;
-                }
-                
-                string fileContent = await File.ReadAllTextAsync(GetFullPath(pathOrFilename), cancellationToken).ConfigureAwait(false);
-            
-                // If the file is empty, return an empty string and log a warning.
-                if (string.IsNullOrEmpty(fileContent))
-                {
-                    if (SaveManager.SaveSlotIndex > -1)
-                        Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - The file \"{pathOrFilename}\" in slot index {SaveManager.SaveSlotIndex} was empty. This may be expected if the file has been erased.");
-                    else
-                        Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - The file \"{pathOrFilename}\" was empty. This may be expected if the file has been erased.");
-                    
-                    return string.Empty;
-                }
-                
-                return fileContent;
-            }
-            catch (UnauthorizedAccessException ex)
+            string fullPath = GetFullPath(pathOrFilename);
+
+            if (!File.Exists(fullPath))
             {
-                Debug.LogError($"[Save Async] FileHandler.ReadFile() - Access denied to file \"{pathOrFilename}\": {ex.Message}");
+                Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - File does not exist at path \"{fullPath}\". This may be expected if the file has not been created yet.");
                 return string.Empty;
             }
-            catch (IOException ex)
+
+            string fileContent = await File.ReadAllTextAsync(fullPath, cancellationToken).ConfigureAwait(false);
+
+            if (string.IsNullOrEmpty(fileContent))
             {
-                Debug.LogError($"[Save Async] FileHandler.ReadFile() - IO error reading file \"{pathOrFilename}\": {ex.Message}");
+                if (SaveManager.SaveSlotIndex > -1)
+                    Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - The file \"{pathOrFilename}\" in slot index {SaveManager.SaveSlotIndex} was empty. This may be expected if the file has been erased.");
+                else
+                    Debug.LogWarning($"[Save Async] FileHandler.ReadFile() - The file \"{pathOrFilename}\" was empty. This may be expected if the file has been erased.");
+
                 return string.Empty;
             }
+
+            return fileContent;
         }
-        
+
         /// <summary>
         /// Returns the contents of a file at the given path or filename.
         /// <code>
@@ -193,7 +174,7 @@ public virtual async Task<string> ReadFile(string pathOrFilename, CancellationTo
         /// <param name="pathOrFilename">The path or filename of the file to read.</param>
         public virtual async Task<string> ReadFile(string pathOrFilename)
             => await ReadFile(pathOrFilename, CancellationToken.None);
-        
+
         /// <summary>
         /// Erases a file at the given path or filename. The file will still exist on disk, but it will be empty.
         /// Use <see cref="Delete(string)"/> to remove the file from disk.
@@ -206,7 +187,7 @@ public virtual async Task<string> ReadFile(string pathOrFilename)
         /// <param name="cancellationToken">The cancellation token should be the same one from the calling MonoBehaviour.</param>
         public virtual async Task Erase(string pathOrFilename, CancellationToken cancellationToken)
             => await WriteFile(pathOrFilename, string.Empty, cancellationToken);
-        
+
         /// <summary>
         /// Erases a file at the given path or filename. The file will still exist on disk, but it will be empty.
         /// Use <see cref="Delete(string)"/> to remove the file from disk.
@@ -232,20 +213,32 @@ public virtual async Task Erase(string pathOrFilename)
         public virtual async Task Delete(string pathOrFilename, CancellationToken cancellationToken)
         {
             string fullPath = GetFullPath(pathOrFilename);
-            if (File.Exists(fullPath))
+
+            if (!File.Exists(fullPath))
+                return;
+
+            try
+            {
                 await Task.Run(() => File.Delete(fullPath), cancellationToken).ConfigureAwait(false);
+            }
+            catch (UnauthorizedAccessException ex)
+            {
+                Debug.LogError($"[Save Async] FileHandler.Delete() - Access denied to file \"{pathOrFilename}\": {ex.Message}");
+                throw;
+            }
+            catch (IOException ex)
+            {
+                Debug.LogError($"[Save Async] FileHandler.Delete() - IO error deleting file \"{pathOrFilename}\": {ex.Message}");
+                throw;
+            }
         }
-        
+
         /// <summary>
         /// Deletes a file at the given path or filename. This will remove the file from disk.
         /// Use <see cref="Erase(string, CancellationToken)"/> to fill the file with an empty string without removing it from disk.
-        /// <code>
-        /// File example: "MyFile"
-        /// Path example: "MyFolder/MyFile"
-        /// </code>
         /// </summary>
         /// <param name="pathOrFilename">The path or filename of the file to delete.</param>
         public virtual async Task Delete(string pathOrFilename)
             => await Delete(pathOrFilename, CancellationToken.None);
     }
-}
+}

Runtime/ISaveable.cs

@@ -3,37 +3,39 @@
 namespace Buck.SaveAsync
 {
     /// <summary>
-    /// Allows an object to be saved and loaded via the SaveManager class.
+    /// Allows an object to be saved and loaded via the SaveManager class using a strongly-typed state.
+    /// Implementations should define a serializable struct or class for TState.
     /// </summary>
-    public interface ISaveable
+    /// <typeparam name="TState">A serializable type representing this object's save data.</typeparam>
+    public interface ISaveable<TState>
     {
         /// <summary>
         /// This is a unique string used to identify the object when saving and loading.
         /// Often this can just be the name of the class if there is only one instance, like "EnemyManager" or "Player"
         /// If you choose to use a Guid, it is recommended that it is backed by a
         /// serialized byte array that does not change.
         /// </summary>
-        public string Key { get; }
-        
+        string Key { get; }
+
         /// <summary>
         /// This is the file name where this object's data will be saved.
         /// It is recommended to use a static class to store file paths as strings to avoid typos.
         /// </summary>
-        public string Filename { get; }
-        
+        string Filename { get; }
+
         /// <summary>
         /// This is used by the SaveManager class to capture the state of a saveable object.
         /// Typically this is a struct defined by the ISaveable implementing class.
         /// The contents of the struct could be created at the time of saving, or cached in a variable.
         /// </summary>
-        object CaptureState();
-        
+        TState CaptureState();
+
         /// <summary>
         /// This is used by the SaveManager class to restore the state of a saveable object.
-        /// This will be called any time the game is loaded, so you need to handle cases where the "state" parameter is a null object.
+        /// This will be called any time the game is loaded, so you need to handle cases where the "state" parameter is null.
         /// In cases where the state is null, you should initialize the object to a default state.
         /// You may also consider using this method to initialize any fields that are not saved (i.e. "resetting the object").
         /// </summary>
-        void RestoreState(object state);
+        void RestoreState(TState state);
     }
-}
+}