Integration of copyRecursively API

[N7ghtm4r3]

Hi @vinceglb!

Could be very useful to introduce an API like copy-recursively to copy recursively all files in a folder in batch to other destination in each targets.

If for you could be good to have I can handle this integration!

[vinceglb]

Hi @N7ghtm4r3, thanks for this one too!

This fits well with #666: once we have walk(), a recursive copy can be built on top of it. I'm open to adding it, and you're welcome to implement it. As with #666, let's agree on the API here before you open a PR. Here's what I have in mind:

/**
 * Copies this file or directory tree to [target], which becomes the new root.
 * Fails on the first error, leaving [target] partially copied.
 * Symbolic links are skipped. Not available on web.
 */
public suspend fun PlatformFile.copyRecursively(
    target: PlatformFile,
    overwrite: Boolean = false,
)

Which would give:

source.copyRecursively(target)                   // source/a.txt -> target/a.txt
source.copyRecursively(target, overwrite = true) // merge into an existing target
file.copyRecursively(target)                     // also works on a regular file

Design points:

• Same name and behavior as the stdlib's copyRecursively(): target becomes the new root (target/a.txt, not target/source/a.txt), and missing parent directories are created. This differs from copyTo(), which copies into a directory, which is why I'd rather not add a recursively parameter to copyTo().
• overwrite = false fails on the first existing file. overwrite = true merges into an existing directory and replaces conflicting files.
• Errors throw, like copyTo() and walk() in Directory utils integration #666. There's no rollback, so target may be partially copied. This will be documented. We can add an onError callback later if someone needs it.
• Symbolic links are skipped: they're never followed, matching delete(recursively = true) and walk().
• Copying into itself fails: if target is source or is inside it, the function throws instead of looping forever.
• Built on walk(): I'd ship Directory utils integration #666 first, then this as a separate PR on top of it. Smaller PRs are easier to review.
• Naming is open too: happy to hear other ideas.

Platform notes:

• Android (SAF): every file and subdirectory is a new document created through the content provider, so large trees will be slow.
• Apple: access to the security-scoped source and target folders must stay active for the whole copy.
• Web: not supported, since FileKit can't write to the user's file system there (copyTo() isn't available on web either).
• Available on every target except web (Android, Apple, JVM, Windows, etc.), since it's built only on APIs that already work there.

What's your concrete use case? Does this API cover it, or would you change anything (target semantics, overwrite behavior, naming, etc.)? Once we agree, feel free to open a PR after #666, with tests for each platform.

[N7ghtm4r3]

Hi @vinceglb!

ASAP as before I Will read the comment and let you know about, thanks for the opportunity to work on It!

[N7ghtm4r3]

Hi @vinceglb!

As the comment on discussion about walk implementation I am agree with you!

Additional I would implement also callbacks like onFileAdded, onFileRemoved, onFileOverwritten and onFileSkipped to handle also the lifecycle of the copy to provide an external access point to work with stats for example!

Let me know if you agree with that and I am very Happy about integrate It ASAP!

[N7ghtm4r3]

Hi @vinceglb!

I just opened the related PR for this integration, the PR is the #677!
I added the callbacks instead on fail with an error I hope could be a valid alternative, because I have an use cause that should use them. These callbacks are optional due not all scenarios require them