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

• Platform detection utilities

• Designed for library integration and automation tools

The goal of filesystem is to provide a minimal and predictable abstraction for file system access across platforms.

Key principles:

• Platform separation – JVM and Android implementations remain independent
• Stream-first design – files are exposed as streams to support large data processing
• Minimal dependencies – avoids heavy frameworks
• Developer control – does not hide platform limitations

Maven Central

implementation("io.github.sifisofakude.filesystem:filesystem-android:0.3.1")
implementation("io.github.sifisofakude.filesystem:filesystem-jvm:0.3.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.

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

    fun write(
    	input: InputStream, 
    	output: OutputStream
    ): Boolean

    fun writeText(
    	outputFile: String,
    	text: String
    ): Boolean
}

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

• Minimal dependency design

• Maven Central publishing

• Clean, documented Kotlin API design

filesystem is useful for:

• Build tools

• Code generators

• Static analyzers

• File processing pipelines

• Android storage tools

• CLI utilities

• Cross-platform automation tools

MIT License

Sifiso Fakude