SPB Git

Repository Public

VQFreshness.swift 4.9 KB 103 lines swift

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
Files main
Menu

Theme