File utilities

Utility functions for working with files in Kotlin Multiplatform

Standard Directories

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

FileKit provides access to standard platform-specific directories:

// Get the application's files directory
val filesDir: PlatformFile = FileKit.filesDir

// Get the application's cache directory
val cacheDir: PlatformFile = FileKit.cacheDir

// Get the application's databases directory
val databasesDir: PlatformFile = FileKit.databasesDir

These directories are automatically created if they don’t exist and are properly sandboxed on each platform.

Platform-specific Directory Behavior

Each platform maps these standard directories to different locations according to platform conventions:

Android

• filesDir: Maps to context.filesDir, which is the app’s private internal storage
• cacheDir: Maps to context.cacheDir, which is the app’s private cache directory
• databasesDir: Maps to a databases subdirectory in the app’s internal storage

iOS

• filesDir: Maps to the app’s Documents directory, which is backed up with iCloud
• cacheDir: Maps to the app’s Caches directory, which isn’t backed up and may be cleared by the system
• databasesDir: Maps to a databases subdirectory in the app’s Documents directory

macOS

• filesDir: Maps to ~/Library/Application Support/<app-id>/, requiring FileKit initialization with an app ID
• cacheDir: Maps to ~/Library/Caches/<app-id>/
• databasesDir: Maps to a databases subdirectory in the application support directory

JVM (Desktop)

• filesDir: Maps to platform-specific app data locations:
  • Linux: ~/.local/share/<app-id>/
  • macOS: ~/Library/Application Support/<app-id>/
  • Windows: %APPDATA%/<app-id>/
• cacheDir: Maps to platform-specific cache locations:
  • Linux: ~/.cache/<app-id>/
  • macOS: ~/Library/Caches/<app-id>/
  • Windows: %LOCALAPPDATA%/<app-id>/Cache/
• databasesDir: Maps to a databases subdirectory within filesDir

Kotlin/Native Linux (linuxX64, linuxArm64)

• filesDir: Maps to $XDG_DATA_HOME/<app-id>/, or ~/.local/share/<app-id>/ when XDG_DATA_HOME is unset
• cacheDir: Maps to $XDG_CACHE_HOME/<app-id>/, or ~/.cache/<app-id>/ when XDG_CACHE_HOME is unset
• databasesDir: Maps to a databases subdirectory within filesDir

On JVM, macOS, and Kotlin/Native Linux platforms, you must initialize FileKit with an application ID before accessing these directories. See the Setup guide for details.

Additional Directories

On desktop platforms (JVM, macOS, and Kotlin/Native Linux), FileKit provides access to common user directories:

// Typed API
val downloads: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Downloads)
val pictures: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Pictures)
val videos: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Videos)
val music: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Music)
val documents: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Documents)

// Convenience wrappers
val downloadsDir: PlatformFile = FileKit.downloadsDir
val picturesDir: PlatformFile = FileKit.picturesDir
val videosDir: PlatformFile = FileKit.videosDir
val musicDir: PlatformFile = FileKit.musicDir
val documentsDir: PlatformFile = FileKit.documentsDir

Use FileKit.userDirectoryOrNull(...) when you prefer nullable handling instead of exceptions.

Directory Usage Example

// Store app configuration
val configFile = FileKit.filesDir / "config.json"
configFile.writeString("{\"version\": 1}")

// Store temporary processing data
val tempFile = FileKit.cacheDir / "temp_data.bin"
tempFile.write(processingData)

```kotlin
// Access a database file
val dbFile = FileKit.databasesDir / "app.db" 
// Use the database file with your preferred database library

Scoped Resource Access (iOS/macOS)

On iOS and macOS, some files may require security-scoped access to be read or written. FileKit provides utilities to manage this:

// Start accessing a security-scoped resource
val success = platformFile.startAccessingSecurityScopedResource()
if (success) {
    try {
        // Perform file operations
    } finally {
        // Stop accessing the resource
        platformFile.stopAccessingSecurityScopedResource()
    }
}

To simplify this pattern, you can use the withScopedAccess method:

platformFile.withScopedAccess { file ->
    // Perform file operations with scoped access
}

These methods ensure that security-scoped resources are properly accessed and released, preventing potential resource leaks.

Downloading files from web

Supported on JS and WASM targets

FileKit provides a convenient way to download files in web environments (JS and WASM targets). This functionality allows users to save files from your web application to their local device:

// Download from bytes
FileKit.download(bytes, "file.txt")

// Download from file
val file: PlatformFile = ...
FileKit.download(file, "file.txt")