HanekeSwift

by Haneke

Haneke / HanekeSwift

A lightweight generic cache for iOS written in Swift with extra love for images.

5.0K Stars 586 Forks Last release: over 2 years ago (0.11.0) Apache License 2.0 543 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Haneke

Carthage compatible Platform Build Status Join the chat at https://gitter.im/Haneke/HanekeSwift

Haneke is a lightweight generic cache for iOS and tvOS written in Swift 4. It's designed to be super-simple to use. Here's how you would initalize a JSON cache and fetch objects from a url:

let cache = Cache(name: "github")
let URL = NSURL(string: "https://api.github.com/users/haneke")!

cache.fetch(URL: URL).onSuccess { JSON in print(JSON.dictionary?["bio"]) }

Haneke provides a memory and LRU disk cache for

UIImage
,
NSData
,
JSON
,
String
or any other type that can be read or written as data.

Particularly, Haneke excels at working with images. It includes a zero-config image cache with automatic resizing. Everything is done in background, allowing for fast, responsive scrolling. Asking Haneke to load, resize, cache and display an appropriately sized image is as simple as:

imageView.hnk_setImageFromURL(url)

Really.

Features

  • Generic cache with out-of-the-box support for
    UIImage
    ,
    NSData
    ,
    JSON
    and
    String
  • First-level memory cache using
    NSCache
  • Second-level LRU disk cache using the file system
  • Asynchronous fetching of original values from network or disk
  • All disk access is performed in background
  • Thread-safe
  • Automatic cache eviction on memory warnings or disk capacity reached
  • Comprehensive unit tests
  • Extensible by defining custom formats, supporting additional types or implementing custom fetchers

For images:

  • Zero-config
    UIImageView
    and
    UIButton
    extensions to use the cache, optimized for
    UITableView
    and
    UICollectionView
    cell reuse
  • Background image resizing and decompression

Installation

Using CocoaPods:

use_frameworks!
pod 'HanekeSwift'

Using Carthage:

github "Haneke/HanekeSwift"

Manually:

  1. Drag
    Haneke.xcodeproj
    to your project in the Project Navigator.
  2. Select your project and then your app target. Open the Build Phases panel.
  3. Expand the Target Dependencies group, and add
    Haneke.framework
    .
  4. Click on the
    +
    button at the top left of the panel and select New Copy Files Phase. Set Destination to Frameworks, and add
    Haneke.framework
    .
  5. import Haneke
    whenever you want to use Haneke.

Requirements

  • iOS 8.0+ or tvOS 9.1+
  • Swift 4

Using the cache

Haneke provides shared caches for

UIImage
,
NSData
,
JSON
and
String
. You can also create your own caches.

The cache is a key-value store. For example, here's how you would cache and then fetch some data.

let cache = Shared.dataCache

cache.set(value: data, key: "funny-games.mp4")

// Eventually...

cache.fetch(key: "funny-games.mp4").onSuccess { data in // Do something with data }

In most cases the value will not be readily available and will have to be fetched from network or disk. Haneke offers convenience

fetch
functions for these cases. Let's go back to the first example, now using a shared cache:
let cache = Shared.JSONCache
let URL = NSURL(string: "https://api.github.com/users/haneke")!

cache.fetch(URL: URL).onSuccess { JSON in print(JSON.dictionary?["bio"]) }

The above call will first attempt to fetch the required JSON from (in order) memory, disk or

NSURLCache
. If not available, Haneke will fetch the JSON from the source, return it and then cache it. In this case, the URL itself is used as the key.

Further customization can be achieved by using formats, supporting additional types or implementing custom fetchers.

Extra ♡ for images

Need to cache and display images? Haneke provides convenience methods for

UIImageView
and
UIButton
with optimizations for
UITableView
and
UICollectionView
cell reuse. Images will be resized appropriately and cached in a shared cache.
// Setting a remote image
imageView.hnk_setImageFromURL(url)

// Setting an image manually. Requires you to provide a key. imageView.hnk_setImage(image, key: key)

The above lines take care of:

  1. If cached, retrieving an appropriately sized image (based on the
    bounds
    and
    contentMode
    of the
    UIImageView
    ) from the memory or disk cache. Disk access is performed in background.
  2. If not cached, loading the original image from web/memory and producing an appropriately sized image, both in background. Remote images will be retrieved from the shared
    NSURLCache
    if available.
  3. Setting the image and animating the change if appropriate.
  4. Or doing nothing if the
    UIImageView
    was reused during any of the above steps.
  5. Caching the resulting image.
  6. If needed, evicting the least recently used images in the cache.

Formats

Formats allow to specify the disk cache size and any transformations to the values before being cached. For example, the

UIImageView
extension uses a format that resizes images to fit or fill the image view as needed.

You can also use custom formats. Say you want to limit the disk capacity for icons to 10MB and apply rounded corners to the images. This is how it could look like:

let cache = Shared.imageCache

let iconFormat = Format(name: "icons", diskCapacity: 10 * 1024 * 1024) { image in return imageByRoundingCornersOfImage(image) } cache.addFormat(iconFormat)

let URL = NSURL(string: "http://haneke.io/icon.png")! cache.fetch(URL: URL, formatName: "icons").onSuccess { image in // image will be a nice rounded icon }

Because we told the cache to use the

"icons"
format Haneke will execute the format transformation in background and return the resulting value.

Formats can also be used from the

UIKit
extensions:
imageView.hnk_setImageFromURL(url, format: iconFormat)

Fetchers

The

fetch
functions for urls and paths are actually convenience methods. Under the hood Haneke uses fetcher objects. To illustrate, here's another way of fetching from a url by explictly using a network fetcher:
let URL = NSURL(string: "http://haneke.io/icon.png")!
let fetcher = NetworkFetcher(URL: URL)
cache.fetch(fetcher: fetcher).onSuccess { image in
    // Do something with image
}

Fetching an original value from network or disk is an expensive operation. Fetchers act as a proxy for the value, and allow Haneke to perform the fetch operation only if absolutely necessary.

In the above example the fetcher will be executed only if there is no value associated with

"http://haneke.io/icon.png"
in the memory or disk cache. If that happens, the fetcher will be responsible from fetching the original value, which will then be cached to avoid further network activity.

Haneke provides two specialized fetchers:

NetworkFetcher
and
DiskFetcher
. You can also implement your own fetchers by subclassing
Fetcher
.

Custom fetchers

Through custom fetchers you can fetch original values from other sources than network or disk (e.g., Core Data), or even change how Haneke acceses network or disk (e.g., use Alamofire for networking instead of

NSURLSession
). A custom fetcher must subclass
Fetcher
and is responsible for:
  • Providing the key (e.g.,
    NSURL.absoluteString
    in the case of
    NetworkFetcher
    ) associated with the value to be fetched
  • Fetching the value in background and calling the success or failure closure accordingly, both in the main queue
  • Cancelling the fetch on demand, if possible

Fetchers are generic, and the only restriction on their type is that it must implement

DataConvertible
.

Supporting additional types

Haneke can cache any type that can be read and saved as data. This is indicated to Haneke by implementing the protocols

DataConvertible
and
DataRepresentable
.
public protocol DataConvertible {
    typealias Result

class func convertFromData(data:NSData) -> Result?

}

public protocol DataRepresentable {

func asData() -> NSData!

}

This is how one could add support for

NSDictionary
:
extension NSDictionary : DataConvertible, DataRepresentable {

public typealias Result = NSDictionary

public class func convertFromData(data:NSData) -> Result? {
    return NSKeyedUnarchiver.unarchiveObjectWithData(data) as? NSDictionary
}

public func asData() -> NSData! {
    return NSKeyedArchiver.archivedDataWithRootObject(self)
}

}

Then creating a

NSDictionary
cache would be as simple as:
let cache = Cache(name: "dictionaries")

Roadmap

Haneke Swift is in initial development and its public API should not be considered stable.

License

Copyright 2014 Hermes Pique (@hpique)
                 2014 Joan Romano (@joanromano)
                 2014 Luis Ascorbe (@lascorbe)
                 2014 Oriol Blanc (@oriolblanc)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.