Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/Data/VQFreshness.swift3// Description: The freshness vocabulary of the data layer (CONTRACT §3) and how to say it. VQuant has no streaming4// feed: nothing here ever produces the word "live".5import Foundation67public enum VQLanguage: String, Sendable, Hashable, CaseIterable {8 case fr, en9 /// The language the app itself runs in: French when the app is localised in French and the person prefers it,10 /// English otherwise. It is the app's localisation that decides (`Bundle.main.preferredLocalizations`), not the11 /// device's language list alone — an English-only app gets English strings from the package on a French device.12 public static var preferred: VQLanguage {13 (Bundle.main.preferredLocalizations.first ?? "en").lowercased().hasPrefix("fr") ? .fr : .en14 }15}1617public struct VQFreshness: Sendable, Equatable, VQJSONDecodable {18 public enum Kind: String, Sendable, Hashable, CaseIterable {19 /// provider quote fetched on request, stamped with the provider's own timestamp20 case polled21 case delayed22 /// last official close23 case eod24 case historical25 case estimated2627 public func label(_ language: VQLanguage = .preferred) -> String {28 switch self {29 case .polled: return VQL10n.string("Polled", language)30 case .delayed: return VQL10n.string("Delayed", language)31 case .eod: return VQL10n.string("Close (end of day)", language)32 case .historical: return VQL10n.string("Historical", language)33 case .estimated: return VQL10n.string("Estimated", language)34 }35 }3637 /// One sentence for a tooltip or an accessibility hint.38 public func explanation(_ language: VQLanguage = .preferred) -> String {39 switch self {40 case .polled: return VQL10n.string("Quote requested from the provider when displayed, stamped by the provider. Not a continuous feed.", language)41 case .delayed: return VQL10n.string("Data published with a delay by the exchange or the provider.", language)42 case .eod: return VQL10n.string("End-of-day data: the last official close.", language)43 case .historical: return VQL10n.string("Historical series: it no longer changes, unless the provider revises it.", language)44 case .estimated: return VQL10n.string("Estimated or derived value, for lack of an observation.", language)45 }46 }4748 /// A glyph per kind so the kind reads without colour: ● polled, ◐ delayed, ○ close, ▫ historical, ≈ estimated.49 public var glyph: String {50 switch self {51 case .polled: return "●"52 case .delayed: return "◐"53 case .eod: return "○"54 case .historical: return "▫"55 case .estimated: return "≈"56 }57 }58 }5960 public var kind: VQOpen<Kind>61 /// The provider's own timestamp of the data (nil when it gives none).62 public var asOf: Date?63 public var provider: String?64 public var retrievedAt: Date?65 public var note: String?6667 public init(kind: Kind, asOf: Date? = nil, provider: String? = nil, retrievedAt: Date? = nil, note: String? = nil) {68 self.kind = .known(kind); self.asOf = asOf; self.provider = provider; self.retrievedAt = retrievedAt; self.note = note69 }70 public init(json j: VQJSON) {71 kind = j.open("kind", .historical); asOf = j.date("asOf"); provider = j.optStr("provider"); retrievedAt = j.date("retrievedAt"); note = j.optStr("note")72 }7374 public static func providerName(_ id: String?) -> String? {75 guard let id, !id.isEmpty else { return nil }76 switch id.lowercased() {77 case "fmp": return "FMP"78 case "findata": return "FinData"79 case "eodhd": return "EODHD"80 case "vquant": return "VQuant"81 default: return id82 }83 }8485 /// The kind's label; a kind this version does not know is shown by its own name — never as "live".86 public func kindLabel(_ language: VQLanguage = .preferred) -> String {87 switch kind {88 case .known(let k): return k.label(language)89 case .unknown(let raw):90 let lowered = raw.lowercased()91 return lowered == "live" || lowered == "realtime" || lowered == "real-time" ? Kind.polled.label(language) : raw.capitalized92 }93 }9495 /// "Interrogé · FMP · 14 h 05" — kind, provider, as-of (time today, date otherwise).96 public func displayText(_ language: VQLanguage = .preferred, now: Date = Date(), timeZone: TimeZone = .current) -> String {97 var parts = [kindLabel(language)]98 if let p = VQFreshness.providerName(provider) { parts.append(p) }99 if let asOf { parts.append(VQFormat.asOf(asOf, now: now, language: language, timeZone: timeZone)) }100 return parts.joined(separator: " · ")101 }102}103