feat: smart value display formats with auto-detection and per-column overrides

Author: datlechin

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Smart value detection: auto-render UUIDs in BINARY(16) columns and timestamps in integer columns
+- Per-column "Display As" override via column header context menu
 - iOS: safe mode (Off, Confirm Writes, Read-Only) per connection
 
 ## [0.27.6] - 2026-04-07

TablePro/Core/Services/Formatting/CellDisplayFormatter.swift

@@ -12,12 +12,15 @@ import Foundation
 enum CellDisplayFormatter {
     static let maxDisplayLength = 10_000
 
-    static func format(_ rawValue: String?, columnType: ColumnType?) -> String? {
+    static func format(_ rawValue: String?, columnType: ColumnType?, displayFormat: ValueDisplayFormat? = nil) -> String? {
         guard let value = rawValue, !value.isEmpty else { return rawValue }
 
         var displayValue = value
 
-        if let columnType {
+        // Apply explicit display format when set (non-raw)
+        if let displayFormat, displayFormat != .raw {
+            displayValue = ValueDisplayFormatService.applyFormat(value, format: displayFormat)
+        } else if let columnType {
             if columnType.isDateType {
                 if let formatted = DateFormattingService.shared.format(dateString: displayValue) {
                     displayValue = formatted

TablePro/Core/Services/Formatting/ValueDisplayDetector.swift

@@ -0,0 +1,121 @@
+//
+//  ValueDisplayDetector.swift
+//  TablePro
+//
+//  Heuristic auto-detection of semantic value formats.
+//  Examines column types, names, and sample values to suggest
+//  display formats like UUID or Unix timestamp.
+//
+
+import Foundation
+
+@MainActor
+enum ValueDisplayDetector {
+    /// Detect display formats for each column based on type, name, and sample values.
+    /// Returns an array parallel to `columns` where nil means no format detected (.raw).
+    static func detect(
+        columns: [String],
+        columnTypes: [ColumnType],
+        sampleValues: [[String?]]?
+    ) -> [ValueDisplayFormat?] {
+        var results = [ValueDisplayFormat?](repeating: nil, count: columns.count)
+
+        for i in 0..<columns.count {
+            let columnType = i < columnTypes.count ? columnTypes[i] : nil
+            let columnName = columns[i]
+            let sampleValue = firstNonNilSample(at: i, from: sampleValues)
+
+            if let format = detectUuid(columnType: columnType, columnName: columnName) {
+                results[i] = format
+            } else if let format = detectTimestamp(columnType: columnType, columnName: columnName, sampleValue: sampleValue) {
+                results[i] = format
+            }
+        }
+
+        return results
+    }
+
+    // MARK: - UUID Detection
+
+    private static func detectUuid(columnType: ColumnType?, columnName: String) -> ValueDisplayFormat? {
+        guard let columnType else { return nil }
+        let nameLower = columnName.lowercased()
+        let nameHint = nameLower.contains("uuid") || nameLower.contains("guid")
+            || nameLower.hasSuffix("_id") || nameLower == "id"
+
+        switch columnType {
+        case .blob(let rawType):
+            // BINARY(16) requires name hint to avoid false positives on arbitrary 16-byte data
+            guard let raw = rawType?.uppercased() else { return nil }
+            if raw.contains("BINARY") && raw.contains("(16)") && nameHint {
+                return .uuid
+            }
+        case .text(let rawType):
+            guard let raw = rawType?.uppercased() else { return nil }
+            let isCharLike = (raw.contains("CHAR") || raw.contains("VARCHAR"))
+                && (raw.contains("(32)") || raw.contains("(36)"))
+            if isCharLike && (nameLower.contains("uuid") || nameLower.contains("guid")) {
+                return .uuid
+            }
+        default:
+            break
+        }
+
+        return nil
+    }
+
+    // MARK: - Timestamp Detection
+
+    private static func detectTimestamp(
+        columnType: ColumnType?,
+        columnName: String,
+        sampleValue: String?
+    ) -> ValueDisplayFormat? {
+        guard let columnType else { return nil }
+
+        switch columnType {
+        case .integer:
+            break
+        default:
+            return nil
+        }
+
+        let nameLower = columnName.lowercased()
+        let nameMatches = nameLower.hasSuffix("_at")
+            || nameLower.hasSuffix("_time")
+            || nameLower.hasSuffix("_timestamp")
+            || nameLower == "created"
+            || nameLower == "updated"
+            || nameLower == "modified"
+            || nameLower == "timestamp"
+
+        guard nameMatches else { return nil }
+
+        // Validate with sample value if available
+        if let sample = sampleValue, let numericValue = Double(sample) {
+            // Millisecond timestamps are > 10 billion
+            if numericValue > 10_000_000_000 {
+                let seconds = numericValue / 1_000
+                guard seconds >= 946_684_800 && seconds <= 4_102_444_800 else { return nil }
+                return .unixTimestampMillis
+            }
+            guard numericValue >= 946_684_800 && numericValue <= 4_102_444_800 else { return nil }
+            return .unixTimestamp
+        }
+
+        // No sample to validate against; default to seconds
+        return .unixTimestamp
+    }
+
+    // MARK: - Helpers
+
+    private static func firstNonNilSample(at columnIndex: Int, from sampleValues: [[String?]]?) -> String? {
+        guard let samples = sampleValues else { return nil }
+        for row in samples {
+            if columnIndex < row.count, let value = row[columnIndex], !value.isEmpty {
+                return value
+            }
+        }
+        return nil
+    }
+}

TablePro/Core/Services/Formatting/ValueDisplayFormat.swift

@@ -0,0 +1,62 @@
+//
+//  ValueDisplayFormat.swift
+//  TablePro
+//
+//  Semantic display formats for raw database values.
+//  Enables auto-detection and per-column overrides for values like
+//  UUIDs stored in BINARY(16) or Unix timestamps in INT columns.
+//
+
+import Foundation
+
+enum ValueDisplayFormat: String, Codable, CaseIterable, Identifiable {
+    case raw
+    case uuid
+    case unixTimestamp
+    case unixTimestampMillis
+
+    var id: String { rawValue }
+
+    var displayName: String {
+        switch self {
+        case .raw: return String(localized: "Raw Value")
+        case .uuid: return String(localized: "UUID")
+        case .unixTimestamp: return String(localized: "Unix Timestamp (seconds)")
+        case .unixTimestampMillis: return String(localized: "Unix Timestamp (milliseconds)")
+        }
+    }
+
+    /// Column types this format can apply to.
+    var applicableColumnTypes: Set<String> {
+        switch self {
+        case .raw:
+            return []
+        case .uuid:
+            return ["blob", "text"]
+        case .unixTimestamp, .unixTimestampMillis:
+            return ["integer"]
+        }
+    }
+
+    /// Returns applicable formats for a given column type.
+    /// Always includes `.raw` as the first option.
+    static func applicableFormats(for columnType: ColumnType?) -> [ValueDisplayFormat] {
+        guard let columnType else { return [.raw] }
+
+        let typeKey: String
+        switch columnType {
+        case .blob: typeKey = "blob"
+        case .text: typeKey = "text"
+        case .integer: typeKey = "integer"
+        default: return [.raw]
+        }
+
+        var result: [ValueDisplayFormat] = [.raw]
+        for format in allCases where format != .raw {
+            if format.applicableColumnTypes.contains(typeKey) {
+                result.append(format)
+            }
+        }
+        return result
+    }
+}

TablePro/Core/Services/Formatting/ValueDisplayFormatService.swift

@@ -0,0 +1,147 @@
+//
+//  ValueDisplayFormatService.swift
+//  TablePro
+//
+//  Applies display format transformations to raw cell values
+//  and manages the effective format per column (auto-detected vs. user override).
+//
+
+import Foundation
+import os
+
+@MainActor
+final class ValueDisplayFormatService {
+    static let shared = ValueDisplayFormatService()
+
+    private static let logger = Logger(subsystem: "com.TablePro", category: "ValueDisplayFormat")
+
+    /// Auto-detected formats keyed by "connectionId.tableName.columnName" for per-connection isolation.
+    private var autoDetectedFormats: [String: ValueDisplayFormat] = [:]
+
+    private init() {}
+
+    // MARK: - Format Application
+
+    static func applyFormat(_ rawValue: String, format: ValueDisplayFormat) -> String {
+        switch format {
+        case .raw:
+            return rawValue
+        case .uuid:
+            return formatAsUuid(rawValue)
+        case .unixTimestamp:
+            return formatAsTimestamp(rawValue, divideBy: 1)
+        case .unixTimestampMillis:
+            return formatAsTimestamp(rawValue, divideBy: 1_000)
+        }
+    }
+
+    // MARK: - Effective Format Resolution
+
+    func effectiveFormat(columnName: String, connectionId: UUID?, tableName: String?) -> ValueDisplayFormat {
+        // Stored overrides take priority
+        if let connId = connectionId, let table = tableName {
+            if let overrides = ValueDisplayFormatStorage.shared.load(for: table, connectionId: connId),
+               let format = overrides[columnName] {
+                return format
+            }
+        }
+
+        // Then auto-detected (scoped by connection + table)
+        let key = scopedKey(columnName: columnName, connectionId: connectionId, tableName: tableName)
+        if let format = autoDetectedFormats[key] {
+            return format
+        }
+
+        return .raw
+    }
+
+    func setAutoDetectedFormats(_ formats: [String: ValueDisplayFormat], connectionId: UUID?, tableName: String?) {
+        // Clear previous entries for this scope
+        let prefix = scopePrefix(connectionId: connectionId, tableName: tableName)
+        autoDetectedFormats = autoDetectedFormats.filter { !$0.key.hasPrefix(prefix) }
+
+        for (columnName, format) in formats {
+            let key = scopedKey(columnName: columnName, connectionId: connectionId, tableName: tableName)
+            autoDetectedFormats[key] = format
+        }
+    }
+
+    func clearAutoDetectedFormats(connectionId: UUID?, tableName: String?) {
+        let prefix = scopePrefix(connectionId: connectionId, tableName: tableName)
+        autoDetectedFormats = autoDetectedFormats.filter { !$0.key.hasPrefix(prefix) }
+    }
+
+    // MARK: - Scoping
+
+    private func scopePrefix(connectionId: UUID?, tableName: String?) -> String {
+        "\(connectionId?.uuidString ?? "_").\(tableName ?? "_")."
+    }
+
+    private func scopedKey(columnName: String, connectionId: UUID?, tableName: String?) -> String {
+        "\(connectionId?.uuidString ?? "_").\(tableName ?? "_").\(columnName)"
+    }
+
+    // MARK: - Override Management
+
+    func setOverride(
+        _ format: ValueDisplayFormat?,
+        columnName: String,
+        connectionId: UUID,
+        tableName: String
+    ) {
+        var overrides = ValueDisplayFormatStorage.shared.load(for: tableName, connectionId: connectionId) ?? [:]
+
+        if let format, format != .raw {
+            overrides[columnName] = format
+        } else {
+            overrides.removeValue(forKey: columnName)
+        }
+
+        if overrides.isEmpty {
+            ValueDisplayFormatStorage.shared.clear(for: tableName, connectionId: connectionId)
+        } else {
+            ValueDisplayFormatStorage.shared.save(overrides, for: tableName, connectionId: connectionId)
+        }
+    }
+
+    // MARK: - Private Formatting
+
+    private static func formatAsUuid(_ rawValue: String) -> String {
+        // Try raw binary bytes (isoLatin1 encoding from MySQL)
+        if let data = rawValue.data(using: .isoLatin1), data.count == 16 {
+            let bytes = [UInt8](data)
+            let hex = bytes.map { String(format: "%02x", $0) }.joined()
+            return insertUuidHyphens(hex)
+        }
+
+        // Try hex string (with or without 0x prefix)
+        var hex = rawValue
+        if hex.hasPrefix("0x") || hex.hasPrefix("0X") {
+            hex = String(hex.dropFirst(2))
+        }
+        hex = hex.replacingOccurrences(of: "-", with: "")
+
+        guard (hex as NSString).length == 32, hex.allSatisfy({ $0.isHexDigit }) else {
+            return rawValue
+        }
+
+        return insertUuidHyphens(hex.lowercased())
+    }
+
+    private static func insertUuidHyphens(_ hex: String) -> String {
+        let ns = hex as NSString
+        let p1 = ns.substring(with: NSRange(location: 0, length: 8))
+        let p2 = ns.substring(with: NSRange(location: 8, length: 4))
+        let p3 = ns.substring(with: NSRange(location: 12, length: 4))
+        let p4 = ns.substring(with: NSRange(location: 16, length: 4))
+        let p5 = ns.substring(with: NSRange(location: 20, length: 12))
+        return "\(p1)-\(p2)-\(p3)-\(p4)-\(p5)"
+    }
+
+    private static func formatAsTimestamp(_ rawValue: String, divideBy divisor: Double) -> String {
+        guard let numericValue = Double(rawValue) else { return rawValue }
+        let seconds = numericValue / divisor
+        let date = Date(timeIntervalSince1970: seconds)
+        return DateFormattingService.shared.format(date)
+    }
+}