FileMapper-KMP
1.0.0indexedMaps XLSX/JSON into serializable data classes with annotations for column mapping, composable UI controller, suspend-friendly API, and localized error handling.
9
Stars
—
Used by
dependents
—
Health
/ 100
FileMapper KMP
A lightweight, powerful Kotlin Multiplatform (KMP) library designed to seamlessly map files (XLSX, JSON) to Kotlin Data Classes. Supporting Android, iOS, Desktop, and Web (Wasm/JS), it provides both Compose-ready UI triggers and pure logic-based APIs.
🚀 Features
📦 Setup
Add the dependency to your commonMain source set in build.gradle.kts:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.mamon-aburawi:filemapper-kmp:{last_version}")
}
}
}
🛠 Implementation
1. Define your Data Model
Ensure your data class is annotated with @Serializable (from kotlinx.serialization) and use @ColumnName to link Excel headers.
import kotlinx.serialization.Serializable
import io.mamon.filemapper.ColumnName
@Serializable
data class Employee(
@ColumnName("Full Name") // Matches Excel Header
val name: String,
@ColumnName("Email Address")
val email: String,
@ColumnName("Age")
age:
)
2. Usage in Compose (UI)
Use the rememberFileMapper controller for a seamless UI experience. It handles picking, importing, and exporting in one place.
val fileMapperController = rememberFileMapper<Employee>(
fileType = selectedFileType,
onImportSuccess = { employeeList ->
mEmployees = employeeList
statusMessage = "Successfully imported ${employeeList.size} employees."
},
onExportSuccess = { savedPath ->
statusMessage = "Successfully exported to $savedPath"
},
onImportFailed = { error ->
statusMessage = error.getLocalizedMessage()
},
onExportFailed = { error ->
statusMessage = "Export Error: ${error.getLocalizedMessage()}"
}
)
Button(onClick = { fileMapperController.() }) {
Text()
}
Button(onClick = { fileMapperController.export(mEmployees, ) }) {
Text()
}
3. Usage in Non-Compose (Logic)
Trigger picking and mapping from a ViewModel or shared logic using the FileMapperPicker and importData API.
scope.launch {
// 1. Pick the file using the platform picker
val file = FileMapperPicker.pickFile(type = selectedFileType)
if (file != null) {
// 2. Read bytes and import data
fileMapper.importData<Employee>(
bytes = file.readBytes(),
ignoreColumns = emptySet(),
onSuccess = { employeeList ->
mEmployees = employeeList
statusMessage = "Successfully imported ${employeeList.size} employees."
},
onFailed = { error ->
statusMessage = error.getLocalizedMessage()
}
)
}
}
📑 Annotations & Configuration
⚠️ Errors & Exceptions
The library uses a specialized FileMapperException to provide localized feedback.
Localized Messages
Retrieve error messages in the user's system language (English/Arabic) automatically:
// Works in both Compose and Non-Compose (Suspend) contexts
val message = exception.getLocalizedMessage()
🌟 Support the Library
If this library helped you save time on your KMP project, please consider giving it a ⭐ It helps more developers find the project.
Developed by Mamon Aburawi — 2026