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

Feature	Description
Multi-Format	Support for .xlsx and .json file types.
Type-Safe Mapping	Automatically converts file rows/objects into Kotlin Data Classes.
Platform-Agnostic	Unified API for Android, iOS, Desktop (JVM), and Web (Wasm/JS).
Compose Integration	Pre-built Composable controller for easy state management.
Flexible Logic	Pure suspend functions for Use Cases and ViewModels.
Excel Control	Use annotations to map specific columns or ignore unmapped data.

---

📦 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")
    val age: Int 
)

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()}"
    }
)

// Trigger the picker
Button(onClick = { fileMapperController.import() }) {
    Text("Import Employees")
}

// Trigger the export
Button(onClick = { fileMapperController.export(mEmployees, "YourFileName") }) {
    Text("Export to Excel")
}

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

Annotation / Property	Description
@Serializable	Required for the engine to parse the data class structure.
@ColumnName("Name")	Maps a specific Excel header string to a Kotlin property.
ignoreUnmappedColumns	used if you want to ignore the columns in the excel file that does not mapped in data class.
ignoreColumns	Set of strings to skip during the export/import process.

---

⚠️ Errors & Exceptions

The library uses a specialized FileMapperException to provide localized feedback.

Error Code	Meaning
EMPTY_FILE	The selected file is empty.
INVALID_FORMAT	Invalid file format. Expected XLSX or JSON.
READ_FAILED	Failed to read the selected file.
EXPORT_FAILED	An error occurred during export.
NO_DATA_ROWS	The file contains no data rows.
ALL_COLUMNS_IGNORED	All columns for the target data class are ignored.
MISSING_COLUMNS	Missing Required Columns.
UNEXPECTED_COLUMNS	Unexpected Columns found.
UNEXPECTED_ERROR	An unexpected error occurred.

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 Project

If this library helped you save time on your KMP project, please consider giving it a star! It helps more developers find the project.

[ ⭐ Star this Repository ]

---

Developed by Mamon Aburawi — 2026