MIGRATING.md

Migrating from 0.8 to 0.9

Swift 3 support

Please make sure to convert all usages of Carlos APIs to the Swift 3 counterparts. In most cases there won't be a big syntactic difference.

Deprecated functions

All deprecated functions have been removed. This were of 2 types:

• Global functions
• Functions taking fetch closures or transformation closures

For the first type, just use the corresponding protocol extension function.

For the second type, please use BasicFetcher instead of fetch closures, and explicit OneWayTransformationBox instances instead of transformation closures.

Custom operators

All custom operators have been removed. Please use the corresponding protocol extension functions instead. This may require some reordering of the objects.

Migrating from 0.7 to 0.8

Promise now has only an empty init.

If you used one of the convenience init (with value:, with error: or with value:error:), they now moved to Future.

// Before
let future = Promise(value: 10).future

// Now
let future = Future(10)

// Before
let future = Promise(error: MyError.SomeError).future

// Now
let future = Future(MyError.SomeError)

// Before
let future = Promise(value: someOptionalInt, error: MyError.InvalidConversion).future

// Now
let future = Future(value: someOptionalInt, error: MyError.InvalidConversion)

Migrating from 0.6 to 0.7

- Please note that with Carlos 0.7 the Future and Promises code has been moved to a new framework.

• If you use CocoaPods or Carthage, you will just have to add a import PiedPiper line everywhere you make use of Carlos' Futures.
• If you did a submodule integration, please add PiedPiper as Embeded binary to your target.
• If you did a manual integration, please make sure that all the files missing from your target are re-added from the Futures folder.

- Check all your usages of onCompletion and replace the tuple (value, error) with the value result. Code will look like the following:

Before

future.onCompletion { (value, error) in
  if let value = value {
    //handle success case
  } else if let error = error {
  	//handle error case
  } else {
    //handle cancelation case
  }
}

Now

future.onCompletion { result in
  switch result {
  case .Success(let value):
     //handle success case
  case .Error(let error):
    //handle error case
  case .Cancelled:
    //handle cancelation case
  }
}

- Check all your usages of closures in the API. Methods taking closures instead of Fetcher, CacheLevel or OneWayTransformer values have been deprecated.

Migrating from 0.4 to 0.5

- Rename all your usages of CacheRequest to Future

- If you created come custom CacheLevel or Fetcher, you should internally use Promise instead of Future so that you can control when the request can fail or succeed. Future is in fact a read-only version of Promise

Before

class MyCustomLevel: Fetcher {
  typealias KeyType = String
  typealias OutputType = String

  func get(key: String) -> CacheRequest<String> {
    let request = CacheRequest<String>()
   
    //Do stuff...
    request.succeed("Yay!")

    return request
  }
}

Now

class MyCustomLevel: Fetcher {
  typealias KeyType = String
  typealias OutputType = String

  func get(key: String) -> Future<String> {
    let request = Promise<String>()
   
    //Do stuff...
    request.succeed("Yay!")

    return request.future
  }
}

- If you created some custom OneWayTransformer or TwoWayTransformer, you should return Future now. This means that you have to wrap simple return values into Future instances

Before

let transformer = OneWayTransformationBox<String, String>(transform: { $0.uppercaseString })

Now

let transformer = OneWayTransformationBox<String, String>(transform: { Promise(value: $0.uppercaseString).future })

- If you used the conditioned API, the same async changes apply

Before

let conditionedCache = myCache.conditioned { key in 
  //whatever
  return true
}

Now

let conditionedCache = myCache.conditioned { key in
  return Promise(value: true).future
}

- If you use global functions, please consider using protocol extensions instead. Global functions are now deprecated and will be discontinued in Carlos 1.0

For example:

Before

let cache = compose(firstLevel, secondLevel)

Now

let cache = firstLevel.compose(secondLevel)