Repository Public
1import Foundation2import Observation34/// One observable read model: its explicit `state`, the last good `snapshot` (possibly restored from the offline5/// cache), a loader, and helpers to patch it from events or schedule a coalesced reload.6@MainActor7@Observable8public final class Resource<Value: Codable & Sendable> {9 public private(set) var state: Loadable<Value> = .idle10 public private(set) var snapshot: Snapshot<Value>?1112 @ObservationIgnored private let loader: @Sendable () async throws -> Value13 @ObservationIgnored private let cache: OfflineCache?14 @ObservationIgnored private let cacheKey: String?15 @ObservationIgnored private var inFlight: Task<Void, Never>?16 @ObservationIgnored private var reloadTask: Task<Void, Never>?17 @ObservationIgnored private var restoredFromCache = false18 /// True once something asked for this resource: only active resources are reloaded on events / resync.19 @ObservationIgnored public private(set) var isActive = false2021 public init(cache: OfflineCache? = nil, cacheKey: String? = nil, loader: @escaping @Sendable () async throws -> Value) {22 self.loader = loader23 self.cache = cache24 self.cacheKey = cacheKey25 }2627 /// The last good value, live or cached.28 public var value: Value? { snapshot?.value }29 public var receivedAt: Date? { snapshot?.receivedAt }30 /// True when what is shown comes from the offline cache or from before a failed refresh.31 public var isShowingStaleData: Bool {32 guard let s = snapshot else { return false }33 if s.fromCache { return true }34 if case .loaded = state { return false }35 return !state.isLoading36 }3738 /// Loads (or reloads) from the server. Concurrent callers share one request.39 public func load() async {40 isActive = true41 if let t = inFlight { await t.value; return }42 let task = Task { @MainActor [weak self] in43 guard let self else { return }44 await self.restoreIfNeeded()45 let previous = self.state46 self.state = .loading47 do {48 let v = try await self.loader()49 let now = Date()50 self.snapshot = Snapshot(value: v, receivedAt: now)51 self.state = .loaded(v, receivedAt: now)52 if let cache = self.cache, let key = self.cacheKey { await cache.store(v, key: key, receivedAt: now) }53 } catch {54 let e = APIError.from(error)55 if e.isCancelled {56 if case .loading = previous { self.state = .idle } else { self.state = previous }57 } else {58 self.state = .failure(e)59 }60 }61 self.inFlight = nil62 }63 inFlight = task64 await task.value65 }6667 /// Cancels the request in flight, if any: the view that asked for it went away. The state returns to what it68 /// was before the load started (a cancelled load is not an error); callers sharing that request see the same.69 public func cancelLoad() { inFlight?.cancel() }70 /// True while a request is in flight.71 public var isLoading: Bool { inFlight != nil }7273 /// Loads unless a value newer than `maxAge` is already there.74 public func loadIfNeeded(maxAge: TimeInterval = 20) async {75 if let s = snapshot, !s.fromCache, case .loaded = state, Date().timeIntervalSince(s.receivedAt) < maxAge {76 isActive = true77 return78 }79 await load()80 }8182 /// Shows the cached value (if any) without contacting the server.83 public func restoreIfNeeded() async {84 guard !restoredFromCache else { return }85 restoredFromCache = true86 guard snapshot == nil, let cache, let key = cacheKey else { return }87 if let s = await cache.load(Value.self, key: key), snapshot == nil { snapshot = s }88 }8990 /// Coalesced reload used by event handlers: many events in a burst cause one request. No-op for a resource91 /// nobody has asked for.92 public func scheduleReload(after delay: TimeInterval = 0.35) {93 guard isActive, reloadTask == nil else { return }94 reloadTask = Task { @MainActor [weak self] in95 try? await Task.sleep(for: .seconds(delay))96 guard let self else { return }97 self.reloadTask = nil98 if Task.isCancelled { return }99 await self.load()100 }101 }102103 /// Patches the current value in place from a server event.104 public func update(_ transform: (inout Value) -> Void) {105 guard var s = snapshot else { return }106 transform(&s.value)107 snapshot = s108 if case .loaded(_, let at) = state { state = .loaded(s.value, receivedAt: at) }109 }110111 /// Replaces the value with one just returned by the server (for example the result of a mutation).112 public func set(_ value: Value) {113 let now = Date()114 snapshot = Snapshot(value: value, receivedAt: now)115 state = .loaded(value, receivedAt: now)116 isActive = true117 if let cache, let key = cacheKey { Task { await cache.store(value, key: key, receivedAt: now) } }118 }119120 /// Forgets everything (sign-out).121 public func reset() {122 inFlight?.cancel(); inFlight = nil123 reloadTask?.cancel(); reloadTask = nil124 snapshot = nil125 state = .idle126 isActive = false127 restoredFromCache = false128 }129}130131/// Lazily created resources keyed by a parameter (node id, metric query...).132@MainActor133public final class ResourceMap<Key: Hashable & Sendable, Value: Codable & Sendable> {134 private var items: [Key: Resource<Value>] = [:]135 private let make: @MainActor (Key) -> Resource<Value>136 private let limit: Int137 private var order: [Key] = []138139 public init(limit: Int = 64, make: @escaping @MainActor (Key) -> Resource<Value>) {140 self.make = make141 self.limit = limit142 }143144 public subscript(key: Key) -> Resource<Value> {145 if let r = items[key] { return r }146 let r = make(key)147 items[key] = r148 order.append(key)149 if order.count > limit, let old = order.first {150 order.removeFirst()151 items[old] = nil152 }153 return r154 }155156 public func existing(_ key: Key) -> Resource<Value>? { items[key] }157 public var all: [Resource<Value>] { Array(items.values) }158 public func scheduleReloadAll() { items.values.forEach { $0.scheduleReload() } }159 public func reset() { items.values.forEach { $0.reset() }; items = [:]; order = [] }160}161