feat: Add async overloads for File and Folder operations

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 @@
         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>
@@ -217,10 +250,10 @@
         Directory.CreateDirectory(targetPath);
 
         // Copy all subdirectories first
         foreach (var dirPath in Directory.EnumerateDirectories(this, "*", SearchOption.AllDirectories))
         {
             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);
 
@@ -236,10 +269,10 @@
         }
 
         // Copy all files
         foreach (var filePath in Directory.EnumerateFiles(this, "*", SearchOption.AllDirectories))
         {
             var sourceFile = new FileInfo(filePath);
             var relativePath = System.IO.Path.GetRelativePath(this, filePath);
             var newPath = System.IO.Path.Combine(targetPath, relativePath);
             System.IO.File.Copy(filePath, newPath, true);
 
@@ -270,6 +303,91 @@
         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 @@
         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));