DepotKit: a type-safe, composable key-value store for Apple platforms

Hi everyone! We've just open-sourced DepotKit, a type-safe, composable key-value store for Apple platforms. My team at Mercedes-Benz built it, and it has stored most of the local data in the Mercedes-Benz iOS app for the past two years. 1.0.0 is the first public release, under MIT.

Every app has data that's too structured for UserDefaults but doesn't need a database: preferences, drafts, cached API responses. The usual answer is hand-rolled Codable + FileManager, which works until you need atomic writes, concurrency safety, change observation, or cache expiry. DepotKit handles those in one place.

Here's the example from the README

import DepotKit

let depot = try Depot(name: "Weather")

// A key is a typed path plus a coder; a pattern covers a whole family of keys.
let units = depot.register(#key("preferences/units", coder: .json(UnitPreferences.self)))
let forecasts = depot.register(#pattern("forecasts/*", coder: .json(Forecast.self)))

try await depot.set(value: UnitPreferences(temperature: .celsius), for: units)
let current = try await depot.get(valueFor: units)       // UnitPreferences?

let cached = try await depot.get(valuesFor: forecasts)   // [Forecast]
try await depot.remove(valuesFor: forecasts)             // drop the whole family

// Observe: the current value first, then the latest state after each change.
for await case .success(let value) in depot.values(for: units) {
    apply(value)
}

The ideas that shaped the design

  • Typed keys. Keys are declared once with the #key / #pattern macros and carry their value type, so there are no stringly-typed lookups or force casts. The macros check the path syntax at compile time. If you can't use compiler plugins, turn off the default Macros package trait and build paths with a / operator instead.
  • Key families. Patterns like "users/*/settings" or "cache/**" (.gitignore-style) let you read, count, observe, and remove a whole group of values.
  • Composable coders. JSON, property lists, raw data, and images, optionally wrapped in compression, encryption, and versioned migration. They stack like middleware: .json().versioned(version: 2) { … }.compressed(using: .lz4). Conform to Coder to add your own.
  • Observation built in. AsyncSequence, Combine publishers (DepotKitCombine), or @DepotValue / @DepotValues for SwiftUI (DepotKitObservation).

There are also transactions (buffered read-modify-write that rolls back when the closure throws, with one notification per commit), per-key expiry for cached data, app-group sharing with cross-process change detection, and a memory-only mode for previews and tests. Every operation has both a synchronous and an async variant.

What it isn't

It's not a database and isn't trying to replace SwiftData or GRDB. No queries, no relations, no sorting. Transactions aren't crash-atomic across files, and it's not meant for concurrent writers in several processes. If you need either of those, use a transactional database. Secrets belong in the Keychain. The README has a short "When Not to Use It" section, and the DocC articles on transactions and encryption and multi-process use (see the docs link below) spell out the exact guarantees.

Project status

  • 1.0.0, Semantic Versioning, MIT license
  • Swift 6.2 with strict concurrency; iOS 17, macOS 14, watchOS 10, tvOS 17, visionOS 1
  • 1,000+ tests (Swift Testing); CI fails on any warning
  • No runtime dependencies (swift-syntax is build-time only, for the macros)
  • Two years in production in the Mercedes-Benz iOS app, used by several teams. We depend on it, so we'll keep maintaining it.

There's also a demo app: a small SwiftUI weather app that uses every feature. On macOS, swift run DepotKitDemo gets you started.

What I'd love from the community

  • Feedback on the API. We designed it around our own use cases, so a fresh look at ergonomics, naming, and missing pieces would help a lot.
  • Use cases we haven't thought of. We built it for a large iOS app. If you use it somewhere else, I'd love to hear about it.
  • Contributions. See CONTRIBUTING.md in the repo. We use DCO sign-off, no CLA. Issues and PRs are welcome.

Try it

.package(url: "https://github.com/mercedes-benz/DepotKit.git", from: "1.0.0")

Docs: Swift Package Index · License: MIT

7 Likes

Thanks for posting this! I read through the docs and code and noticed a lot of interesting details, quite a cool mix of ideas here.

It'd be good to have a discussion section on how DepotKit sits with regard to FileWrapper.

The expire-on-read mechanism is clever, nice detail.

Cheers.

You're welcome!
FileWrapper is made mainly for document-based apps where the app reads the whole tree and writes it back all at the same time. In DepotKit each key is a single file and mostly unrelated to the others and we don't interact with the whole tree at once.

Thanks Fabian, I'll check it out further. You could use FileWrapper to get a zip of the depot to back it up as a unit, is one thought that came to mind. I look forward to trying DepotKit. Readers might also be interested in Disk by Saoud Rizwan (https://github.com/saoudrizwan/Disk).