refactor: Parameter validation in "async"/"await" methods should be wrapped (#894)

This PR refactors async methods to follow the best practice of wrapping parameter validation in a synchronous outer method with an inner async implementation. This pattern ensures that parameter validation (like null checks) happens immediately when the method is called, rather than being deferred until the async state machine starts executing.

### Key Changes:
- Async methods are split into synchronous outer methods that perform parameter validation and asynchronous inner implementation methods
- Parameter validation exceptions are thrown synchronously before any async operations begin
- Inner async methods use abbreviated parameter names to avoid closure capture of outer parameters

Author: vbreuss

Source/Testably.Abstractions.Compression/ZipArchiveEntryWrapper.cs

@@ -109,31 +109,41 @@ public void ExtractToFile(string destinationFileName, bool overwrite)
 
 #if FEATURE_COMPRESSION_ASYNC
 	/// <inheritdoc cref="IZipArchiveEntry.ExtractToFileAsync(string, CancellationToken)" />
-	public async Task ExtractToFileAsync(string destinationFileName, CancellationToken cancellationToken = default)
+	public Task ExtractToFileAsync(string destinationFileName, CancellationToken cancellationToken = default)
 	{
 		if (destinationFileName == null)
 		{
 			throw new ArgumentNullException(nameof(destinationFileName));
 		}
 
-		await Execute.WhenRealFileSystemAsync(FileSystem,
-			async () => await _instance.ExtractToFileAsync(destinationFileName, cancellationToken),
-			() => ZipUtilities.ExtractToFile(this, destinationFileName, false));
+		return ExtractToFileImplAsync(destinationFileName, cancellationToken);
+		
+		async Task ExtractToFileImplAsync(string d, CancellationToken c)
+		{
+			await Execute.WhenRealFileSystemAsync(FileSystem,
+				async () => await _instance.ExtractToFileAsync(d, c),
+				() => ZipUtilities.ExtractToFile(this, d, false));
+		}
 	}
 #endif
 
 #if FEATURE_COMPRESSION_ASYNC
 	/// <inheritdoc cref="IZipArchiveEntry.ExtractToFileAsync(string, bool, CancellationToken)" />
-	public async Task ExtractToFileAsync(string destinationFileName, bool overwrite, CancellationToken cancellationToken = default)
+	public Task ExtractToFileAsync(string destinationFileName, bool overwrite, CancellationToken cancellationToken = default)
 	{
 		if (destinationFileName == null)
 		{
 			throw new ArgumentNullException(nameof(destinationFileName));
 		}
 
-		await Execute.WhenRealFileSystemAsync(FileSystem,
-			async () => await _instance.ExtractToFileAsync(destinationFileName, overwrite, cancellationToken),
-			() => ZipUtilities.ExtractToFile(this, destinationFileName, overwrite));
+		return ExtractToFileImplAsync(destinationFileName, overwrite, cancellationToken);
+		
+		async Task ExtractToFileImplAsync(string d, bool o, CancellationToken c)
+		{
+			await Execute.WhenRealFileSystemAsync(FileSystem,
+				async () => await _instance.ExtractToFileAsync(d, o, c),
+				() => ZipUtilities.ExtractToFile(this, d, o));
+		}
 	}
 #endif
 

Source/Testably.Abstractions.Compression/ZipArchiveWrapper.cs

@@ -166,30 +166,34 @@ public void ExtractToDirectory(string destinationDirectoryName, bool overwriteFi
 
 #if FEATURE_COMPRESSION_ASYNC
 	/// <inheritdoc cref="IZipArchive.ExtractToDirectoryAsync(string, CancellationToken)" />
-	public async Task ExtractToDirectoryAsync(string destinationDirectoryName,
+	public Task ExtractToDirectoryAsync(string destinationDirectoryName,
 		CancellationToken cancellationToken = default)
 	{
 		if (destinationDirectoryName == null)
 		{
 			throw new ArgumentNullException(nameof(destinationDirectoryName));
 		}
 
-		await Execute.WhenRealFileSystemAsync(FileSystem,
-			async () => await _instance.ExtractToDirectoryAsync(destinationDirectoryName,
-				cancellationToken),
-			() =>
-			{
-				foreach (IZipArchiveEntry entry in Entries)
+		return ExtractToDirectoryImplAsync(destinationDirectoryName, cancellationToken);
+
+		async Task ExtractToDirectoryImplAsync(string d, CancellationToken c)
+		{
+			await Execute.WhenRealFileSystemAsync(FileSystem,
+				async () => await _instance.ExtractToDirectoryAsync(d, c),
+				() =>
 				{
-					entry.ExtractRelativeToDirectory(destinationDirectoryName, overwrite: false);
-				}
-			});
+					foreach (IZipArchiveEntry entry in Entries)
+					{
+						entry.ExtractRelativeToDirectory(d, overwrite: false);
+					}
+				});
+		}
 	}
 #endif
 
 #if FEATURE_COMPRESSION_ASYNC
 	/// <inheritdoc cref="IZipArchive.ExtractToDirectoryAsync(string, bool, CancellationToken)" />
-	public async Task ExtractToDirectoryAsync(string destinationDirectoryName,
+	public Task ExtractToDirectoryAsync(string destinationDirectoryName,
 		bool overwriteFiles,
 		CancellationToken cancellationToken = default)
 	{
@@ -198,17 +202,20 @@ public async Task ExtractToDirectoryAsync(string destinationDirectoryName,
 			throw new ArgumentNullException(nameof(destinationDirectoryName));
 		}
 
-		await Execute.WhenRealFileSystemAsync(FileSystem,
-			async () => await _instance.ExtractToDirectoryAsync(destinationDirectoryName,
-				overwriteFiles, cancellationToken),
-			() =>
-			{
-				foreach (IZipArchiveEntry entry in Entries)
+		return ExtractToDirectoryImplAsync(destinationDirectoryName, overwriteFiles, cancellationToken);
+
+		async Task ExtractToDirectoryImplAsync(string d, bool o, CancellationToken c)
+		{
+			await Execute.WhenRealFileSystemAsync(FileSystem,
+				async () => await _instance.ExtractToDirectoryAsync(d, o, c),
+				() =>
 				{
-					entry.ExtractRelativeToDirectory(destinationDirectoryName,
-						overwrite: overwriteFiles);
-				}
-			});
+					foreach (IZipArchiveEntry entry in Entries)
+					{
+						entry.ExtractRelativeToDirectory(d, overwrite: o);
+					}
+				});
+		}
 	}
 #endif