tomevault-io expect/actual Pattern for KMP
The expect/actual declaration is Kotlin's mechanism for writing platform-specific implementations while maintaining a shared API surface.
Core Concept
// shared/commonMain/kotlin/Platform.kt
expect class Platform() {
val name: String
}
// shared/androidMain/kotlin/Platform.android.kt
actual class Platform {
actual val name: String = "Android ${Build.VERSION.SDK_INT}"
}
// shared/iosMain/kotlin/Platform.ios.kt
actual class Platform {
actual val name: String = "iOS \(UIDevice.currentDevice.systemVersion)"
}
Common Patterns
1. Platform Information
// commonMain
expect object Platform {
val name: String
val version: String
val isDebug: Boolean
}
// androidMain
actual object Platform {
actual val name: String = "Android"
actual val version: String = "${Build.VERSION.SDK_INT}"
actual val isDebug: Boolean = BuildConfig.DEBUG
}
// iosMain
actual object Platform {
actual val name: String = "iOS"
actual val version: String = UIDevice.currentDevice.systemVersion
actual val isDebug: Boolean = KotlinLifecycleController.isDebug
}
2. File System Paths
// commonMain
expect class FileSystem {
fun getDocumentsPath(): String
fun getCachePath(): String
fun getTempPath(): String
}
// androidMain
actual class FileSystem {
actual fun getDocumentsPath(): String {
return context.filesDir.absolutePath
}
actual fun getCachePath(): String {
return context.cacheDir.absolutePath
}
actual fun getTempPath(): String {
return context.cacheDir.absolutePath + "/tmp"
}
}
// iosMain
actual class FileSystem {
actual fun getDocumentsPath(): String {
return NSSearchPathForDirectoriesInDomains(
NSDocumentDirectory,
NSUserDomainMask,
true
).first() as String
}
actual fun getCachePath(): String {
return NSSearchPathForDirectoriesInDomains(
NSCachesDirectory,
NSUserDomainMask,
true
).first() as String
}
actual fun getTempPath(): String {
return NSTemporaryDirectory()
}
}
3. Date/Time Operations
// commonMain
expect class DateTimeFormatter {
fun format(timestamp: Long): String
fun parse(dateString: String): Long
fun now(): Long
}
// androidMain
actual class DateTimeFormatter {
private val format = SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault())
actual fun format(timestamp: Long): String {
return format.format(Date(timestamp))
}
actual fun parse(dateString: String): Long {
return format.parse(dateString)?.time ?: 0L
}
actual fun now(): Long = System.currentTimeMillis()
}
// iosMain
actual class DateTimeFormatter {
private val formatter = NSDateFormatter().apply {
dateFormat = "yyyy-MM-dd HH:mm:ss"
}
actual fun format(timestamp: Long): String {
val date = NSDate(timeIntervalSince1970 = timestamp / 1000.0)
return formatter.stringFromDate(date)
}
actual fun parse(dateString: String): Long {
val date = formatter.dateFromString(dateString) ?: return 0L
return (date.timeIntervalSince1970 * 1000).toLong()
}
actual fun now(): Long = (NSDate().timeIntervalSince1970 * 1000).toLong()
}
4. Database Paths
// commonMain
expect class DatabasePathProvider {
fun getDatabasePath(name: String): String
}
// androidMain
actual class DatabasePathProvider(private val context: Context) {
actual fun getDatabasePath(name: String): String {
return context.getDatabasePath(name).absolutePath
}
}
// iosMain
actual class DatabasePathProvider {
actual fun getDatabasePath(name: String): String {
val dir = NSSearchPathForDirectoriesInDomains(
NSDocumentDirectory,
NSUserDomainMask,
true
).first() as String
return "$dir/databases/$name"
}
}
5. Secure Storage
// commonMain
expect class SecureStorage {
suspend fun save(key: String, value: String)
suspend fun load(key: String): String?
suspend fun delete(key: String)
}
// androidMain
actual class SecureStorage(private val context: Context) {
private val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.build()
private val prefs = EncryptedSharedPreferences.create(
context,
"secure",
masterKey,
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
actual suspend fun save(key: String, value: String) {
prefs.edit().putString(key, value).apply()
}
actual suspend fun load(key: String): String? = prefs.getString(key, null)
actual suspend fun delete(key: String) {
prefs.edit().remove(key).apply()
}
}
// iosMain
actual class SecureStorage {
private val keychain = KeychainHelper()
actual suspend fun save(key: String, value: String) {
keychain.set(key, value)
}
actual suspend fun load(key: String): String? {
return keychain.get(key)
}
actual suspend fun delete(key: String) {
keychain.delete(key)
}
}
6. Network Connectivity
// commonMain
expect class ConnectivityMonitor {
val isOnline: Flow<Boolean>
fun startMonitoring()
fun stopMonitoring()
}
// androidMain
actual class ConnectivityMonitor(private val context: Context) {
private val _isOnline = MutableStateFlow(true)
actual val isOnline: StateFlow<Boolean> = _isOnline.asStateFlow()
private val callback = object : ConnectivityManager.NetworkCallback() {
override fun onAvailable(network: Network) {
_isOnline.value = true
}
override fun onLost(network: Network) {
_isOnline.value = false
}
}
actual fun startMonitoring() {
val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
cm.registerNetworkCallback(
NetworkRequest.Builder().build(),
callback
)
}
actual fun stopMonitoring() {
val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
cm.unregisterNetworkCallback(callback)
}
}
// iosMain
actual class ConnectivityMonitor {
private val _isOnline = MutableStateFlow(true)
actual val isOnline: StateFlow<Boolean> = _isOnline.asStateFlow()
private val monitor = NWPathMonitor()
private val queue = dispatch_queue_create("network", null)
actual fun startMonitoring() {
monitor.pathUpdateHandler = {
_isOnline.value = monitor.currentPath.status == .satisfied
}
monitor.start(queue)
}
actual fun stopMonitoring() {
monitor.cancel()
}
}
7. Logging
// commonMain
enum class LogLevel { DEBUG, INFO, WARN, ERROR }
expect class Logger {
fun log(level: LogLevel, tag: String, message: String, throwable: Throwable?)
}
// androidMain
actual class Logger {
actual fun log(level: LogLevel, tag: String, message: String, throwable: Throwable?) {
when (level) {
LogLevel.DEBUG -> Log.d(tag, message, throwable)
LogLevel.INFO -> Log.i(tag, message, throwable)
LogLevel.WARN -> Log.w(tag, message, throwable)
LogLevel.ERROR -> Log.e(tag, message, throwable)
}
}
}
// iosMain
actual class Logger {
actual fun log(level: LogLevel, tag: String, message: String, throwable: Throwable?) {
val fullMessage = if (throwable != null) "$message: $throwable" else message
println("[$tag] [$level] $fullMessage")
os_log(OSLogDefault, level.toOSLogType(), "%{public}@", fullMessage)
}
private fun LogLevel.toOSLogType() = when (this) {
LogLevel.DEBUG -> OS_LOG_TYPE_DEBUG
LogLevel.INFO -> OS_LOG_TYPE_INFO
LogLevel.WARN -> OS_LOG_TYPE_DEFAULT
LogLevel.ERROR -> OS_LOG_TYPE_ERROR
}
Best Practices
✅ DO
// ✅ Keep expect declarations simple
expect class PlatformInfo {
val platform: String
}
// ✅ Use factory functions for dependencies
expect fun createPlatformService(): PlatformService
// ✅ Group related functionality
expect class FileService {
fun read(path: String): ByteArray
fun write(path: String, data: ByteArray)
fun delete(path: String)
}
// ✅ Provide default implementations when possible
expect class Analytics {
fun track(event: String, properties: Map<String, Any>)
fun flush()
}
❌ DON'T
// ❌ Don't add complex logic in expect declarations
expect class Platform {
// Complex logic here won't compile
fun calculateSomething(): Int {
// This causes errors
}
}
// ❌ Don't use expect for pure Kotlin logic
// Use commonMain instead
expect fun add(a: Int, b: Int): Int // ❌ This doesn't need expect/actual
// ❌ Don't create too many small expect classes
// Consolidate related functionality
expect class FileReader
expect class FileWriter
expect class FileDeleter // ❌ Should be one FileService class
File Organization
shared/
├── commonMain/
│ └── kotlin/
│ └── com/example/platform/
│ ├── Platform.kt (expect class Platform)
│ ├── FileSystem.kt (expect class FileSystem)
│ └── DatabasePath.kt (expect class DatabasePath)
├── androidMain/
│ └── kotlin/
│ └── com/example/platform/
│ ├── Platform.android.kt (actual class Platform)
│ ├── FileSystem.android.kt
│ └── DatabasePath.android.kt
├── iosMain/
│ └── kotlin/
│ └── com/example/platform/
│ ├── Platform.ios.kt (actual class Platform)
│ ├── FileSystem.ios.kt
│ └── DatabasePath.ios.kt
└── desktopMain/
└── kotlin/
└── com/example/platform/
├── Platform.desktop.kt
└── FileSystem.desktop.kt
Testing with expect/actual
// commonTest
class PlatformTest {
@Test
fun `platform name is not empty`() {
assertTrue(Platform.name.isNotEmpty())
}
}
// Test runs on all platforms with actual implementations
Remember: Use expect/actual only when you truly need platform-specific APIs. Keep as much code as possible in commonMain.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.