feat: Add async overloads for File and Folder operations (#1722)

* feat: Add async overloads for File and Folder operations

Fixes #1562

Adds async versions of sync-only file system operations:

File.cs:
- CreateAsync() - async file creation with proper stream disposal
- DeleteAsync(CancellationToken) - async file deletion
- MoveToAsync(string/Folder, CancellationToken) - async file move
- CopyToAsync(string/Folder, CancellationToken) - async stream-based copy

Folder.cs:
- CreateAsync() - async folder creation
- DeleteAsync(CancellationToken) - async recursive folder deletion
- MoveToAsync(string, CancellationToken) - async folder move
- CopyToAsync(string, bool, CancellationToken) - async stream-based folder copy

Benefits:
- Prevents thread pool starvation in highly concurrent pipelines
- Uses stream-based copying for truly async I/O
- Supports cancellation tokens for long-running operations
- Consistent API with existing async methods (Read/Write)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: Simplify await using syntax and document Task.Run usage

Address review feedback:
- Simplify CopyToAsync to use 'await using var' declarations (cleaner syntax)
- Add <remarks> documenting that Task.Run is used for operations without
  native async APIs (.NET has no async file delete/move/directory create)
- This is a common pattern for thread pool offloading of blocking I/O

* fix: Add CancellationToken to Folder.CreateAsync

Add optional CancellationToken parameter to CreateAsync for API
consistency with other async methods in the class.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: thomhurst

src/ModularPipelines/FileSystem/File.cs

@@ -163,6 +163,19 @@ public File Create()
         return this;
     }
 
+    /// <summary>
+    /// Asynchronously creates a new file at the current path.
+    /// </summary>
+    /// <returns>This file instance for method chaining.</returns>
+    public async Task<File> CreateAsync()
+    {
+        LogFileOperation("Creating File: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
+
+        var fileStream = System.IO.File.Create(Path);
+        await fileStream.DisposeAsync().ConfigureAwait(false);
+        return this;
+    }
+
     /// <inheritdoc cref="FileSystemInfo.Attributes"/>>
     public FileAttributes Attributes
     {
@@ -192,6 +205,21 @@ public void Delete()
         FileInfo.Delete();
     }
 
+    /// <summary>
+    /// Asynchronously deletes the file.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async delete API exists in .NET.
+    /// For true async I/O, consider using stream-based operations where available.
+    /// </remarks>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    public Task DeleteAsync(CancellationToken cancellationToken = default)
+    {
+        LogFileOperation("Deleting File: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
+
+        return Task.Run(() => FileInfo.Delete(), cancellationToken);
+    }
+
     /// <inheritdoc cref="FileInfo.MoveTo(string)"/>>
     public File MoveTo(string path)
     {
@@ -210,6 +238,43 @@ public File MoveTo(Folder folder)
         return MoveTo(System.IO.Path.Combine(folder.Path, Name));
     }
 
+    /// <summary>
+    /// Asynchronously moves the file to a new path.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async move API exists in .NET.
+    /// </remarks>
+    /// <param name="path">The destination path.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>This file instance for method chaining.</returns>
+    public Task<File> MoveToAsync(string path, CancellationToken cancellationToken = default)
+    {
+        LogFileOperationWithDestination("Moving File: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, path);
+
+        return Task.Run(() =>
+        {
+            FileInfo.MoveTo(path);
+            return this;
+        }, cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously moves the file to a folder.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async move API exists in .NET.
+    /// </remarks>
+    /// <param name="folder">The destination folder.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>This file instance for method chaining.</returns>
+    public async Task<File> MoveToAsync(Folder folder, CancellationToken cancellationToken = default)
+    {
+        LogFileOperationWithDestination("Moving File: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, folder);
+
+        await folder.CreateAsync().ConfigureAwait(false);
+        return await MoveToAsync(System.IO.Path.Combine(folder.Path, Name), cancellationToken).ConfigureAwait(false);
+    }
+
     /// <inheritdoc cref="FileInfo.CopyTo(string)"/>>
     public File CopyTo(string path)
     {
@@ -226,6 +291,37 @@ public File CopyTo(Folder folder)
         return CopyTo(System.IO.Path.Combine(folder.Path, Name));
     }
 
+    /// <summary>
+    /// Asynchronously copies the file to a new path using stream-based copying.
+    /// </summary>
+    /// <param name="path">The destination path.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A new File instance representing the copied file.</returns>
+    public async Task<File> CopyToAsync(string path, CancellationToken cancellationToken = default)
+    {
+        LogFileOperationWithDestination("Copying File: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, path);
+
+        await using var sourceStream = System.IO.File.OpenRead(Path);
+        await using var destStream = System.IO.File.Create(path);
+        await sourceStream.CopyToAsync(destStream, cancellationToken).ConfigureAwait(false);
+
+        return new File(path);
+    }
+
+    /// <summary>
+    /// Asynchronously copies the file to a folder using stream-based copying.
+    /// </summary>
+    /// <param name="folder">The destination folder.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A new File instance representing the copied file.</returns>
+    public async Task<File> CopyToAsync(Folder folder, CancellationToken cancellationToken = default)
+    {
+        LogFileOperationWithDestination("Copying File: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, folder);
+
+        await folder.CreateAsync().ConfigureAwait(false);
+        return await CopyToAsync(System.IO.Path.Combine(folder.Path, Name), cancellationToken).ConfigureAwait(false);
+    }
+
     public static File GetNewTemporaryFilePath()
     {
         var path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), System.IO.Path.GetRandomFileName());

src/ModularPipelines/FileSystem/Folder.cs

@@ -96,13 +96,46 @@ public Folder Create()
         return this;
     }
 
+    /// <summary>
+    /// Asynchronously creates the folder if it does not exist.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async directory creation API exists in .NET.
+    /// </remarks>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>This folder instance for method chaining.</returns>
+    public Task<Folder> CreateAsync(CancellationToken cancellationToken = default)
+    {
+        LogFolderOperation("Creating Folder: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
+
+        return Task.Run(() =>
+        {
+            Directory.CreateDirectory(Path);
+            return this;
+        }, cancellationToken);
+    }
+
     public void Delete()
     {
         LogFolderOperation("Deleting Folder: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
 
         DirectoryInfo.Delete(true);
     }
 
+    /// <summary>
+    /// Asynchronously deletes the folder and all its contents.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async delete API exists in .NET.
+    /// </remarks>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    public Task DeleteAsync(CancellationToken cancellationToken = default)
+    {
+        LogFolderOperation("Deleting Folder: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
+
+        return Task.Run(() => DirectoryInfo.Delete(true), cancellationToken);
+    }
+
     /// <summary>
     /// Removes all files and subdirectories within the folder.
     /// </summary>
@@ -270,6 +303,91 @@ public Folder CopyTo(string targetPath, bool preserveTimestamps)
         return new Folder(targetPath);
     }
 
+    /// <summary>
+    /// Asynchronously copies the folder and its contents to the specified target path using stream-based file copying.
+    /// </summary>
+    /// <param name="targetPath">The destination path for the copied folder.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A new <see cref="Folder"/> instance representing the copied folder.</returns>
+    public Task<Folder> CopyToAsync(string targetPath, CancellationToken cancellationToken = default)
+    {
+        return CopyToAsync(targetPath, preserveTimestamps: false, cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously copies the folder and its contents to the specified target path using stream-based file copying.
+    /// </summary>
+    /// <param name="targetPath">The destination path for the copied folder.</param>
+    /// <param name="preserveTimestamps">
+    /// When true, preserves CreationTimeUtc, LastWriteTimeUtc, and LastAccessTimeUtc
+    /// for all files and directories.
+    /// </param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A new <see cref="Folder"/> instance representing the copied folder.</returns>
+    public async Task<Folder> CopyToAsync(string targetPath, bool preserveTimestamps, CancellationToken cancellationToken = default)
+    {
+        LogFolderOperationWithDestination("Copying Folder: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, targetPath);
+
+        Directory.CreateDirectory(targetPath);
+
+        // Copy all subdirectories first
+        foreach (var dirPath in Directory.EnumerateDirectories(this, "*", SearchOption.AllDirectories))
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var sourceDir = new DirectoryInfo(dirPath);
+            var relativePath = System.IO.Path.GetRelativePath(this, dirPath);
+            var newPath = System.IO.Path.Combine(targetPath, relativePath);
+            var targetDir = Directory.CreateDirectory(newPath);
+
+            targetDir.Attributes = sourceDir.Attributes;
+
+            if (preserveTimestamps)
+            {
+                targetDir.CreationTimeUtc = sourceDir.CreationTimeUtc;
+                targetDir.LastWriteTimeUtc = sourceDir.LastWriteTimeUtc;
+                targetDir.LastAccessTimeUtc = sourceDir.LastAccessTimeUtc;
+            }
+        }
+
+        // Copy all files using async stream copying
+        foreach (var filePath in Directory.EnumerateFiles(this, "*", SearchOption.AllDirectories))
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var sourceFile = new FileInfo(filePath);
+            var relativePath = System.IO.Path.GetRelativePath(this, filePath);
+            var newPath = System.IO.Path.Combine(targetPath, relativePath);
+
+            await using var sourceStream = System.IO.File.OpenRead(filePath);
+            await using var destStream = System.IO.File.Create(newPath);
+            await sourceStream.CopyToAsync(destStream, cancellationToken).ConfigureAwait(false);
+
+            var targetFile = new FileInfo(newPath);
+            targetFile.Attributes = sourceFile.Attributes;
+
+            if (preserveTimestamps)
+            {
+                targetFile.CreationTimeUtc = sourceFile.CreationTimeUtc;
+                targetFile.LastWriteTimeUtc = sourceFile.LastWriteTimeUtc;
+                targetFile.LastAccessTimeUtc = sourceFile.LastAccessTimeUtc;
+            }
+        }
+
+        // Preserve root directory attributes and timestamps
+        var targetRootDir = new DirectoryInfo(targetPath);
+        targetRootDir.Attributes = DirectoryInfo.Attributes;
+
+        if (preserveTimestamps)
+        {
+            targetRootDir.CreationTimeUtc = DirectoryInfo.CreationTimeUtc;
+            targetRootDir.LastWriteTimeUtc = DirectoryInfo.LastWriteTimeUtc;
+            targetRootDir.LastAccessTimeUtc = DirectoryInfo.LastAccessTimeUtc;
+        }
+
+        return new Folder(targetPath);
+    }
+
     public Folder MoveTo(string path)
     {
         LogFolderOperationWithDestination("Moving Folder: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, path);
@@ -278,6 +396,26 @@ public Folder MoveTo(string path)
         return this;
     }
 
+    /// <summary>
+    /// Asynchronously moves the folder to a new path.
+    /// </summary>
+    /// <remarks>
+    /// Uses thread pool offloading as no native async move API exists in .NET.
+    /// </remarks>
+    /// <param name="path">The destination path.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>This folder instance for method chaining.</returns>
+    public Task<Folder> MoveToAsync(string path, CancellationToken cancellationToken = default)
+    {
+        LogFolderOperationWithDestination("Moving Folder: {Source} > {Destination} [Module: {ModuleName}, Activity: {ActivityId}]", this, path);
+
+        return Task.Run(() =>
+        {
+            DirectoryInfo.MoveTo(path);
+            return this;
+        }, cancellationToken);
+    }
+
     public Folder GetFolder(string name)
     {
         var directoryInfo = new DirectoryInfo(System.IO.Path.Combine(Path, name));