Unified file-system abstraction with stream-first APIs for discovering, reading, and writing files, recursive extension-filtered discovery, storage access framework support, stack-based traversal, and lightweight platform detection.
A lightweight cross-platform file system abstraction library for JVM desktop and Android SAF.
filesystem provides a unified API for discovering, reading, and writing files across different environments while hiding platform-specific implementations.
It allows developers to work with files using the same interface whether running on Windows, Linux, Mac, Android, or Termux.
Cross-platform file access abstraction
JVM desktop file system support
Android Storage Access Framework (SAF) support
Recursive file discovery with extension filtering
Stream-based file processing
The goal of filesystem is to provide a minimal and predictable abstraction for file system access across platforms.
Key principles:
| Platform | Support |
|---|---|
| Windows | ✅ |
Maven Central
implementation("io.github.sifisofakude:filesystem-common:0.1.1")
import io.github.sifisofakude.filesystem.JvmFileSystem
val fs = JvmFileSystem()
val files = fs.resolveFiles(
listOf("src"),
setOf("kt", "java")
)
files.forEach { file ->
println(file.relativePath)
}
val fs = AndroidSafFileSystem(context)
fs.changeSelectedDirectory(userSelectedUri)
val files = fs.resolveFiles(
listOf(userSelectedUri),
setOf("txt")
)
files.forEach {
println(it.relativePath)
}
The library revolves around the FileSystemUtil interface.
Implementations:
JvmFileSystem → Desktop environments
AndroidSafFileSystem → Android SAF environments
The library includes a lightweight PlatformDetector utility.
val detector = PlatformDetector()
if (detector.isAndroid()) {
println("Running on Android")
}
if (detector.isDesktop()) {
println("Desktop environment")
}
This project demonstrates several software engineering concepts:
Cross-platform abstraction layer separating platform APIs from application logic
SAF directory traversal without recursion using stack-based iteration
Stream-first file pipeline for efficient file processing
Extension-filtered recursive file discovery
filesystem is useful for:
Build tools
Code generators
Static analyzers
File processing pipelines
Android storage tools
CLI utilities
MIT License
Sifiso Fakude
Platform detection utilities
Designed for library integration and automation tools
| Linux | ✅ |
| macOS | ✅ |
| Android (SAF) | ✅ |
| Termux | ✅ |
interface FileSystemUtil {
fun getCurrentDirectory(): String?
fun resolvePath(path: String): String
fun createDirectory(path: String): String?
fun createFile(path: String): String?
fun openInputStream(path: String): InputStream?
fun openOutputStream(path: String): OutputStream?
fun readText(path: String): String?
fun listFiles(path: String): List<String>
fun findFiles(directory: String, extensions: Set<String>): List<String>
fun resolveFiles(
inputFiles: List<Any>,
extensions: Set<String>
): List<FileSource>
fun exists(path: String): Boolean
fun delete(path: String): Boolean
fun rename(src: String, target: String): String?
fun move(src: String, dst: String): String?
fun isFile(path: String): Boolean
fun isDirectory(path: String): Boolean
fun lastModified(path: String): Long
fun size(path: String): Long
}
Minimal dependency design
Maven Central publishing
Clean, documented Kotlin API design
Cross-platform automation tools
Surfaced from shared tags and platforms — no rankings paid for.