Improves `NSError` interoperability by exposing conversion logic between `NSError` and `Throwable`, providing extension functions and properties to handle error unwrapping and wrapping effectively.
A Kotlin Multiplatform Library to improve NSError interop.
Kotlin already has Throwable to NSError interop for straightforward cases as described in
the docs.
Though currently there is no way for application or library code to use this interop directly,
meaning applications and libraries need to create their own instead.
The Ktor Darwin client does this by wrapping a NSError in a custom Exception:
@OptIn(UnsafeNumber::class)
internal fun handleNSError(requestData: HttpRequestData, error: NSError): Throwable = when (error.code) {
NSURLErrorTimedOut -> SocketTimeoutException(requestData)
else -> DarwinHttpRequestException(error)
}
Which is a great solution for your Kotlin code as it allows you to access the wrapped NSError.
However once these Exceptions reach Swift/ObjC, Kotlin will convert them to a NSError.
Since Kotlin doesn't know this Exception is a wrapped NSError it will wrap the Exception in a again.
This results in hard to log errors like this one.
KMP-NativeCoroutines has a similar problem
where it needs to convert Exceptions to NSErrors:
@OptIn(UnsafeNumber::class)
internal fun Throwable.asNSError(): NSError {
val userInfo = mutableMapOf<Any?, Any>()
userInfo["KotlinException"] = this.freeze()
val message = message
if (message != null) {
userInfo[NSLocalizedDescriptionKey] = message
}
return NSError.errorWithDomain("KotlinException", 0.convert(), userInfo)
}
It produces similar NSErrors to the once Kotlin creates, but it doesn't unwrap an already wrapped NSError.
And in case such an NSError reaches Kotlin again it will be wrapped in an Exception instead of being unwrapped.
So depending on your code this might result in hard to log errors as well.
The latest version of the library uses Kotlin version 1.9.22.
[!WARNING] This library exposes the Kotlin
NSErrorinterop logic provided by the Kotlin Native runtime.
These internals aren't part of any public API and are considered to be an implementation detail!
Use at your own risk and beware that using the library with other Kotlin versions might not work as expected.
Simply add the dependency to the appleMain source-set of your Kotlin module:
kotlin {
sourceSets {
appleMain {
dependencies {
api("com.rickclephas.kmp:nserror-kt:0.2.0")
}
}
}
}
If you want to use the library in your Swift code, make sure to export it from your shared Kotlin module:
kotlin {
targets.withType(KotlinNativeTarget::class) {
if (!konanTarget.family.isAppleFamily) return@withType
binaries.framework {
export("com.rickclephas.kmp:nserror-kt:0.2.0")
}
}
}
To solve the interop issues this library exposes the Kotlin NSError interop logic to your application and library code.
Consisting of 3 extension functions:
and 2 extension properties:
/**
* Converts `this` [Throwable] to a [NSError].
*
* If `this` [Throwable] represents a [NSError], the original [NSError] is returned.
* For other [Throwable]s a `KotlinException` [NSError] is returned:
* ```
* NSError.errorWithDomain("KotlinException", 0, mapOf(
* "KotlinException" to this,
* NSLocalizedDescriptionKey to this.message
* ))
* ```
*
* @see throwAsNSError
* @see asThrowable
*/
fun Throwable.asNSError(): NSError
/**
* Tries to convert `this` [Throwable] to a [NSError].
*
* If `this` [Throwable] is an instance of one of the [exceptionClasses] or their subclasses,
* it is converted to a [NSError] in the same way [asNSError] would.
*
* Other [Throwable]s are considered unhandled and will cause program termination
* in the same way a [Throws] annotated function would.
*
* @see asNSError
* @see asThrowable
* @see Throws
*/
fun Throwable.throwAsNSError(vararg exceptionClasses: KClass<out Throwable>): NSError
/**
* Converts `this` [NSError] to a [Throwable].
*
* If `this` [NSError] represents a [Throwable], the original [Throwable] is returned.
* For other [NSError]s an [ObjCErrorException] will be returned.
*
* @see asNSError
*/
fun NSError.asThrowable(): Throwable
/**
* Indicates if `this` [Throwable] represents a [NSError].
*/
val Throwable.isNSError: Boolean
/**
* Indicates if `this` [NSError] represents a [Throwable].
*/
val NSError.isThrowable: Boolean
NSErrorSurfaced from shared tags and platforms — no rankings paid for.