PlatformFile

Cross-platform file representation for Kotlin Multiplatform

Supported on Android, iOS, macOS, JVM, Kotlin/Native Linux, JS and WASM targets

Introduction

PlatformFile is the core class in FileKit that provides a unified representation of files across all platforms. It abstracts away platform-specific file implementations and provides a consistent API for working with files in your Kotlin Multiplatform project.

Creating a PlatformFile

You can create a PlatformFile instance in several ways:

// From a path string
val file = PlatformFile("/path/to/file.txt")

// From a kotlinx.io.files.Path
val path = Path("/path/to/file.txt")
val file = PlatformFile(path)

// From a parent file and child path
val parentDir = PlatformFile("/path/to")
val file = PlatformFile(parentDir, "file.txt")
// or using the convenient / operator
val file = parentDir / "file.txt"

Platform-specific constructors

Each platform also provides specific constructors:

Android

// From a Java File
val javaFile = File("/path/to/file.txt")
val file = PlatformFile(javaFile)

// From an Android Uri
val uri = Uri.parse("content://...")
val file = PlatformFile(uri)

Properties

PlatformFile provides several properties to access file information:

val file = PlatformFile("/path/to/document.pdf")

// Get the file name with extension
val name: String = file.name // "document.pdf"

// Get just the file extension
val extension: String = file.extension // "pdf"

// Get the file name without extension
val nameWithoutExtension: String = file.nameWithoutExtension // "document"

// Get the file path
val path: String = file.path // "/path/to/document.pdf"

// Get the file size in bytes
val size: Long = file.size()
// Note: some provider-backed files may return -1 when size metadata is unavailable.

// Get the parent directory
val parent: PlatformFile? = file.parent()

@OptIn(ExperimentalTime::class)
val createdAt: Instant? = file.createdAt()

@OptIn(ExperimentalTime::class)
val lastModified: Instant = file.lastModified()

// Get the absolute path string
val absolutePath: String = file.absolutePath()

// Get the absolute file
val absoluteFile: PlatformFile = file.absoluteFile()

// Check the MIME type (null for directories or unknown types)
val mimeType: MimeType? = file.mimeType()

On Android, name is resolved using provider metadata. For Photo Picker URIs, FileKit performs a best-effort lookup of MediaStore.MediaColumns.DISPLAY_NAME when providers return synthetic names (for example 18.jpg), then falls back to a stable provider/URI-derived name if the original filename is not accessible.

For Android content URIs, parent() supports external-storage document trees and preserves access to the selected tree. It returns null at the selected directory’s root and for other content providers whose parent cannot be determined from the URI. Filesystem paths continue to use normal filesystem parents.

On JS/WASM, directory picker results are virtual directory trees built from browser file entries. Empty directories are not exposed by browsers, and directory lastModified() values are synthetic.

File operations

PlatformFile provides methods for common file operations:

// Check if the file exists
val exists: Boolean = file.exists()

// Check if it's a regular file
val isFile: Boolean = file.isRegularFile()

// Check if it's a directory
val isDirectory: Boolean = file.isDirectory()

// Check if it's an absolute path
val isAbsolute: Boolean = file.isAbsolute()

// Create directories
file.createDirectories()

// Copy the file to a new location
file.copyTo(newFile)

// Move the file to a new location
file.atomicMove(newFile)

// Delete the file
file.delete()

// List files in the directory
val files: List<PlatformFile> = file.list()

// Get input stream as a source
val source: RawSource = file.source()

// Get output stream as a sink
val sink: RawSink = file.sink(append = false)

// Read bytes from the file
val bytes: ByteArray = file.readBytes()

// Read string from the file
val content: String = file.readString()

// Write bytes to the file
file.write(bytes)

// Write string to the file
file.writeString(content)

Determining MIME types

Use mimeType() to ask the underlying platform for the best-known media type. It returns null when the value is unknown (for example, directories or proprietary containers).

• Apple platforms: FileKit first queries provider metadata (e.g., from the Files app or iCloud Drive) and falls back to the filename extension when needed, so even extension-less documents can resolve to a MIME type.
• Android: The resolver consults the ContentResolver for content:// URIs and then falls back to MimeTypeMap if necessary.
• JVM Desktop & Web: The lookup is derived from the file extension or the desktop platform’s MIME registry.
• Kotlin/Native Linux: FileKit matches the filename against the system shared MIME database, with /etc/mime.types as a fallback.

This utility is helpful when you need to validate file types, populate upload headers, or customise previews based on content.

Working with directories

You can use the resolve method or the / operator to navigate through directories:

val baseDir = PlatformFile("/path/to/base")

// Create a reference to a subdirectory or file
val subDir = baseDir / "subdirectory"
val file = subDir / "file.txt"

// Alternative using resolve
val file2 = baseDir.resolve("subdirectory/file.txt")

// Get the absolute path from a relative path
val relativeDir = PlatformFile("/path/to/relative")
val absoluteDir: PlatformFile = relativeDir.absoluteFile()

Walking a directory tree

walk() lazily yields every file and subdirectory below a directory, depth-first, without the directory itself. sizeRecursively() returns the total size of the regular files in the tree:

val fileCount = directory.walk().count { it.isRegularFile() }
val children = directory.walk(maxDepth = 1).toList() // like list()
val totalBytes: Long = directory.sizeRecursively()

• Symbolic links are listed but never followed, so a link can’t cause an infinite loop. They add nothing to sizeRecursively(). This also applies when you call either function on a link.
• On a regular file, walk() yields only that file and sizeRecursively() returns its size. maxDepth must be positive.
• walk() is synchronous, like list(): on non-web platforms, iterate it on Dispatchers.IO. sizeRecursively() is a suspend function that switches to Dispatchers.IO itself on non-web platforms.
• Android: each subdirectory of a document tree costs provider queries, so large trees are slow. Files whose provider doesn’t report a size count as 0.
• Apple platforms: keep security-scoped access to the root active while iterating walk(), for example inside withScopedAccess { }.
• Windows: every reparse point counts as a link, including directory junctions and OneDrive Files On-Demand folders. walk() lists such a folder without its contents, and sizeRecursively() doesn’t count them.
• Web: works on directories picked with the directory picker, whose tree is already in memory. Both functions run on the caller’s dispatcher. Origin private file system directories aren’t supported.

Converting to kotlinx-io

PlatformFile provides built-in integration with kotlinx-io.

// Convert to kotlinx.io.files.Path
val path: Path = file.toKotlinxIoPath()

// Convert to kotlinx.io.RawSource
val source: RawSource = file.source()

// Convert to kotlinx.io.RawSink
val sink: RawSink = file.sink()

Example usage

// Create a file reference
val file = PlatformFile(FileKit.filesDir, "document.txt")

// Check if it exists
if (file.exists()) {
    // Write content to the file
    file.writeString("Hello, FileKit!")
}

// Read the file content
val content = file.readString()
println(content) // "Hello, FileKit!"

Next steps

Read File

Read files as bytes, strings, or streams across platforms.

Write File

Write data to files with atomic operations and appending.

Image & Video Utils

Compress, resize and save images with platform-specific optimizations.

File Utils

Access standard directories and common file operations.

Bookmark Data

Maintain persistent access to user-selected files across app restarts.