Carlos: A Simple But Flexible Cache

Carlos

A simple but flexible cache, written in Swift for iOS 13+ and WatchOS 6 apps.

Breaking Changes

Carlos 1.0.0 has been migrated from PiedPiper dependency to Combine hence the minimum supported platforms versions are equal to the Combine's minimum supported platforms versions. See the releases page for more information.

What is Carlos?

Carlos is a small set of classes and functions to realize custom, flexible and powerful cache layers in your application.

With a Functional Programming vocabulary, Carlos makes for a monoidal cache system. You can check the best explanation of how that is realized here or in this video, thanks to @bkase for the slides.

By default, Carlos ships with an in-memory cache, a disk cache, a simple network fetcher and a NSUserDefaults cache (the disk cache is inspired by HanekeSwift).

With Carlos you can:

• create levels and fetchers depending on your needs
• combine levels
• Cancel pending requests
• transform the key each level will get, or the values each level will output (this means you're free to implement every level independing on how it will be used later on). Some common value transformers are already provided with Carlos
• Apply post-processing steps to a cache level, for example sanitizing the output or resizing images
• Post-processing steps and value transformations can also be applied conditionally on the key used to fetch the value
• react to memory pressure events in your app
• automatically populate upper levels when one of the lower levels fetches a value for a key, so the next time the first level will already have it cached
• enable or disable specific levels of your composed cache depending on boolean conditions
• easily pool requests so you don't have to care whether 5 requests with the same key have to be executed by an expensive cache level before even only 1 of them is done. Carlos can take care of that for you
• batch get requests to only get notified when all of them are done
• setup multiple lanes for complex scenarios where, depending on certain keys or conditions, different caches should be used
• have a type-safe complex cache that won't even compile if the code doesn't satisfy the type requirements

Installation

Swift Package Manager (Preferred)

Add Carlos to your project through the Xcode or add the following line to your package dependencies:

.package("https://github.com/spring-media/Carlos", from: "1.0.0")

CocoaPods

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

pod "Carlos", :git => "https://github.com/spring-media/Carlos"

Carthage

Carthage is also supported.

Requirements

• iOS 13.0+
• WatchOS 6+
• Xcode 12+

Usage

To run the example project, clone the repo.

Usage examples

let cache = MemoryCacheLevel<String, NSData>().compose(DiskCacheLevel())

This line will generate a cache that takes String keys and returns NSData values. Setting a value for a given key on this cache will set it for both the levels. Getting a value for a given key on this cache will first try getting it on the memory level, and if it cannot find one, will ask the disk level. In case both levels don't have a value, the request will fail. In case the disk level can fetch a value, this will also be set on the memory level so that the next fetch will be faster.

Carlos comes with a CacheProvider class so that standard caches are easily accessible.

• CacheProvider.dataCache() to create a cache that takes URL keys and returns NSData values
• CacheProvider.imageCache() to create a cache that takes URL keys and returns UIImage values
• CacheProvider.JSONCache() to create a cache that takes URL keys and returns AnyObject values (that should be then safely casted to arrays or dictionaries depending on your application)

The above methods always create new instances (so calling CacheProvider.imageCache() twice doesn't return the same instance, even though the disk level will be effectively shared because it will use the same folder on disk, but this is a side-effect and should not be relied upon) and you should take care of retaining the result in your application layer. If you want to always get the same instance, you can use the following accessors instead:

• CacheProvider.sharedDataCache to retrieve a shared instance of a data cache
• CacheProvider.sharedImageCache to retrieve a shared instance of an image cache
• CacheProvider.sharedJSONCache to retrieve a shared instance of a JSON cache

Creating requests

To fetch a value from a cache, use the get method.

cache.get("key")
  .sink( 
    receiveCompletion: { completion in 
      if case let .failure(error) = completion {
        print("An error occurred :( \(error)")
      }
    },
    receiveValue: { value in 
      print("I found \(value)!")
    }
  )

A request can also be canceled with the cancel() method, and you can be notified of this event by calling onCancel on a given request:

let cancellable = cache.get(key)
                    .handleEvents(receiveCancel: { 
                      print("Looks like somebody canceled this request!")
                    })
                    .sink(...)
[... somewhere else]
cancellable.cancel()

This cache is not very useful, though. It will never actively fetch values, just store them for later use. Let's try to make it more interesting:

let cache = MemoryCacheLevel()
              .compose(DiskCacheLevel())
              .compose(NetworkFetcher())

This will create a cache level that takes URL keys and stores NSData values (the type is inferred from the NetworkFetcher hard-requirement of URL keys and NSData values, while MemoryCacheLevel and DiskCacheLevel are much more flexible as described later).

Key transformations

Key transformations are meant to make it possible to plug cache levels in whatever cache you're building.

Let's see how they work:

// Define your custom ErrorType values
enum URLTransformationError: Error {
    case invalidURLString
}

let transformedCache = NetworkFetcher().transformKeys(
  OneWayTransformationBox(
    transform: {
      Future { promise in 
        let url = URL(string: $0) {
          promise(.success(url))
        } else {
          promise(.failure(URLTransformationError.invalidURLString))
        }
      }
    }
  )
)

With the line above, we're saying that all the keys coming into the NetworkFetcher level have to be transformed to URL values first. We can now plug this cache into a previously defined cache level that takes String keys:

let cache = MemoryCacheLevel<String, NSData>().compose(transformedCache)

If this doesn't look very safe (one could always pass string garbage as a key and it won't magically translate to a URL, thus causing the NetworkFetcher to silently fail), we can still use a domain specific structure as a key, assuming it contains both String and URL values:

struct Image {
  let identifier: String
  let URL: Foundation.URL
}

let imageToString = OneWayTransformationBox(transform: { (image: Image) -> AnyPublisher<String, String> in
    Just(image.identifier).eraseToAnyPublisher()
})

let imageToURL = OneWayTransformationBox(transform: { (image: Image) -> AnyPublisher<URL> in
    Just(image.URL).eraseToAnyPublisher()
})

let memoryLevel = MemoryCacheLevel<String, NSData>().transformKeys(imageToString)
let diskLevel = DiskCacheLevel<String, NSData>().transformKeys(imageToString)
let networkLevel = NetworkFetcher().transformKeys(imageToURL)

let cache = memoryLevel.compose(diskLevel).compose(networkLevel)

Now we can perform safe requests like this:

let image = Image(identifier: "550e8400-e29b-41d4-a716-446655440000", URL: URL(string: "http://goo.gl/KcGz8T")!)

cache.get(image).sink {
  print("Found \(value)!")
}

Since Carlos 0.5 you can also apply conditions to OneWayTransformers used for key transformations. Just call the conditioned function on the transformer and pass your condition. The condition can also be asynchronous and has to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation.

let transformer = OneWayTransformationBox<String, URL>(transform: { key in
  Future { promise in 
    if let value = URL(string: key) {
      promise(.success(value))
    } else {
      promise(.failure(MyError.stringIsNotURL))
    }
  }.eraseToAnyPublisher()
}).conditioned { key in
  Just(key)
    .filter { $0.rangeOfString("http") != nil }
    .eraseToAnyPublisher()
}

let cache = CacheProvider.imageCache().transformKeys(transformer)

That's not all, though.

What if our disk cache only stores Data, but we want our memory cache to conveniently store UIImage instances instead?

Value transformations

Value transformers let you have a cache that (let's say) stores Data and mutate it to a cache that stores UIImage values. Let's see how:

let dataTransformer = TwoWayTransformationBox(transform: { (image: UIImage) -> AnyPublisher<Data, Error> in
    Just(UIImagePNGRepresentation(image)).eraseToAnyPublisher()
}, inverseTransform: { (data: Data) -> AnyPublisher<UIImage, Error> in
    Just(UIImage(data: data)!).eraseToAnyPublisher()
})

let memoryLevel = MemoryCacheLevel<String, UIImage>().transformKeys(imageToString).transformValues(dataTransformer)

This memory level can now replace the one we had before, with the difference that it will internally store UIImage values!

Keep in mind that, as with key transformations, if your transformation closure fails (either the forward transformation or the inverse transformation), the cache level will be skipped, as if the fetch would fail. Same considerations apply for set calls.

Carlos comes with some value transformers out of the box, for example:

• JSONTransformer to serialize NSData instances into JSON
• ImageTransformer to serialize NSData instances into UIImage values (not available on the Mac OS X framework)
• StringTransformer to serialize NSData instances into String values with a given encoding
• Extensions for some Cocoa classes (DateFormatter, NumberFormatter, MKDistanceFormatter) so that you can use customized instances depending on your needs.

As of Carlos 0.4, it's possible to transform values coming out of Fetcher instances with just a OneWayTransformer (as opposed to the required TwoWayTransformer for normal CacheLevel instancess. This is because the Fetcher protocol doesn't require set). This means you can easily chain Fetchers that get a JSON from the internet and transform their output to a model object (for example a struct) into a complex cache pipeline without having to create a dummy inverse transformation just to satisfy the requirements of the TwoWayTransformer protocol.

As of Carlos 0.5, all transformers natively support asynchronous computation, so you can have expensive transformations in your custom transformers without blocking other operations. In fact, the ImageTransformer that comes out of the box processes image transformations on a background queue.

As of Carlos 0.5 you can also apply conditions to TwoWayTransformers used for value transformations. Just call the conditioned function on the transformer and pass your conditions (one for the forward transformation, one for the inverse transformation). The conditions can also be asynchronous and have to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation.

let transformer = JSONTransformer().conditioned({ input in
  Just(myCondition).eraseToAnyPublisher()
}, inverseCondition: { input in
  Just(myCondition)eraseToAnyPublisher()
})

let cache = CacheProvider.dataCache().transformValues(transformer)

Post-processing output

In some cases your cache level could return the right value, but in a sub-optimal format. For example, you would like to sanitize the output you're getting from the Cache as a whole, independently of the exact layer that returned it.

For these cases, the postProcess function introduced with Carlos 0.4 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The postProcess function takes a CacheLevel and a OneWayTransformer with TypeIn == TypeOut as parameters and outputs a decorated BasicCache with the post-processing step embedded in.

// Let's create a simple "to uppercase" transformer
let transformer = OneWayTransformationBox<NSString, String>(transform: { Just($0.uppercased() as String).eraseToAnyPublisher() })

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.postProcess(transformer)

// Lowercase value set on the memory layer
memoryCache.set("test String", forKey: "key")

// We get the lowercase value from the undecorated memory layer
memoryCache.get("key").sink { value in
  let x = value
}

// We get the uppercase value from the decorated cache, though
transformedCache.get("key").sink { value in
  let x = value
}

Since Carlos 0.5 you can also apply conditions to OneWayTransformers used for post processing transformations. Just call the conditioned function on the transformer and pass your condition. The condition can also be asynchronous and has to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation. Keep in mind that the condition will actually take the output of the cache as the input, not the key used to fetch this value! If you want to apply conditions based on the key, use conditionedPostProcess instead, but keep in mind this doesn't support using OneWayTransformer instances yet.

let processer = OneWayTransformationBox<NSData, NSData>(transform: { value in
      Future { promise in 
        if let value = String(data: value as Data, encoding: .utf8)?.uppercased().data(using: .utf8) as NSData? {
          promise(.success(value))
        } else {
          promise(.failure(FetchError.conditionNotSatisfied))
        }
      }
    }).conditioned { value in
      Just(value.length < 1000).eraseToAnyPublisher()
    }

let cache = CacheProvider.dataCache().postProcess(processer)

Conditioned output post-processing

Extending the case for simple output post-processing, you can also apply conditional transformations based on the key used to fetch the value.

For these cases, the conditionedPostProcess function introduced with Carlos 0.6 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The conditionedPostProcess function takes a CacheLevel and a conditioned transformer conforming to ConditionedOneWayTransformer as parameters and outputs a decorated CacheLevel with the conditional post-processing step embedded in.

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.conditionedPostProcess(ConditionedOneWayTransformationBox(conditionalTransformClosure: { (key, value) in
    if key == "some sentinel value" {
        return Just(value.uppercased()).eraseToAnyPublisher()
    } else {
        return Just(value).eraseToAnyPublisher()
    }
})

// Lowercase value set on the memory layer
memoryCache.set("test String", forKey: "some sentinel value")

// We get the lowercase value from the undecorated memory layer
memoryCache.get("some sentinel value").sink { value in
  let x = value
}

// We get the uppercase value from the decorated cache, though
transformedCache.get("some sentinel value").sink { value in
  let x = value
}

Conditioned value transformation

Extending the case for simple value transformation, you can also apply conditional transformations based on the key used to fetch or set the value.

For these cases, the conditionedValueTransformation function introduced with Carlos 0.6 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The conditionedValueTransformation function takes a CacheLevel and a conditioned transformer conforming to ConditionedTwoWayTransformer as parameters and outputs a decorated CacheLevel with a modified OutputType (equal to the transformer's TypeOut, as in the normal value transformation case) with the conditional value transformation step embedded in.

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.conditionedValueTransformation(ConditionedTwoWayTransformationBox(conditionalTransformClosure: { (key, value) in
    if key == "some sentinel value" {
        return Just(1).eraseToAnyPublisher()
    } else {
        return Just(0).eraseToAnyPublisher()
    }
}, conditionalInverseTransformClosure: { (key, value) in
    if key > 0 {
        return Just("Positive").eraseToAnyPublisher()
    } else {
        return Just("Null or negative").eraseToAnyPublisher()
    }
})

// Value set on the memory layer
memoryCache.set("test String", forKey: "some sentinel value")

// We get the same value from the undecorated memory layer
memoryCache.get("some sentinel value").sink { value in
  let x = value
}

// We get 1 from the decorated cache, though
transformedCache.get("some sentinel value").sink { value in
  let x = value
}

// We set "Positive" on the decorated cache
transformedCache.set(5, forKey: "test")

Composing transformers

As of Carlos 0.4, it's possible to compose multiple OneWayTransformer objects. This way, one can create several transformer modules to build a small library and then combine them as more convenient depending on the application.

You can compose the transformers in the same way you do with normal CacheLevels: with the compose protocol extension:

let firstTransformer = ImageTransformer() // NSData -> UIImage
let secondTransformer = ImageTransformer().invert() // Trivial UIImage -> NSData

let identityTransformer = firstTransformer.compose(secondTransformer)

The same approach can be applied to TwoWayTransformer objects (that by the way are already OneWayTransformer as well).

Many transformer modules will be provided by default with Carlos.

Pooling requests

When you have a working cache, but some of your levels are expensive (say a Network fetcher or a database fetcher), you may want to pool requests in a way that multiple requests for the same key, coming together before one of them completes, are grouped so that when one completes all of the other complete as well without having to actually perform the expensive operation multiple times.

This functionality comes with Carlos.

let cache = (memoryLevel.compose(diskLevel).compose(networkLevel)).pooled()

Keep in mind that the key must conform to the Hashable protocol for the pooled function to work:

extension Image: Hashable {
  var hashValue: Int {
    return identifier.hashValue
  }
}

extension Image: Equatable {}

func ==(lhs: Image, rhs: Image) -> Bool {
  return lhs.identifier == rhs.identifier && lhs.URL == rhs.URL
}

Now we can execute multiple fetches for the same Image value and be sure that only one network request will be started.

Batching get requests

Since Carlos 0.7 you can pass a list of keys to your CacheLevel through batchGetSome. This returns a AnyPublisher that succeeds when all the requests for the specified keys complete, not necessarily succeeding. You will only get the successful values in the success callback, though.

Since Carlos 0.9 you can transform your CacheLevel into one that takes a list of keys through allBatch. Calling get on such a CacheLevel returns a AnyPublisher that succeeds only when the requests for all of the specified keys succeed, and fails as soon as one of the requests for the specified keys fails. If you cancel the AnyPublisher returned by this CacheLevel, all of the pending requests are canceled, too.

An example of the usage:

let cache = MemoryCacheLevel<String, Int>()

for iter in 0..<99 {
  cache.set(iter, forKey: "key_\(iter)")
}

let keysToBatch = (0..<100).map { "key_\($0)" }

cache.batchGetSome(keysToBatch).sink(
    receiveCompletion: { completion in 
        print("Failed because \($0)")
    },
    receiveValue: { values in 
        print("Got \(values.count) values in total")
    }
)

In this case the allBatch().get call would fail because there are only 99 keys set and the last request will make the whole batch fail, with a valueNotInCache error. The batchGetSome().get will succeed instead, printing Got 99 values in total.

Since allBatch returns a new CacheLevel instance, it can be composed or transformed just like any other cache:

In this case cache is a cache that takes a sequence of String keys and returns a AnyPublisher of a list of Int values, but is limited to 3 concurrent requests (see the next paragraph for more information on limiting concurrent requests).

Conditioning caches

Sometimes we may have levels that should only be queried under some conditions. Let's say we have a DatabaseLevel that should only be triggered when users enable a given setting in the app that actually starts storing data in the database. We may want to avoid accessing the database if the setting is disabled in the first place.

let conditionedCache = cache.conditioned { key in
  Just(appSettingIsEnabled).eraseToAnyPublisher()
}

The closure gets the key the cache was asked to fetch and has to return a AnyPublisher<Bool, Error> object indicating whether the request can proceed or should skip the level, with the possibility to fail with a specific Error to communicate the error to the caller.

At runtime, if the variable appSettingIsEnabled is false, the get request will skip the level (or fail if this was the only or last level in the cache). If true, the get request will be executed.

Multiple cache lanes

If you have a complex scenario where, depending on the key or some other external condition, either one or another cache should be used, then the switchLevels function could turn useful.

Usage:

let lane1 = MemoryCacheLevel<URL, NSData>() // The two lanes have to be equivalent (same key type, same value type).
let lane2 = CacheProvider.dataCache() // Keep in mind that you can always use key transformation or value transformations if two lanes don't match by default

let switched = switchLevels(lane1, lane2) { key in
  if key.scheme == "http" {
      return .cacheA
  } else {
       return .cacheB // The example is just meant to show how to return different lanes
  }
}

Now depending on the scheme of the key URL, either the first lane or the second will be used.

Listening to memory warnings

If we store big objects in memory in our cache levels, we may want to be notified of memory warning events. This is where the listenToMemoryWarnings and unsubscribeToMemoryWarnings functions come handy:

let token = cache.listenToMemoryWarnings()

and later

unsubscribeToMemoryWarnings(token)

With the first call, the cache level and all its composing levels will get a call to onMemoryWarning when a memory warning comes.

With the second call, the behavior will stop.

Keep in mind that this functionality is not yet supported by the WatchOS 2 framework CarlosWatch.framework.

Normalization

In case you need to store the result of multiple Carlos composition calls in a property, it may be troublesome to set the type of the property to BasicCache as some calls return different types (e.g. PoolCache). In this case, you can normalize the cache level before assigning it to the property and it will be converted to a BasicCache value.

import Carlos

class CacheManager {
  let cache: BasicCache<URL, NSData>

  init(injectedCache: BasicCache<URL, NSData>) {
    self.cache = injectedCache
  }
}

[...]

let manager = CacheManager(injectedCache: CacheProvider.dataCache().pooled()) // This won't compile

let manager = CacheManager(injectedCache: CacheProvider.dataCache().pooled().normalize()) // This will

As a tip, always use normalize if you need to assign the result of multiple composition calls to a property. The call is a no-op if the value is already a BasicCache, so there will be no performance loss in that case.

Creating custom levels

Creating custom levels is easy and encouraged (after all, there are multiple cache libraries already available if you only need memory, disk and network functionalities!).

Let's see how to do it:

class MyLevel: CacheLevel {
  typealias KeyType = Int
  typealias OutputType = Float

  func get(_ key: KeyType) -> AnyPublisher<OutputType, Error> {
    Future {
      // Perform the fetch and either succeed or fail
    }.eraseToAnyPublisher()
  }

  func set(_ value: OutputType, forKey key: KeyType) -> AnyPublisher<Void, Error> {  
    Future {
      // Store the value (db, memory, file, etc) and call this on completion:
    }.eraseToAnyPublisher()
  }

  func clear() {
    // Clear the stored values
  }

  func onMemoryWarning() {
    // A memory warning event came. React appropriately
  }
}

The above class conforms to the CacheLevel protocol. First thing we need is to declare what key types we accept and what output types we return. In this example case, we have Int keys and Float output values.

The required methods to implement are 4: get, set, clear and onMemoryWarning. This sample cache can now be pipelined to a list of other caches, transforming its keys or values if needed as we saw in the earlier paragraphs.

Creating custom fetchers

With Carlos 0.4, the Fetcher protocol was introduced to make it easier for users of the library to create custom fetchers that can be used as read-only levels in the cache. An example of a "Fetcher in disguise" that has always been included in Carlos is NetworkFetcher: you can only use it to read from the network, not to write (set, clear and onMemoryWarning were no-ops).

This is how easy it is now to implement your custom fetcher:

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

  func get(_ key: KeyType) -> Anypublisher<OutputType, Error> {
    return Just("Found an hardcoded value :)").eraseToAnyPublisher()
  }
}

You still need to declare what KeyType and OutputType your CacheLevel deals with, of course, but then you're only required to implement get. Less boilerplate for you!

Built-in levels

Carlos comes with 3 cache levels out of the box:

• MemoryCacheLevel
• DiskCacheLevel
• NetworkFetcher
• Since the 0.5 release, a UserDefaultsCacheLevel

MemoryCacheLevel is a volatile cache that internally stores its values in an NSCache instance. The capacity can be specified through the initializer, and it supports clearing under memory pressure (if the level is subscribed to memory warning notifications). It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the ExpensiveObject protocol. Data, NSData, String, NSString UIImage, URL already conform to the latter protocol out of the box, while String, NSString and URL conform to the StringConvertible protocol. This cache level is thread-safe.

DiskCacheLevel is a persistent cache that asynchronously stores its values on disk. The capacity can be specified through the initializer, so that the disk size will never get too big. It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the NSCoding protocol. This cache level is thread-safe, and currently the only CacheLevel that can fail when calling set, with a DiskCacheLevelError.diskArchiveWriteFailed error.

NetworkFetcher is a cache level that asynchronously fetches values over the network. It accepts URL keys and returns NSData values. This cache level is thread-safe.

NSUserDefaultsCacheLevel is a persistent cache that stores its values on a UserDefaults persistent domain with a specific name. It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the NSCoding protocol. It has an internal soft cache used to avoid hitting the persistent storage too often, and can be cleared without affecting other values saved on the standardUserDefaults or on other persistent domains. This cache level is thread-safe.

Logging

When we decided how to handle logging in Carlos, we went for the most flexible approach that didn't require us to code a complete logging framework, that is the ability to plug-in your own logging library. If you want the output of Carlos to only be printed if exceeding a given level, if you want to completely silent it for release builds, or if you want to route it to a file, or whatever else: just assign your logging handling closure to Carlos.Logger.output:

Carlos.Logger.output = { message, level in
   myLibrary.log(message) //Plug here your logging library
}

Tests

Carlos is thouroughly tested so that the features it's designed to provide are safe for refactoring and as much as possible bug-free.

We use Quick and Nimble instead of XCTest in order to have a good BDD test layout.

As of today, there are around 1000 tests for Carlos (see the folder Tests), and overall the tests codebase is double the size of the production codebase.

Future development

Carlos is under development and here you can see all the open issues. They are assigned to milestones so that you can have an idea of when a given feature will be shipped.

If you want to contribute to this repo, please:

• Create an issue explaining your problem and your solution
• Clone the repo on your local machine
• Create a branch with the issue number and a short abstract of the feature name
• Implement your solution
• Write tests (untested features won't be merged)
• When all the tests are written and green, create a pull request, with a short description of the approach taken

Apps using Carlos

• Die Welt Edition
• Welt news

Using Carlos? Please let us know through a Pull request, we'll be happy to mention your app!

Contributors:

Vittorio Monaco, vittorio.monaco@weltn24.de, @vittoriom on Github, @Vittorio_Monaco on Twitter

Esad Hajdarevic, @esad

Acknowledgements

Carlos internally uses:

The DiskCacheLevel class is inspired by Haneke. The source code has been heavily modified, but adapting the original file has proven valuable for Carlos development.

---

Download Details:

Author: Spring-media
Source Code: https://github.com/spring-media/Carlos 
License: MIT license

#swift #ios #cache #apps 

What is GEEK

Buddha Community

A Template Language That Completely Separates Structure and Logic/Ruby

Curly

Curly is a template language that completely separates structure and logic. Instead of interspersing your HTML with snippets of Ruby, all logic is moved to a presenter class.

Installing

Installing Curly is as simple as running gem install curly-templates. If you're using Bundler to manage your dependencies, add this to your Gemfile

gem 'curly-templates'

Curly can also install an application layout file, replacing the .erb file commonly created by Rails. If you wish to use this, run the curly:install generator.

$ rails generate curly:install

How to use Curly

In order to use Curly for a view or partial, use the suffix .curly instead of .erb, e.g. app/views/posts/_comment.html.curly. Curly will look for a corresponding presenter class named Posts::CommentPresenter. By convention, these are placed in app/presenters/, so in this case the presenter would reside in app/presenters/posts/comment_presenter.rb. Note that presenters for partials are not prepended with an underscore.

Add some HTML to the partial template along with some Curly components:

<!-- app/views/posts/_comment.html.curly -->
<div class="comment">
  <p>
    {{author_link}} posted {{time_ago}} ago.
  </p>

  {{body}}

  {{#author?}}
    <p>{{deletion_link}}</p>
  {{/author?}}
</div>

The presenter will be responsible for providing the data for the components. Add the necessary Ruby code to the presenter:

# app/presenters/posts/comment_presenter.rb
class Posts::CommentPresenter < Curly::Presenter
  presents :comment

  def body
    SafeMarkdown.render(@comment.body)
  end

  def author_link
    link_to @comment.author.name, @comment.author, rel: "author"
  end

  def deletion_link
    link_to "Delete", @comment, method: :delete
  end

  def time_ago
    time_ago_in_words(@comment.created_at)
  end

  def author?
    @comment.author == current_user
  end
end

The partial can now be rendered like any other, e.g. by calling

render 'comment', comment: comment
render comment
render collection: post.comments

Curly components are surrounded by curly brackets, e.g. {{hello}}. They always map to a public method on the presenter class, in this case #hello. Methods ending in a question mark can be used for conditional blocks, e.g. {{#admin?}} ... {{/admin?}}.

Identifiers

Curly components can specify an identifier using the so-called dot notation: {{x.y.z}}. This can be very useful if the data you're accessing is hierarchical in nature. One common example is I18n:

<h1>{{i18n.homepage.header}}</h1>

# In the presenter, the identifier is passed as an argument to the method. The
# argument will always be a String.
def i18n(key)
  translate(key)
end

The identifier is separated from the component name with a dot. If the presenter method has a default value for the argument, the identifier is optional – otherwise it's mandatory.

Attributes

In addition to an identifier, Curly components can be annotated with attributes. These are key-value pairs that affect how a component is rendered.

The syntax is reminiscent of HTML:

<div>{{sidebar rows=3 width=200px title="I'm the sidebar!"}}</div>

The presenter method that implements the component must have a matching keyword argument:

def sidebar(rows: "1", width: "100px", title:); end

All argument values will be strings. A compilation error will be raised if

• an attribute is used in a component without a matching keyword argument being present in the method definition; or
• a required keyword argument in the method definition is not set as an attribute in the component.

You can define default values using Ruby's own syntax. Additionally, if the presenter method accepts arbitrary keyword arguments using the **doublesplat syntax then all attributes will be valid for the component, e.g.

def greetings(**names)
  names.map {|name, greeting| "#{name}: #{greeting}!" }.join("\n")
end

{{greetings alice=hello bob=hi}}
<!-- The above would be rendered as: -->
alice: hello!
bob: hi!

Note that since keyword arguments in Ruby are represented as Symbol objects, which are not garbage collected in Ruby versions less than 2.2, accepting arbitrary attributes represents a security vulnerability if your application allows untrusted Curly templates to be rendered. Only use this feature with trusted templates if you're not on Ruby 2.2 yet.

Conditional blocks

If there is some content you only want rendered under specific circumstances, you can use conditional blocks. The {{#admin?}}...{{/admin?}} syntax will only render the content of the block if the admin? method on the presenter returns true, while the {{^admin?}}...{{/admin?}} syntax will only render the content if it returns false.

Both forms can have an identifier: {{#locale.en?}}...{{/locale.en?}} will only render the block if the locale? method on the presenter returns true given the argument "en". Here's how to implement that method in the presenter:

class SomePresenter < Curly::Presenter
  # Allows rendering content only if the locale matches a specified identifier.
  def locale?(identifier)
    current_locale == identifier
  end
end

Furthermore, attributes can be set on the block. These only need to be specified when opening the block, not when closing it:

{{#square? width=3 height=3}}
  <p>It's square!</p>
{{/square?}}

Attributes work the same way as they do for normal components.

Collection blocks

Sometimes you want to render one or more items within the current template, and splitting out a separate template and rendering that in the presenter is too much overhead. You can instead define the template that should be used to render the items inline in the current template using the collection block syntax.

Collection blocks are opened using an asterisk:

{{*comments}}
  <li>{{body}} ({{author_name}})</li>
{{/comments}}

The presenter will need to expose the method #comments, which should return a collection of objects:

class Posts::ShowPresenter < Curly::Presenter
  presents :post

  def comments
    @post.comments
  end
end

The template within the collection block will be used to render each item, and it will be backed by a presenter named after the component – in this case, comments. The name will be singularized and Curly will try to find the presenter class in the following order:

• Posts::ShowPresenter::CommentPresenter
• Posts::CommentPresenter
• CommentPresenter

This allows you some flexibility with regards to how you want to organize these nested templates and presenters.

Note that the nested template will only have access to the methods on the nested presenter, but all variables passed to the "parent" presenter will be forwarded to the nested presenter. In addition, the current item in the collection will be passed, as well as that item's index in the collection:

class Posts::CommentPresenter < Curly::Presenter
  presents :post, :comment, :comment_counter

  def number
    # `comment_counter` is automatically set to the item's index in the collection,
    # starting with 1.
    @comment_counter
  end

  def body
    @comment.body
  end

  def author_name
    @comment.author.name
  end
end

Collection blocks are an alternative to splitting out a separate template and rendering that from the presenter – which solution is best depends on your use case.

Context blocks

While collection blocks allow you to define the template that should be used to render items in a collection right within the parent template, context blocks allow you to define the template for an arbitrary context. This is very powerful, and can be used to define widget-style components and helpers, and provide an easy way to work with structured data. Let's say you have a comment form on your page, and you'd rather keep the template inline. A simple template could look like:

<!-- post.html.curly -->
<h1>{{title}}</h1>
{{body}}

{{@comment_form}}
  <b>Name: </b> {{name_field}}<br>
  <b>E-mail: </b> {{email_field}}<br>
  {{comment_field}}

  {{submit_button}}
{{/comment_form}}

Note that an @ character is used to denote a context block. Like with collection blocks, a separate presenter class is used within the block, and a simple convention is used to find it. The name of the context component (in this case, comment_form) will be camel cased, and the current presenter's namespace will be searched:

class PostPresenter < Curly::Presenter
  presents :post
  def title; @post.title; end
  def body; markdown(@post.body); end

  # A context block method *must* take a block argument. The return value
  # of the method will be used when rendering. Calling the block argument will
  # render the nested template. If you pass a value when calling the block
  # argument it will be passed to the presenter.
  def comment_form(&block)
    form_for(Comment.new, &block)
  end

  # The presenter name is automatically deduced.
  class CommentFormPresenter < Curly::Presenter
    # The value passed to the block argument will be passed in a parameter named
    # after the component.
    presents :comment_form

    # Any parameters passed to the parent presenter will be forwarded to this
    # presenter as well.
    presents :post

    def name_field
      @comment_form.text_field :name
    end

    # ...
  end
end

Context blocks were designed to work well with Rails' helper methods such as form_for and content_tag, but you can also work directly with the block. For instance, if you want to directly control the value that is passed to the nested presenter, you can call the call method on the block yourself:

def author(&block)
  content_tag :div, class: "author" do
    # The return value of `call` will be the result of rendering the nested template
    # with the argument. You can post-process the string if you want.
    block.call(@post.author)
  end
end

Context shorthand syntax

If you find yourself opening a context block just in order to use a single component, e.g. {{@author}}{{name}}{{/author}}, you can use the shorthand syntax instead: {{author:name}}. This works for all component types, e.g.

{{#author:admin?}}
  <p>The author is an admin!</p>
{{/author:admin?}}

The syntax works for nested contexts as well, e.g. {{comment:author:name}}. Any identifier and attributes are passed to the target component, which in this example would be {{name}}.

Setting up state

Although most code in Curly presenters should be free of side effects, sometimes side effects are required. One common example is defining content for a content_for block.

If a Curly presenter class defines a setup! method, it will be called before the view is rendered:

class PostPresenter < Curly::Presenter
  presents :post

  def setup!
    content_for :title, post.title

    content_for :sidebar do
      render 'post_sidebar', post: post
    end
  end
end

Escaping Curly syntax

In order to have {{ appear verbatim in the rendered HTML, use the triple Curly escape syntax:

This is {{{escaped}}.

You don't need to escape the closing }}.

Comments

If you want to add comments to your Curly templates that are not visible in the rendered HTML, use the following syntax:

{{! This is some interesting stuff }}

Presenters

Presenters are classes that inherit from Curly::Presenter – they're usually placed in app/presenters/, but you can put them anywhere you'd like. The name of the presenter classes match the virtual path of the view they're part of, so if your controller is rendering posts/show, the Posts::ShowPresenter class will be used. Note that Curly is only used to render a view if a template can be found – in this case, at app/views/posts/show.html.curly.

Presenters can declare a list of accepted variables using the presents method:

class Posts::ShowPresenter < Curly::Presenter
  presents :post
end

A variable can have a default value:

class Posts::ShowPresenter < Curly::Presenter
  presents :post
  presents :comment, default: nil
end

Any public method defined on the presenter is made available to the template as a component:

class Posts::ShowPresenter < Curly::Presenter
  presents :post

  def title
    @post.title
  end

  def author_link
    # You can call any Rails helper from within a presenter instance:
    link_to author.name, profile_path(author), rel: "author"
  end

  private

  # Private methods are not available to the template, so they're safe to
  # use.
  def author
    @post.author
  end
end

Presenter methods can even take an argument. Say your Curly template has the content {{t.welcome_message}}, where welcome_message is an I18n key. The following presenter method would make the lookup work:

def t(key)
  translate(key)
end

That way, simple ``functions'' can be added to the Curly language. Make sure these do not have any side effects, though, as an important part of Curly is the idempotence of the templates.

Layouts and content blocks

Both layouts and content blocks (see content_for) use yield to signal that content can be inserted. Curly works just like ERB, so calling yield with no arguments will make the view usable as a layout, while passing a Symbol will make it try to read a content block with the given name:

# Given you have the following Curly template in
# app/views/layouts/application.html.curly
#
#   <html>
#     <head>
#       <title>{{title}}</title>
#     </head>
#     <body>
#       <div id="sidebar">{{sidebar}}</div>
#       {{body}}
#     </body>
#   </html>
#
class ApplicationLayout < Curly::Presenter
  def title
    "You can use methods just like in any other presenter!"
  end

  def sidebar
    # A view can call `content_for(:sidebar) { "some HTML here" }`
    yield :sidebar
  end

  def body
    # The view will be rendered and inserted here:
    yield
  end
end

Rails helper methods

In order to make a Rails helper method available as a component in your template, use the exposes_helper method:

class Layouts::ApplicationPresenter < Curly::Presenter
  # The components {{sign_in_path}} and {{root_path}} are made available.
  exposes_helper :sign_in_path, :root_path
end

Testing

Presenters can be tested directly, but sometimes it makes sense to integrate with Rails on some levels. Currently, only RSpec is directly supported, but you can easily instantiate a presenter:

SomePresenter.new(context, assigns)

context is a view context, i.e. an object that responds to render, has all the helper methods you expect, etc. You can pass in a test double and see what you need to stub out. assigns is the hash containing the controller and local assigns. You need to pass in a key for each argument the presenter expects.

Testing with RSpec

In order to test presenters with RSpec, make sure you have rspec-rails in your Gemfile. Given the following presenter:

# app/presenters/posts/show_presenter.rb
class Posts::ShowPresenter < Curly::Presenter
  presents :post

  def body
    Markdown.render(@post.body)
  end
end

You can test the presenter methods like this:

# You can put this in your `spec_helper.rb`.
require 'curly/rspec'

# spec/presenters/posts/show_presenter_spec.rb
describe Posts::ShowPresenter, type: :presenter do
  describe "#body" do
    it "renders the post's body as Markdown" do
      assign(:post, double(:post, body: "**hello!**"))
      expect(presenter.body).to eq "<strong>hello!</strong>"
    end
  end
end

Note that your spec must be tagged with type: :presenter.

Examples

Here is a simple Curly template – it will be looked up by Rails automatically.

<!-- app/views/posts/show.html.curly -->
<h1>{{title}}<h1>
<p class="author">{{author}}</p>
<p>{{description}}</p>

{{comment_form}}

<div class="comments">
  {{comments}}
</div>

When rendering the template, a presenter is automatically instantiated with the variables assigned in the controller or the render call. The presenter declares the variables it expects with presents, which takes a list of variables names.

# app/presenters/posts/show_presenter.rb
class Posts::ShowPresenter < Curly::Presenter
  presents :post

  def title
    @post.title
  end

  def author
    link_to(@post.author.name, @post.author, rel: "author")
  end

  def description
    Markdown.new(@post.description).to_html.html_safe
  end

  def comments
    render 'comment', collection: @post.comments
  end

  def comment_form
    if @post.comments_allowed?
      render 'comment_form', post: @post
    else
      content_tag(:p, "Comments are disabled for this post")
    end
  end
end

Caching

Caching is handled at two levels in Curly – statically and dynamically. Static caching concerns changes to your code and templates introduced by deploys. If you do not wish to clear your entire cache every time you deploy, you need a way to indicate that some view, helper, or other piece of logic has changed.

Dynamic caching concerns changes that happen on the fly, usually made by your users in the running system. You wish to cache a view or a partial and have it expire whenever some data is updated – usually whenever a specific record is changed.

Dynamic Caching

Because of the way logic is contained in presenters, caching entire views or partials by the data they present becomes exceedingly straightforward. Simply define a #cache_key method that returns a non-nil object, and the return value will be used to cache the template.

Whereas in ERB you would include the cache call in the template itself:

<% cache([@post, signed_in?]) do %>
  ...
<% end %>

In Curly you would instead declare it in the presenter:

class Posts::ShowPresenter < Curly::Presenter
  presents :post

  def cache_key
    [@post, signed_in?]
  end
end

Likewise, you can add a #cache_duration method if you wish to automatically expire the fragment cache:

class Posts::ShowPresenter < Curly::Presenter
  ...

  def cache_duration
    30.minutes
  end
end

In order to set any cache option, define a #cache_options method that returns a Hash of options:

class Posts::ShowPresenter < Curly::Presenter
  ...

  def cache_options
    { compress: true, namespace: "my-app" }
  end
end

Static Caching

Static caching will only be enabled for presenters that define a non-nil #cache_key method (see Dynamic Caching.)

In order to make a deploy expire the cache for a specific view, set the version of the view to something new, usually by incrementing by one:

class Posts::ShowPresenter < Curly::Presenter
  version 3

  def cache_key
    # Some objects
  end
end

This will change the cache keys for all instances of that view, effectively expiring the old cache entries.

This works well for views, or for partials that are rendered in views that themselves are not cached. If the partial is nested within a view that is cached, however, the outer cache will not be expired. The solution is to register that the inner partial is a dependency of the outer one such that Curly can automatically deduce that the outer partial cache should be expired:

class Posts::ShowPresenter < Curly::Presenter
  version 3
  depends_on 'posts/comment'

  def cache_key
    # Some objects
  end
end

class Posts::CommentPresenter < Curly::Presenter
  version 4

  def cache_key
    # Some objects
  end
end

Now, if the version of Posts::CommentPresenter is bumped, the cache keys for both presenters would change. You can register any number of view paths with depends_on.

Curly integrates well with the caching mechanism in Rails 4 (or Cache Digests in Rails 3), so the dependencies defined with depends_on will be tracked by Rails. This will allow you to deploy changes to your templates and have the relevant caches automatically expire.

Thanks

Thanks to Zendesk for sponsoring the work on Curly.

Contributors

• Daniel Schierbeck (@dasch)
• Benjamin Quorning (@bquorning)
• Jeremy Rodi (@medcat)
• Alisson Cavalcante Agiani (@thelinuxlich)
• Łukasz Niemier (@hauleth)
• Cristian Planas (@Gawyn)
• Steven Davidovitz (@steved)

Build Status

---

Author: zendesk
Source code: https://github.com/zendesk/curly

#ruby   #ruby-on-rails 

Carlos: A Simple But Flexible Cache

Carlos

A simple but flexible cache, written in Swift for iOS 13+ and WatchOS 6 apps.

Breaking Changes

Carlos 1.0.0 has been migrated from PiedPiper dependency to Combine hence the minimum supported platforms versions are equal to the Combine's minimum supported platforms versions. See the releases page for more information.

What is Carlos?

Carlos is a small set of classes and functions to realize custom, flexible and powerful cache layers in your application.

With a Functional Programming vocabulary, Carlos makes for a monoidal cache system. You can check the best explanation of how that is realized here or in this video, thanks to @bkase for the slides.

By default, Carlos ships with an in-memory cache, a disk cache, a simple network fetcher and a NSUserDefaults cache (the disk cache is inspired by HanekeSwift).

With Carlos you can:

• create levels and fetchers depending on your needs
• combine levels
• Cancel pending requests
• transform the key each level will get, or the values each level will output (this means you're free to implement every level independing on how it will be used later on). Some common value transformers are already provided with Carlos
• Apply post-processing steps to a cache level, for example sanitizing the output or resizing images
• Post-processing steps and value transformations can also be applied conditionally on the key used to fetch the value
• react to memory pressure events in your app
• automatically populate upper levels when one of the lower levels fetches a value for a key, so the next time the first level will already have it cached
• enable or disable specific levels of your composed cache depending on boolean conditions
• easily pool requests so you don't have to care whether 5 requests with the same key have to be executed by an expensive cache level before even only 1 of them is done. Carlos can take care of that for you
• batch get requests to only get notified when all of them are done
• setup multiple lanes for complex scenarios where, depending on certain keys or conditions, different caches should be used
• have a type-safe complex cache that won't even compile if the code doesn't satisfy the type requirements

Installation

Swift Package Manager (Preferred)

Add Carlos to your project through the Xcode or add the following line to your package dependencies:

.package("https://github.com/spring-media/Carlos", from: "1.0.0")

CocoaPods

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

pod "Carlos", :git => "https://github.com/spring-media/Carlos"

Carthage

Carthage is also supported.

Requirements

• iOS 13.0+
• WatchOS 6+
• Xcode 12+

Usage

To run the example project, clone the repo.

Usage examples

let cache = MemoryCacheLevel<String, NSData>().compose(DiskCacheLevel())

This line will generate a cache that takes String keys and returns NSData values. Setting a value for a given key on this cache will set it for both the levels. Getting a value for a given key on this cache will first try getting it on the memory level, and if it cannot find one, will ask the disk level. In case both levels don't have a value, the request will fail. In case the disk level can fetch a value, this will also be set on the memory level so that the next fetch will be faster.

Carlos comes with a CacheProvider class so that standard caches are easily accessible.

• CacheProvider.dataCache() to create a cache that takes URL keys and returns NSData values
• CacheProvider.imageCache() to create a cache that takes URL keys and returns UIImage values
• CacheProvider.JSONCache() to create a cache that takes URL keys and returns AnyObject values (that should be then safely casted to arrays or dictionaries depending on your application)

The above methods always create new instances (so calling CacheProvider.imageCache() twice doesn't return the same instance, even though the disk level will be effectively shared because it will use the same folder on disk, but this is a side-effect and should not be relied upon) and you should take care of retaining the result in your application layer. If you want to always get the same instance, you can use the following accessors instead:

• CacheProvider.sharedDataCache to retrieve a shared instance of a data cache
• CacheProvider.sharedImageCache to retrieve a shared instance of an image cache
• CacheProvider.sharedJSONCache to retrieve a shared instance of a JSON cache

Creating requests

To fetch a value from a cache, use the get method.

cache.get("key")
  .sink( 
    receiveCompletion: { completion in 
      if case let .failure(error) = completion {
        print("An error occurred :( \(error)")
      }
    },
    receiveValue: { value in 
      print("I found \(value)!")
    }
  )

A request can also be canceled with the cancel() method, and you can be notified of this event by calling onCancel on a given request:

let cancellable = cache.get(key)
                    .handleEvents(receiveCancel: { 
                      print("Looks like somebody canceled this request!")
                    })
                    .sink(...)
[... somewhere else]
cancellable.cancel()

This cache is not very useful, though. It will never actively fetch values, just store them for later use. Let's try to make it more interesting:

let cache = MemoryCacheLevel()
              .compose(DiskCacheLevel())
              .compose(NetworkFetcher())

This will create a cache level that takes URL keys and stores NSData values (the type is inferred from the NetworkFetcher hard-requirement of URL keys and NSData values, while MemoryCacheLevel and DiskCacheLevel are much more flexible as described later).

Key transformations

Key transformations are meant to make it possible to plug cache levels in whatever cache you're building.

Let's see how they work:

// Define your custom ErrorType values
enum URLTransformationError: Error {
    case invalidURLString
}

let transformedCache = NetworkFetcher().transformKeys(
  OneWayTransformationBox(
    transform: {
      Future { promise in 
        let url = URL(string: $0) {
          promise(.success(url))
        } else {
          promise(.failure(URLTransformationError.invalidURLString))
        }
      }
    }
  )
)

With the line above, we're saying that all the keys coming into the NetworkFetcher level have to be transformed to URL values first. We can now plug this cache into a previously defined cache level that takes String keys:

let cache = MemoryCacheLevel<String, NSData>().compose(transformedCache)

If this doesn't look very safe (one could always pass string garbage as a key and it won't magically translate to a URL, thus causing the NetworkFetcher to silently fail), we can still use a domain specific structure as a key, assuming it contains both String and URL values:

struct Image {
  let identifier: String
  let URL: Foundation.URL
}

let imageToString = OneWayTransformationBox(transform: { (image: Image) -> AnyPublisher<String, String> in
    Just(image.identifier).eraseToAnyPublisher()
})

let imageToURL = OneWayTransformationBox(transform: { (image: Image) -> AnyPublisher<URL> in
    Just(image.URL).eraseToAnyPublisher()
})

let memoryLevel = MemoryCacheLevel<String, NSData>().transformKeys(imageToString)
let diskLevel = DiskCacheLevel<String, NSData>().transformKeys(imageToString)
let networkLevel = NetworkFetcher().transformKeys(imageToURL)

let cache = memoryLevel.compose(diskLevel).compose(networkLevel)

Now we can perform safe requests like this:

let image = Image(identifier: "550e8400-e29b-41d4-a716-446655440000", URL: URL(string: "http://goo.gl/KcGz8T")!)

cache.get(image).sink {
  print("Found \(value)!")
}

Since Carlos 0.5 you can also apply conditions to OneWayTransformers used for key transformations. Just call the conditioned function on the transformer and pass your condition. The condition can also be asynchronous and has to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation.

let transformer = OneWayTransformationBox<String, URL>(transform: { key in
  Future { promise in 
    if let value = URL(string: key) {
      promise(.success(value))
    } else {
      promise(.failure(MyError.stringIsNotURL))
    }
  }.eraseToAnyPublisher()
}).conditioned { key in
  Just(key)
    .filter { $0.rangeOfString("http") != nil }
    .eraseToAnyPublisher()
}

let cache = CacheProvider.imageCache().transformKeys(transformer)

That's not all, though.

What if our disk cache only stores Data, but we want our memory cache to conveniently store UIImage instances instead?

Value transformations

Value transformers let you have a cache that (let's say) stores Data and mutate it to a cache that stores UIImage values. Let's see how:

let dataTransformer = TwoWayTransformationBox(transform: { (image: UIImage) -> AnyPublisher<Data, Error> in
    Just(UIImagePNGRepresentation(image)).eraseToAnyPublisher()
}, inverseTransform: { (data: Data) -> AnyPublisher<UIImage, Error> in
    Just(UIImage(data: data)!).eraseToAnyPublisher()
})

let memoryLevel = MemoryCacheLevel<String, UIImage>().transformKeys(imageToString).transformValues(dataTransformer)

This memory level can now replace the one we had before, with the difference that it will internally store UIImage values!

Keep in mind that, as with key transformations, if your transformation closure fails (either the forward transformation or the inverse transformation), the cache level will be skipped, as if the fetch would fail. Same considerations apply for set calls.

Carlos comes with some value transformers out of the box, for example:

• JSONTransformer to serialize NSData instances into JSON
• ImageTransformer to serialize NSData instances into UIImage values (not available on the Mac OS X framework)
• StringTransformer to serialize NSData instances into String values with a given encoding
• Extensions for some Cocoa classes (DateFormatter, NumberFormatter, MKDistanceFormatter) so that you can use customized instances depending on your needs.

As of Carlos 0.4, it's possible to transform values coming out of Fetcher instances with just a OneWayTransformer (as opposed to the required TwoWayTransformer for normal CacheLevel instancess. This is because the Fetcher protocol doesn't require set). This means you can easily chain Fetchers that get a JSON from the internet and transform their output to a model object (for example a struct) into a complex cache pipeline without having to create a dummy inverse transformation just to satisfy the requirements of the TwoWayTransformer protocol.

As of Carlos 0.5, all transformers natively support asynchronous computation, so you can have expensive transformations in your custom transformers without blocking other operations. In fact, the ImageTransformer that comes out of the box processes image transformations on a background queue.

As of Carlos 0.5 you can also apply conditions to TwoWayTransformers used for value transformations. Just call the conditioned function on the transformer and pass your conditions (one for the forward transformation, one for the inverse transformation). The conditions can also be asynchronous and have to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation.

let transformer = JSONTransformer().conditioned({ input in
  Just(myCondition).eraseToAnyPublisher()
}, inverseCondition: { input in
  Just(myCondition)eraseToAnyPublisher()
})

let cache = CacheProvider.dataCache().transformValues(transformer)

Post-processing output

In some cases your cache level could return the right value, but in a sub-optimal format. For example, you would like to sanitize the output you're getting from the Cache as a whole, independently of the exact layer that returned it.

For these cases, the postProcess function introduced with Carlos 0.4 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The postProcess function takes a CacheLevel and a OneWayTransformer with TypeIn == TypeOut as parameters and outputs a decorated BasicCache with the post-processing step embedded in.

// Let's create a simple "to uppercase" transformer
let transformer = OneWayTransformationBox<NSString, String>(transform: { Just($0.uppercased() as String).eraseToAnyPublisher() })

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.postProcess(transformer)

// Lowercase value set on the memory layer
memoryCache.set("test String", forKey: "key")

// We get the lowercase value from the undecorated memory layer
memoryCache.get("key").sink { value in
  let x = value
}

// We get the uppercase value from the decorated cache, though
transformedCache.get("key").sink { value in
  let x = value
}

Since Carlos 0.5 you can also apply conditions to OneWayTransformers used for post processing transformations. Just call the conditioned function on the transformer and pass your condition. The condition can also be asynchronous and has to return a AnyPublisher<Bool, Error>, having the chance to return a specific error for the failure of the transformation. Keep in mind that the condition will actually take the output of the cache as the input, not the key used to fetch this value! If you want to apply conditions based on the key, use conditionedPostProcess instead, but keep in mind this doesn't support using OneWayTransformer instances yet.

let processer = OneWayTransformationBox<NSData, NSData>(transform: { value in
      Future { promise in 
        if let value = String(data: value as Data, encoding: .utf8)?.uppercased().data(using: .utf8) as NSData? {
          promise(.success(value))
        } else {
          promise(.failure(FetchError.conditionNotSatisfied))
        }
      }
    }).conditioned { value in
      Just(value.length < 1000).eraseToAnyPublisher()
    }

let cache = CacheProvider.dataCache().postProcess(processer)

Conditioned output post-processing

Extending the case for simple output post-processing, you can also apply conditional transformations based on the key used to fetch the value.

For these cases, the conditionedPostProcess function introduced with Carlos 0.6 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The conditionedPostProcess function takes a CacheLevel and a conditioned transformer conforming to ConditionedOneWayTransformer as parameters and outputs a decorated CacheLevel with the conditional post-processing step embedded in.

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.conditionedPostProcess(ConditionedOneWayTransformationBox(conditionalTransformClosure: { (key, value) in
    if key == "some sentinel value" {
        return Just(value.uppercased()).eraseToAnyPublisher()
    } else {
        return Just(value).eraseToAnyPublisher()
    }
})

// Lowercase value set on the memory layer
memoryCache.set("test String", forKey: "some sentinel value")

// We get the lowercase value from the undecorated memory layer
memoryCache.get("some sentinel value").sink { value in
  let x = value
}

// We get the uppercase value from the decorated cache, though
transformedCache.get("some sentinel value").sink { value in
  let x = value
}

Conditioned value transformation

Extending the case for simple value transformation, you can also apply conditional transformations based on the key used to fetch or set the value.

For these cases, the conditionedValueTransformation function introduced with Carlos 0.6 could come helpful. The function is available as a protocol extension of the CacheLevel protocol.

The conditionedValueTransformation function takes a CacheLevel and a conditioned transformer conforming to ConditionedTwoWayTransformer as parameters and outputs a decorated CacheLevel with a modified OutputType (equal to the transformer's TypeOut, as in the normal value transformation case) with the conditional value transformation step embedded in.

// Our memory cache
let memoryCache = MemoryCacheLevel<String, NSString>()

// Our decorated cache
let transformedCache = memoryCache.conditionedValueTransformation(ConditionedTwoWayTransformationBox(conditionalTransformClosure: { (key, value) in
    if key == "some sentinel value" {
        return Just(1).eraseToAnyPublisher()
    } else {
        return Just(0).eraseToAnyPublisher()
    }
}, conditionalInverseTransformClosure: { (key, value) in
    if key > 0 {
        return Just("Positive").eraseToAnyPublisher()
    } else {
        return Just("Null or negative").eraseToAnyPublisher()
    }
})

// Value set on the memory layer
memoryCache.set("test String", forKey: "some sentinel value")

// We get the same value from the undecorated memory layer
memoryCache.get("some sentinel value").sink { value in
  let x = value
}

// We get 1 from the decorated cache, though
transformedCache.get("some sentinel value").sink { value in
  let x = value
}

// We set "Positive" on the decorated cache
transformedCache.set(5, forKey: "test")

Composing transformers

As of Carlos 0.4, it's possible to compose multiple OneWayTransformer objects. This way, one can create several transformer modules to build a small library and then combine them as more convenient depending on the application.

You can compose the transformers in the same way you do with normal CacheLevels: with the compose protocol extension:

let firstTransformer = ImageTransformer() // NSData -> UIImage
let secondTransformer = ImageTransformer().invert() // Trivial UIImage -> NSData

let identityTransformer = firstTransformer.compose(secondTransformer)

The same approach can be applied to TwoWayTransformer objects (that by the way are already OneWayTransformer as well).

Many transformer modules will be provided by default with Carlos.

Pooling requests

When you have a working cache, but some of your levels are expensive (say a Network fetcher or a database fetcher), you may want to pool requests in a way that multiple requests for the same key, coming together before one of them completes, are grouped so that when one completes all of the other complete as well without having to actually perform the expensive operation multiple times.

This functionality comes with Carlos.

let cache = (memoryLevel.compose(diskLevel).compose(networkLevel)).pooled()

Keep in mind that the key must conform to the Hashable protocol for the pooled function to work:

extension Image: Hashable {
  var hashValue: Int {
    return identifier.hashValue
  }
}

extension Image: Equatable {}

func ==(lhs: Image, rhs: Image) -> Bool {
  return lhs.identifier == rhs.identifier && lhs.URL == rhs.URL
}

Now we can execute multiple fetches for the same Image value and be sure that only one network request will be started.

Batching get requests

Since Carlos 0.7 you can pass a list of keys to your CacheLevel through batchGetSome. This returns a AnyPublisher that succeeds when all the requests for the specified keys complete, not necessarily succeeding. You will only get the successful values in the success callback, though.

Since Carlos 0.9 you can transform your CacheLevel into one that takes a list of keys through allBatch. Calling get on such a CacheLevel returns a AnyPublisher that succeeds only when the requests for all of the specified keys succeed, and fails as soon as one of the requests for the specified keys fails. If you cancel the AnyPublisher returned by this CacheLevel, all of the pending requests are canceled, too.

An example of the usage:

let cache = MemoryCacheLevel<String, Int>()

for iter in 0..<99 {
  cache.set(iter, forKey: "key_\(iter)")
}

let keysToBatch = (0..<100).map { "key_\($0)" }

cache.batchGetSome(keysToBatch).sink(
    receiveCompletion: { completion in 
        print("Failed because \($0)")
    },
    receiveValue: { values in 
        print("Got \(values.count) values in total")
    }
)

In this case the allBatch().get call would fail because there are only 99 keys set and the last request will make the whole batch fail, with a valueNotInCache error. The batchGetSome().get will succeed instead, printing Got 99 values in total.

Since allBatch returns a new CacheLevel instance, it can be composed or transformed just like any other cache:

In this case cache is a cache that takes a sequence of String keys and returns a AnyPublisher of a list of Int values, but is limited to 3 concurrent requests (see the next paragraph for more information on limiting concurrent requests).

Conditioning caches

Sometimes we may have levels that should only be queried under some conditions. Let's say we have a DatabaseLevel that should only be triggered when users enable a given setting in the app that actually starts storing data in the database. We may want to avoid accessing the database if the setting is disabled in the first place.

let conditionedCache = cache.conditioned { key in
  Just(appSettingIsEnabled).eraseToAnyPublisher()
}

The closure gets the key the cache was asked to fetch and has to return a AnyPublisher<Bool, Error> object indicating whether the request can proceed or should skip the level, with the possibility to fail with a specific Error to communicate the error to the caller.

At runtime, if the variable appSettingIsEnabled is false, the get request will skip the level (or fail if this was the only or last level in the cache). If true, the get request will be executed.

Multiple cache lanes

If you have a complex scenario where, depending on the key or some other external condition, either one or another cache should be used, then the switchLevels function could turn useful.

Usage:

let lane1 = MemoryCacheLevel<URL, NSData>() // The two lanes have to be equivalent (same key type, same value type).
let lane2 = CacheProvider.dataCache() // Keep in mind that you can always use key transformation or value transformations if two lanes don't match by default

let switched = switchLevels(lane1, lane2) { key in
  if key.scheme == "http" {
      return .cacheA
  } else {
       return .cacheB // The example is just meant to show how to return different lanes
  }
}

Now depending on the scheme of the key URL, either the first lane or the second will be used.

Listening to memory warnings

If we store big objects in memory in our cache levels, we may want to be notified of memory warning events. This is where the listenToMemoryWarnings and unsubscribeToMemoryWarnings functions come handy:

let token = cache.listenToMemoryWarnings()

and later

unsubscribeToMemoryWarnings(token)

With the first call, the cache level and all its composing levels will get a call to onMemoryWarning when a memory warning comes.

With the second call, the behavior will stop.

Keep in mind that this functionality is not yet supported by the WatchOS 2 framework CarlosWatch.framework.

Normalization

In case you need to store the result of multiple Carlos composition calls in a property, it may be troublesome to set the type of the property to BasicCache as some calls return different types (e.g. PoolCache). In this case, you can normalize the cache level before assigning it to the property and it will be converted to a BasicCache value.

import Carlos

class CacheManager {
  let cache: BasicCache<URL, NSData>

  init(injectedCache: BasicCache<URL, NSData>) {
    self.cache = injectedCache
  }
}

[...]

let manager = CacheManager(injectedCache: CacheProvider.dataCache().pooled()) // This won't compile

let manager = CacheManager(injectedCache: CacheProvider.dataCache().pooled().normalize()) // This will

As a tip, always use normalize if you need to assign the result of multiple composition calls to a property. The call is a no-op if the value is already a BasicCache, so there will be no performance loss in that case.

Creating custom levels

Creating custom levels is easy and encouraged (after all, there are multiple cache libraries already available if you only need memory, disk and network functionalities!).

Let's see how to do it:

class MyLevel: CacheLevel {
  typealias KeyType = Int
  typealias OutputType = Float

  func get(_ key: KeyType) -> AnyPublisher<OutputType, Error> {
    Future {
      // Perform the fetch and either succeed or fail
    }.eraseToAnyPublisher()
  }

  func set(_ value: OutputType, forKey key: KeyType) -> AnyPublisher<Void, Error> {  
    Future {
      // Store the value (db, memory, file, etc) and call this on completion:
    }.eraseToAnyPublisher()
  }

  func clear() {
    // Clear the stored values
  }

  func onMemoryWarning() {
    // A memory warning event came. React appropriately
  }
}

The above class conforms to the CacheLevel protocol. First thing we need is to declare what key types we accept and what output types we return. In this example case, we have Int keys and Float output values.

The required methods to implement are 4: get, set, clear and onMemoryWarning. This sample cache can now be pipelined to a list of other caches, transforming its keys or values if needed as we saw in the earlier paragraphs.

Creating custom fetchers

With Carlos 0.4, the Fetcher protocol was introduced to make it easier for users of the library to create custom fetchers that can be used as read-only levels in the cache. An example of a "Fetcher in disguise" that has always been included in Carlos is NetworkFetcher: you can only use it to read from the network, not to write (set, clear and onMemoryWarning were no-ops).

This is how easy it is now to implement your custom fetcher:

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

  func get(_ key: KeyType) -> Anypublisher<OutputType, Error> {
    return Just("Found an hardcoded value :)").eraseToAnyPublisher()
  }
}

You still need to declare what KeyType and OutputType your CacheLevel deals with, of course, but then you're only required to implement get. Less boilerplate for you!

Built-in levels

Carlos comes with 3 cache levels out of the box:

• MemoryCacheLevel
• DiskCacheLevel
• NetworkFetcher
• Since the 0.5 release, a UserDefaultsCacheLevel

MemoryCacheLevel is a volatile cache that internally stores its values in an NSCache instance. The capacity can be specified through the initializer, and it supports clearing under memory pressure (if the level is subscribed to memory warning notifications). It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the ExpensiveObject protocol. Data, NSData, String, NSString UIImage, URL already conform to the latter protocol out of the box, while String, NSString and URL conform to the StringConvertible protocol. This cache level is thread-safe.

DiskCacheLevel is a persistent cache that asynchronously stores its values on disk. The capacity can be specified through the initializer, so that the disk size will never get too big. It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the NSCoding protocol. This cache level is thread-safe, and currently the only CacheLevel that can fail when calling set, with a DiskCacheLevelError.diskArchiveWriteFailed error.

NetworkFetcher is a cache level that asynchronously fetches values over the network. It accepts URL keys and returns NSData values. This cache level is thread-safe.

NSUserDefaultsCacheLevel is a persistent cache that stores its values on a UserDefaults persistent domain with a specific name. It accepts keys of any given type that conforms to the StringConvertible protocol and can store values of any given type that conforms to the NSCoding protocol. It has an internal soft cache used to avoid hitting the persistent storage too often, and can be cleared without affecting other values saved on the standardUserDefaults or on other persistent domains. This cache level is thread-safe.

Logging

When we decided how to handle logging in Carlos, we went for the most flexible approach that didn't require us to code a complete logging framework, that is the ability to plug-in your own logging library. If you want the output of Carlos to only be printed if exceeding a given level, if you want to completely silent it for release builds, or if you want to route it to a file, or whatever else: just assign your logging handling closure to Carlos.Logger.output:

Carlos.Logger.output = { message, level in
   myLibrary.log(message) //Plug here your logging library
}

Tests

Carlos is thouroughly tested so that the features it's designed to provide are safe for refactoring and as much as possible bug-free.

We use Quick and Nimble instead of XCTest in order to have a good BDD test layout.

As of today, there are around 1000 tests for Carlos (see the folder Tests), and overall the tests codebase is double the size of the production codebase.

Future development

Carlos is under development and here you can see all the open issues. They are assigned to milestones so that you can have an idea of when a given feature will be shipped.

If you want to contribute to this repo, please:

• Create an issue explaining your problem and your solution
• Clone the repo on your local machine
• Create a branch with the issue number and a short abstract of the feature name
• Implement your solution
• Write tests (untested features won't be merged)
• When all the tests are written and green, create a pull request, with a short description of the approach taken

Apps using Carlos

• Die Welt Edition
• Welt news

Using Carlos? Please let us know through a Pull request, we'll be happy to mention your app!

Contributors:

Vittorio Monaco, vittorio.monaco@weltn24.de, @vittoriom on Github, @Vittorio_Monaco on Twitter

Esad Hajdarevic, @esad

Acknowledgements

Carlos internally uses:

The DiskCacheLevel class is inspired by Haneke. The source code has been heavily modified, but adapting the original file has proven valuable for Carlos development.

---

Download Details:

Author: Spring-media
Source Code: https://github.com/spring-media/Carlos 
License: MIT license

#swift #ios #cache #apps 

Caching In WordPress: What You Need to Learn?

WordPress caching has nothing new to showcase in this context. WordPress websites also run on a specific server system and you have to make sure these servers work well for user engagement. So caching can help your website server work effectively to serve too many visitors collectively. The commonly requested items can be converted into varied copies that the website server doesn’t want to showcase every time to every website visitor. Classification of Caching is usually divided into two kinds. The Client-Side Caching & the Server Side Caching. Where client-side caching has nothing to do with your website, Server Side Caching is usually its opposite. Read more on https://bit.ly/3rbqvVh

#caching plugins #server side caching #client side caching #wordpress websites #wordpress caching

What is Distributed Caching

In this tutorial we are going to learn about what a cache is ? when we are going to use?, and How to use it? in a detailed manner.

So first of all,

What is a Cache?

Imagine that you have a system like this. Client Application request for some results from the server and the server asks those details form the Database. Then Database pullout the results to the Application server. Without pulling data from the Database all the time we can maintain another database/server to store data called Cache. Here there are 2 scenarios that you might want to use a cache.

• When you requesting for a commonly used data, and every time we ask for those data we need to provide from the Database. Instead of this, you can save those commonly used data in a cache (in-memory cache). Here we can reduce network calls.
• When you are doing a calculation by getting data from the database. You can reduce the number of calculations here. Store the result in cache and get the value from the cache without doing recomputations all the time. (Example: Assume you have a Student Management System and you need to calculate the average marks for a particular exam for a particular student. Store Average value in cache memory with key-value pair.)
• We have all servers and they are hitting the database. It’s going to be a lot of loads. Instead of getting one cache, we can use more caches as a distributed system for Avoid load in the Database.

Can we store all the data in the cache?

No! We can’t store all the data in the cache because of multiple reasons.

• The hardware that we use to make cache memories is much more expensive than a normal database.
• If you store a ton of data on cache the search time will increase compared to the database.

So that now you know we can store infinite data on the database and we need to store the most valuable data in the cache.

When do you load data into the cache? When do you evict data from the cache?

Loading or Evicting data from the cache is called a Policy. So the cache performance depends on your cache policy. There are a number of policies you can have. The Most popular one is LRU(Least Recently Used).

**LRU **— you can add recently used entries to the bottom of the cache and least recently used entries go to the bottom. If you want to add new entries but the cache is almost full, then you can evict(kick) out those least recently used data.

Some other Policies are,

• Least Recently Used (LRU)
• First In First Out (FIFO)
• Random

#distributed-cache #caching-server #redis #caching

Best WordPress Caching Plugins Comparison

WordPress caching plugins  is a complex topic for many people (especially newcomers), and there’s a lot to cover in any  guide. A comprehensive exploration of WordPress caching  might even demand a whole book — which we obviously don’t have the space or time to create here. But we _can _ make the essentials of [WordPress] caching easier to understand, and that’s exactly what we’ll do below.

First, let’s start by looking at caching it as if it were a fairly straightforward math problem to be solved. Most of you reading this would have no problem multilying, say, eight by eight to get 64. That’s a simple sum countless children learn in school every year.

#cache #wordpress #wordpress caching #wp #caching plugin