Latest 4.0.0
Homepage https://github.com/JanGorman/Waxwing
License MIT
Platforms ios 8.0, requires ARC
Authors

Build Status
codecov
Carthage compatible
Version
License
Platform

iOS version migrations in Swift. When mangling data or performing any other kind of updates you want to ensure that all relevant migrations are run in order and only once. Waxwing allows you to do just that.

Requirements

  • Swift 4
  • iOS 8+

Installation

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

pod "Waxwing"

If you don’t like CocoaPods, you can also add the dependency via Carthage or simply include Waxwing.swift in your project.

Usage

There are two ways to run your migrations, either with closures or through an OperationQueue:

import Waxwing

…

let waxwing = Waxwing(bundle: .main, defaults: .standard)

waxwing.migrateToVersion("0.9") {
    firstMigrationCall()
    secondMigrationCall()
    …
}

or

import Waxwing

…
// No need to explicitly set userdefaults or bundle
let waxwing = Waxwing()

Waxwing.migrateToVersion("0.9", [FirstMigrationClass(), SecondMigrationClass()])

Note that closure based migrations are run from the thread they are created on. Anything that has to run on the main thread, such as notifying your users of changes introduced with this version, needs to explictly call the method on the main thread:

import Waxwing

DispatchQueue.global().async {
    let waxwing = Waxwing(bundle: .main, defaults: .standard)
    waxwing.migrateToVersion("0.9") {
        DispatchQueue.main.async {
            // Some alert that we're done updating / what's new in this version of the app
        }
    }
}

The OperationQueue based migrations are always run from their own queue so the same caveat applies. Also note, that if any of the migrations in the queue depend on another one having run first, you explicitly need to add that dependency. Operation of course makes this trivial through the addDependency() method.

You can add as many migrations as you want. They will always be executed once which makes reasoning about the state of your application a lot easier.

Progress

Waxwing has built in support for Progress. Since the number of actions that are run using the closure based method cannot be determined it just reports a total unit count of 1. If you’re using Operations, the unit count will match the number of migrations.

import Waxwing

func migrate() {
    let progress = Progress(totalUnitCount: 1)
    progress.becomeCurrent(withPendingUnitCount: 1)
    _ = progress.observe(.fractionCompleted, options: [.new]) { progress, _ in
        // e.g. Update progress indicator, remember to do this on the main thread
    }

    waxwing.migrateToVersion("0.8", migrations: [migration1, migration2, migration3…])
}

For more information on how Progress works I recommend this article by Ole Begemann.

Author

Jan Gorman

License

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

Latest podspec

{
    "name": "Waxwing",
    "version": "4.0.0",
    "summary": "iOS version migrations",
    "description": "iOS version migrations in Swift. When mangling data or performing any other kind of updates you want to ensure that all relevant migrations are run in order and only once. Waxwing allows you to just that.",
    "homepage": "https://github.com/JanGorman/Waxwing",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "Jan Gorman": "[email protected]"
    },
    "social_media_url": "http://twitter.com/JanGorman",
    "platforms": {
        "ios": "8.0"
    },
    "requires_arc": true,
    "source": {
        "git": "https://github.com/JanGorman/Waxwing.git",
        "tag": "4.0.0"
    },
    "source_files": "Waxwing/WaxWing/Waxwing.swift",
    "pushed_with_swift_version": "4.0"
}

Pin It on Pinterest

Share This