CacheKit

CacheKit is a Swift 6-native cache library for iOS. It provides memory, disk, hybrid, and content-addressed file caches with synchronous and Swift Concurrency APIs.

The core cache deliberately uses a proven architecture: an in-memory LRU backed by SQLite metadata and external files for large values. CacheKit does not introduce a new cache algorithm. Its focus is a type-safe Swift API, explicit codecs, predictable concurrency, transactional batch operations, and a dedicated file cache.

Requirements

• iOS 15.0+
• Swift 6.0+
• Xcode 16.0+

Installation

Swift Package Manager

Add the package URL in Xcode, or add it to Package.swift:

dependencies: [
    .package(url: "https://github.com/FeliksLv01/CacheKit.git", from: "0.1.2")
]

Then add CacheKit to the target dependencies.

CocoaPods

pod 'CacheKit',
    git: 'https://github.com/FeliksLv01/CacheKit.git',
    tag: '0.1.2'

The runtime library has no third-party dependencies. It links the system SQLite library. Cache and YYCache are used by the benchmark target only and are not exposed to clients.

Usage

import CacheKit

let root = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
let configuration = CacheConfiguration(
    name: "documents",
    directoryURL: root,
    storageMode: .hybrid
)
let cache = try CacheKit.Cache<Data>(configuration: configuration, codec: .data)

try cache.setValue(Data("hello".utf8), forKey: "greeting")
let value = try cache.value(forKey: "greeting")

let loaded = try await cache.async.value(forKey: "profile", orLoad: {
    try await downloadProfile()
})

CacheCodec.codable provides JSON encoding for Codable values. Custom codecs can be supplied for other formats.

File cache

let fileCache = try FileCache(
    configuration: FileCacheConfiguration(directoryURL: root.appendingPathComponent("files"))
)

let key = remoteURL.absoluteString
let downloadedURL = try await download(remoteURL)
let cachedURL = try await fileCache.async.storeFile(
    at: downloadedURL,
    forKey: key
)

let existingURL = try await fileCache.async.fileURL(forKey: key)

Files can have multiple aliases, are deduplicated by SHA-256 content hashes, and can be protected from eviction with acquireLease and releaseLease.

Design

• Cache<Value> is a modern Swift implementation of the established memory-LRU plus SQLite-backed disk-cache design used by mature iOS cache libraries.
• Memory LRU uses os_unfair_lock, a Swift dictionary, and a doubly linked list.
• Disk metadata uses SQLite WAL through CacheKit's focused internal SQLite layer.
• Disk values support size, count, and expiration limits.
• Large values are stored externally while small values remain inline in SQLite.
• Batch reads use a consistent snapshot; batch writes and removals use one transaction.
• Concurrent loads for the same key are coalesced into a single operation.
• Multiple cache instances for the same directory coordinate file lifecycle safely.
• FileCache adds flat content-addressed storage, SHA-256 deduplication, aliases, and leases that protect files from eviction while they are in use.

Example and benchmarks

The Example project is generated by XcodeGen and includes both the library tests and comparative benchmarks against Cache 6.0.0 and YYCache 1.0.4.

brew install xcodegen
bundle install
cd Example
./generate_project.sh
bundle exec pod install
xcodebuild -workspace CacheKitExample.xcworkspace \
  -scheme CacheKitExample \
  -configuration Release \
  -destination 'platform=iOS,id=YOUR_DEVICE_UDID' \
  DEVELOPMENT_TEAM=YOUR_TEAM_ID \
  CODE_SIGN_STYLE=Automatic \
  test | xcbeautify

The project, app target, library tests, benchmark tests, shared scheme, and Release test configuration all come from project.yml.

Existing baseline

The following measurements are from a Release build running arm64 on a physical iPhone 12 (iPhone13,2) with iOS 26.5.2 and Xcode 26.6. Memory tests perform 100,000 operations with 256-byte values. Disk tests perform 1,000 operations with 1 KB inline values. Memory keys are pre-generated before measurement and use the same input set for every compared implementation.

Scenario	CacheKit	YYCache 1.0.4	Cache 6.0.0
Memory read	0.030s	0.032s	0.055s
Memory write	0.062s	0.075s	0.127s
Disk read	0.014s	0.023s	0.185s
Disk write	0.087s	0.069s	0.951s
Concurrent disk read	0.032s	0.098s	0.322s
Concurrent mixed read/write	0.070s	0.095s	0.415s

CacheKit scenario	Time
Batch disk read	0.010s
Batch disk write	0.017s
Concurrent external disk read	0.074s

These numbers are regression baselines, not guarantees. Re-run them on representative devices and workloads before making performance decisions.

Development

Run the Swift Package tests for the supported iOS platform with:

xcodebuild test \
  -scheme CacheKit \
  -destination 'platform=iOS Simulator,name=iPhone 17' | xcbeautify

License

CacheKit is available under the MIT License. See LICENSE.