The protocol-oriented persistence engine for Swift.

// Initialize on-disk SwiftData store
let storage = try LocalStorage()

// Save a Codable model with a 2-hour TTL
try await storage.save(product, expiration: .hours(2))

// Fetch live record by primary key
let item: Product? = try await storage.fetch(Product.self, id: "sku_108")

final class ProductService {
    private let repository: LocalRepository<Product>
    
    init(storage: LocalStorage) {
        self.repository = storage.repository(Product.self)
    }
    
    func cache(_ product: Product) async throws {
        try await repository.save(product, expiration: .days(1))
    }
    
    func get(id: String) async throws -> Product? {
        try await repository.fetch(id: id)
    }
}

struct Product: LocalStorageIndexed {
    let id: String
    var title: String
    var category: String
    var price: Double
    var rating: Double
    
    static var storageIndexes: [StorageIndex<Product>] {
        [
            StorageIndex("category", \.category),
            StorageIndex("price", \.price),
            StorageIndex("rating", \.rating)
        ]
    }
}

// Index on a nested or root property
StorageIndex("category", \Product.category)
StorageIndex("price", \Product.price)
StorageIndex("isFeatured", \Product.isFeatured)

// Combine multiple indexed predicates
let filters: [StorageIndexFilter] = [
    .equals("category", "electronics"),
    .atLeast("rating", 4.5),
    .between("price", 100.0...500.0),
    .startsWith("sku", "TECH_")
]

let results = try await storage.fetch(Product.self, matching: filters)

// Sort ascending or descending by indexed column
let sortOrder: StorageIndexSort = .descending("rating")

let topRated = try await storage.fetch(
    Product.self,
    matching: [.equals("category", "books")],
    orderedBy: sortOrder,
    options: FetchOptions(limit: 10)
)

let options = FetchOptions(
    limit: 20,
    offset: 40,
    sort: .newestFirst,
    purgeExpired: true
)
let recentPosts = try await storage.fetch(Post.self, options: options)

let page: StoragePage<Product> = try await storage.page(
    Product.self,
    matching: [.atLeast("price", 50.0)],
    orderedBy: .ascending("price"),
    page: 1,
    pageSize: 25
)

print("Page \(page.page) of \(page.totalPages), total items: \(page.totalCount)")
if page.hasNextPage {
    // Fetch page 2...
}

// Standard expiration options
let policy1: CacheExpiration = .never
let policy2: CacheExpiration = .seconds(30)
let policy3: CacheExpiration = .minutes(15)
let policy4: CacheExpiration = .hours(6)
let policy5: CacheExpiration = .days(7)
let policy6: CacheExpiration = .date(Date().addingTimeInterval(3600))

if let meta = try await storage.metadata(User.self, id: "usr_42") {
    print("Created at: \(meta.createdAt)")
    print("Updated at: \(meta.updatedAt)")
    print("Expires at: \(meta.expiresAt?.description ?? "Never")")
    print("Payload size: \(meta.sizeInBytes) bytes")
    print("Is expired: \(meta.isExpired)")
}

for await change in storage.changes(of: TaskItem.self) {
    switch change {
    case .inserted(let task):
        print("Created task: \(task.title)")
    case .updated(let task):
        print("Updated task: \(task.title)")
    case .deleted(let id):
        print("Deleted task ID: \(id)")
    case .expired(let id):
        print("Task expired ID: \(id)")
    case .cleared:
        print("All tasks cleared from cache")
    }
}

// SwiftUI ViewModel observation
@Observable @MainActor
final class FeedViewModel {
    var posts: [Post] = []
    
    func observeFeed(storage: LocalStorage) async {
        do {
            for try await updatedPosts in storage.updates(of: Post.self) {
                self.posts = updatedPosts
            }
        } catch {
            print("Stream terminated with error: \(error)")
        }
    }
}

struct UserProfile: LocalStorageVersioned {
    let id: String
    var fullName: String
    var email: String
    
    static var currentVersion: Int { 2 }
    
    static var migrations: [StorageMigration] {
        [
            StorageMigration(from: 1, to: 2) { oldData in
                // Transform V1 legacy JSON payload into V2 schema
                var json = try JSONSerialization.jsonObject(with: oldData) as! [String: Any]
                let first = json.removeValue(forKey: "firstName") as? String ?? ""
                let last = json.removeValue(forKey: "lastName") as? String ?? ""
                json["fullName"] = "\(first) \(last)".trimmingCharacters(in: .whitespaces)
                return try JSONSerialization.data(withJSONObject: json)
            }
        ]
    }
}

let v1ToV2 = StorageMigration(from: 1, to: 2) { data in
    var json = try JSONDecoder().decode(LegacyPayload.self, from: data)
    let upgraded = ModernPayload(legacy: json)
    return try JSONEncoder().encode(upgraded)
}

public protocol StorageLogger: Sendable {
    func log(level: StorageLogLevel, message: String, metadata: [String: String]?)
    func record(duration: TimeInterval, operation: String)
}

let osLogger = OSLogStorageLogger(
    subsystem: "com.acme.app",
    category: "LocalStorage"
)

let storage = try LocalStorage(
    configuration: .default,
    logger: osLogger
)

final class UserViewModelTests: XCTestCase {
    func testUserSave() async throws {
        let storage = try LocalStorage(configuration: .inMemory)
        let repository = storage.repository(User.self)
        
        try await repository.save(User.mock)
        let fetched = try await repository.fetch(id: User.mock.id)
        
        XCTAssertEqual(fetched?.name, User.mock.name)
    }
}

do {
    let user = try await storage.fetch(User.self, id: "usr_99")
} catch LocalStorageError.notFound(let id) {
    print("Record \(id) not found or expired")
} catch LocalStorageError.decodingFailed(let reason) {
    print("Schema mismatch: \(reason)")
} catch LocalStorageError.migrationFailed(let from, let to, let err) {
    print("Migration \(from)->\(to) failed: \(err)")
} catch {
    print("Storage engine error: \(error)")
}

var config = LocalStorageConfiguration()
config.isInMemory = false
config.autoPurgeExpiredOnRead = true
config.databaseDirectory = .applicationSupportDirectory
config.logger = OSLogStorageLogger()

let storage = try LocalStorage(configuration: config)