Latest 0.4.0
Homepage https://github.com/levibostian/Lucid
License MIT
Platforms ios 8.0
Authors

Make Moya errors more human readable. Show users of your app an error message they can understand.

Swift 4.0.x

Version
License
Platform

Why?

When using Moya, if your app ever encounters an error such as no Internet connection, Moya gives you an error.localizedDescription such as "Status code does not fall into range". I don’t want to show that error message to my users. I would rather tell them, "You do not have an Internet connection. Please connect then try again.". This is where Lucid was born.

How?

  • Create a class that inherits the LucidErrorMessageProvider protocol. This is the class that will be notified when an error has occurred and it will return error messages depending on the error that happened.
class MyLucidErrorMessageProvider: LucidErrorMessageProvider {
    ...
}
  • Set this new class you created as the default error handler for all of your Moya endpoints:
LucidConfiguration.setDefaultErrorHandler(MyLucidErrorMessageProvider())
  • In your Moya error handler, get a Lucid error from that original error:
provider = MoyaProvider<GitHub>()
provider.request(.zen) { result in
    switch result {
    case let .success(moyaResponse):
        do {
            try! moyaResponse.filterSuccessfulStatusCodes()

            let data = moyaResponse.data
            let statusCode = moyaResponse.statusCode
            // do something with the response data or statusCode
        } catch (error: LucidMoyaError) {
            let humanReadableError = error.localizedDescription
        }
    case let .failure(error):
        let humanReadableError = error.getLucidError()

        // Feel confident showing `humanReadableError.localizedDescription` to your app users as the error message will actually be helpful to them. 

        // this means there was a network failure - either the request
        // wasn't sent (connectivity), or no response was received (server
        // timed out).  If the server responds with a 4xx or 5xx error, that
        // will be sent as a ".success"-ful response.
    }
}

You can use the extension .getLucidError() on any error returned from Moya, or you can use the set of .filter(invalidStatusCodes: ) functions provided by Lucid on the Moya response to get a LucidMoyaError. Once you have a LucidMoyaError, you can be confident that your .localizedDescription is a human readable one that you provided and can be shown to a user.


RxSwift

Lucid provides RxSwift functionality to make Lucid easier to work with.

provider = MoyaProvider<GitHub>()
provider.rx
  .request(.userProfile("ashfurrow"))
  .filterSuccessfulStatusCodes() // Lucid, as well as Moya, provide functions to filter out status codes that are 'invalid' for your API. 
  .processErrors() // Will run `.getLucidError()` on an error if it is thrown in the stream. If you choose not to use this line, you can manually call `.getLucidError()` on the error returned from this function. 
  .subscribe { event in
    switch event {
    case let .success(response):
        image = UIImage(data: response.data)
    case let .error(error):
        let humanReadableError = error.localizedDescription
        // Because we used `.processErrors()` above, we can feel confident that our error message is human readable and will be helpful to our user. 
    }
}

Installation

Lucid is available through CocoaPods. To install
it, simply add the following line to your Podfile:

Note: I recommend appending the version of the cocoapod to the Podfile line entry like: pod "Lucid", '~> 0.4.0' because this library at this time does not provide the guarantee of backwards compatibility. Be aware when using it the API can change at anytime. I don’t want your code to break the next time you call pod update :).

The latest version at this time is: Version

pod "Lucid"

// Or, use RxSwift version
pod "Lucid/RxSwift"

Author

Levi Bostian image

License

Lucid is available under the MIT license. See the LICENSE file for more info.

Docs

Check out the docs here.

Development

Documentation

The docs are generated and hosted by cocoapods automatically for cocoadocs.

The docs are generated via jazzy using command: jazzy --podspec Lucid.podspec (assuming jazzy is intalled. If not: gem install jazzy)

Credits

Latest podspec

{
    "name": "Lucid",
    "version": "0.4.0",
    "summary": "Parse Moya networking errors for a more human readable error message to show to the end user.",
    "description": "When building iOS apps, you need to handle the response from an API call. Maybe the response was successful. Maybe it failed because the user's Internet connection is bad. Maybe the status code was a 403 error. Maybe Moya failed parsing the response body to JSON. No matter what the case is, writing the code to handle these responses require a lot of boilerplate. With the help of Moya making it easy to work with networking calls, this plugin makes it very quick and easy to configure how your app will handle Moya network call responses.",
    "homepage": "https://github.com/levibostian/Lucid",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "Levi Bostian": "[email protected]"
    },
    "source": {
        "git": "https://github.com/levibostian/Lucid.git",
        "tag": "0.4.0"
    },
    "social_media_url": "https://twitter.com/levibostian",
    "platforms": {
        "ios": "8.0"
    },
    "default_subspecs": "Core",
    "pushed_with_swift_version": "3.0",
    "subspecs": [
        {
            "name": "Core",
            "source_files": "Source/Core/**/*.swift",
            "dependencies": {
                "Moya": [
                    "~> 10.0.0"
                ]
            },
            "frameworks": "Foundation"
        },
        {
            "name": "RxSwift",
            "source_files": "Source/RxSwift/**/*.swift",
            "dependencies": {
                "Moya/RxSwift": [
                    "~> 10.0.0"
                ],
                "Lucid/Core": []
            }
        }
    ]
}

Pin It on Pinterest

Share This