Directory utils integration

[N7ghtm4r3]

Hi @vinceglb!

Could be usefult to have some utils for directories like count files, iterating them or size etc?

[vinceglb]

Hi @N7ghtm4r3, thanks for the idea!

Counting and iterating the direct children of a directory already works on every platform with list():

val count = directory.list().size
directory.list().forEach { file -> /* ... */ }

What's really missing is a recursive traversal and a directory's total size. I'm open to adding them, and you're welcome to implement them. Before you open a PR, though, let's agree on the API here. Here's what I have in mind:

/**
 * Lazily walks this directory recursively (depth-first).
 * Yields files and subdirectories, but not the starting directory itself.
 */
public fun PlatformFile.walk(maxDepth: Int = Int.MAX_VALUE): Sequence<PlatformFile>

/**
 * Returns the total size in bytes of all regular files in this tree.
 * For a regular file, returns its own size.
 */
public suspend fun PlatformFile.sizeRecursively(): Long

Which would give:

directory.walk().count { it.isRegularFile() } // count files recursively
directory.walk().forEach { file -> /* ... */ } // iterate recursively
directory.sizeRecursively()                    // total size

Design points:

• Sequence, not Flow: this matches list() (synchronous) and the Kotlin stdlib (File.walk()). It's lazy, so you can stop early. Callers move to Dispatchers.IO themselves, as they already do with list().
• Symbolic links are never followed, so there's no risk of infinite loops. This matches what delete(recursively = true) already does.
• Errors throw, like list(). We can add an onError callback later if someone needs it.
• size() stays unchanged. sizeRecursively() is a separate function that runs on IO.
• Unknown sizes are skipped: on Android, some document providers don't report a size. Those files count as 0, which will be documented.
• Naming is open too: sizeRecursively() follows the stdlib's deleteRecursively() / copyRecursively(), but happy to hear other ideas.

Platform notes:

• Android (SAF): each subdirectory is one query to the content provider, so large trees will be slow. That's why sizeRecursively() is suspend.
• Apple: access to the security-scoped root folder must stay active for the whole lazy traversal.
• Web: this works, but only on directories the user picked, since their tree is already in memory.

What's your concrete use case? Does this API cover it, or would you change anything (Flow vs Sequence, including the root directory, naming, etc.)? Once we agree, feel free to open a PR, with tests for each platform. 🙂

[N7ghtm4r3]

Hi @vinceglb!

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

[N7ghtm4r3]

Hi @vinceglb! I just read and I am agree with you about the possible implemention as you said!

I have just used that method on JVM target and the wrapper will fit on It

The symbolic links I prefer to keep them, specifing that explicit as and option if you agree on it

My use case was about on counting files and sum the folder size so what those APIs will cover!

If for you is okay I will implement It ASAP?

[N7ghtm4r3]

I will follow your tip about the symbolic links to stay compliant with the delete(recursively = true), I missed it reading it

[N7ghtm4r3]

Hi @vinceglb!

I just opened the related PR #673!

Let me known if is all okay!