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<JSON>(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,JSONandString - 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
UIImageViewandUIButtonextensions to use the cache, optimized forUITableViewandUICollectionViewcell reuse - Background image resizing and decompression
Installation
Using CocoaPods:
use_frameworks!
pod 'HanekeSwift'
Using Carthage:
github "Haneke/HanekeSwift"
.package(url: "https://github.com/Haneke/HanekeSwift.git", .upToNextMajor(from: "0.11.2")),
Then link Haneke in your App target like so:
.target(
name: "App",
dependencies: [
"Haneke",
]
),
Manually:
- Drag
Haneke.xcodeprojto your project in the Project Navigator. - Select your project and then your app target. Open the Build Phases panel.
- Expand the Target Dependencies group, and add
Haneke.framework. - Click on the
+button at the top left of the panel and select New Copy Files Phase. Set Destination to Frameworks, and addHaneke.framework. import Hanekewhenever 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:
- If cached, retrieving an appropriately sized image (based on the
boundsandcontentModeof theUIImageView) from the memory or disk cache. Disk access is performed in background. - 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
NSURLCacheif available. - Setting the image and animating the change if appropriate.
- Or doing nothing if the
UIImageViewwas reused during any of the above steps. - Caching the resulting image.
- 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<UIImage>(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<UIImage>(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<T> and DiskFetcher<T>. You can also implement your own fetchers by subclassing Fetcher<T>.
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<T> and is responsible for:
- Providing the key (e.g.,
NSURL.absoluteStringin the case ofNetworkFetcher) 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<NSDictionary>(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.
2.7k Dec 28, 2022
21 Jan 5, 2023
448 Dec 19, 2022
124 Nov 24, 2022
628 Dec 3, 2022
122 Dec 28, 2022
3 Aug 28, 2022
2.3k Dec 16, 2022
1.2k Dec 28, 2022
2.6k Dec 28, 2022
74 Nov 24, 2022
268 Nov 21, 2022
13 Jan 22, 2018
73 Aug 6, 2021
2 Feb 28, 2022
1 Oct 1, 2021
278 Jan 5, 2023
487 Jan 5, 2023