Add custom error mapping

[Sherlouk]

Problem Statement

You already have a handful of built-in error mappings for common Apple frameworks like URLSession, FileManager, and CoreData. Functions like mapToThrowable, userFriendlyFoundationMessage and others.

These global handlers are called within userFriendlyMessage to try and map to the best possible error message. Awesome.

What would be nice is if I was able to provide my own "error matchers" to map an Error to a Throwable.

The purpose of this is to:

1. Enable an ecosystem of third-party libraries that provide extensions to this primary product. Providing mappings to errors thrown by many third parties, no matter what they be, and without requiring adoption upstream.
2. Adds a centralised way to map error messages within a product, which can be useful to ease in initial onboarding, and in cases where you want to provide backend messages.

Suggested Solution

protocol ThrowableMappingProvider {
  func mapToThrowable(error: Error) -> Throwable? // Where `nil` is unhandled, and falls to the next.
}

ErrorKitMapper.register(MyMappingProvider()) // this would store as an array, first registered gets checked first.

[Jeehut]

That seems to be an interesting idea! So your goal is to map things from third parties even if they don't want official ErrorKit support? That seems reasonable. And there could be repos just providing the mapping, too.

I'm currently on a trip, but I'll think about this in more detail sometime soon. As for naming: I prefer to keep all main functionality under the ErrorKit. namespace. And I'm not sure about the naming of the ThrowableMappingProvider protocol. Could you give me an example implementation / use case so I can better think about it?

[Sherlouk]

You've articulated the use case perfectly.

Naming is not important to me, so happy to call it whatever you think makes sense

[Jeehut]

@Sherlouk Do you have specific libs in mind you would want to see mappings for?

[Sherlouk]

I don't think that's hugely important to the context of this issue, as I wouldn't want this repository to be bloated with those third-party errors.

Though I'd definitely be going through many of thre dependencies I use and mapping them.

[Jeehut]

@Sherlouk Sorry that I wasn't clear enough. I don't want to add the mapping into the repo, I rather want to have specific examples I can play around with to figure out a good naming scheme and API design for the mapping that works for a real-world use case an actual user will use. I'm a very practical person and while I could come up with things in a theoretical way, I've learned that often I just waste a lot of time without practical examples.

[Sherlouk]

https://github.com/kean/Nuke/blob/main/Sources/Nuke/Pipeline/ImagePipeline%2BError.swift
First dependency on my list, has public errors, and ones that I've run into.

[Jeehut]

@Sherlouk Thank you for the example.

I just had more time to take a look at the code and your initial post again. Let me clarify one point first:

You already have a handful of built-in error mappings for common Apple frameworks like URLSession, FileManager, and CoreData. Functions like mapToThrowable, userFriendlyFoundationMessage and others.

These global handlers are called within userFriendlyMessage to try and map to the best possible error message

This is only partly true. Only the likes of userFriendlyFoundationMessage within the EnhancedDescriptions folder are actually called within the global userFriendlyMessage(for:) function. But this is not true for the mappings within the TypedOverloads folder, where you can find two files at the moment. One adds typed overload functions for FileManager APIs, the other for URLSession APIs. The purpose of these is that you call these functions, all by starting with throwable prefix by convention instead of their original variants.

For example, you can call URLSession.shared.throwableData(for:) instead of URLSession.shared.data(for:) and what you'll get is the exact same function call except that the throwable one is using typed throws and therefore throws only errors of the new type URLSessionError. That's where I mapped the system errors to the built-in custom type using a private helper function, which I named mapToThrowable. In no way are these two types directly related to any other code within the ErrorKit library, so we could have also provided them in a separate library. This kind of function overload with typed throws is totally possible without any changes to ErrorKit – you wouldn't even need ErrorKit for that unless you want to conform your errors to Throwable and Catching for the extra functionality.

Having that said, it might still be worth thinking about some kind of mapping provider support more similar to the EnhancedDescriptions folder. But the TypedOverloads folder is a different story and doesn't need any changes IMO.

Please let me know if that makes sense to you, I'm open to discuss this further.

[Jeehut]

@Sherlouk I actually just introduced the ErrorMapper protocol in #35 and published version 1.1.0 with it included.

The Enhanced Error Descriptions article was updated accordingly.

I think that should cover this ticket. Let me know if you have any questions!