feat!(pollux): vcdm 2.0 implementation (#220)

Signed-off-by: goncalo-frade-iohk <[email protected]>

Author: goncalo-frade-iohk

.github/workflows/build.yml

@@ -19,15 +19,15 @@ env:
 jobs:
   lint:
     name: build
-    runs-on: macos-15
+    runs-on: macos-26-xlarge
 
     steps:
       - name: Checkout Code
         uses: actions/checkout@v3
 
       - uses: maxim-lobanov/setup-xcode@v1
         with:
-          xcode-version: '16.2'
+          xcode-version: '26.0.0'
 
 #      - name: Install lcov
 #        run: brew install [email protected] && brew link --overwrite --force [email protected]

Core/Sources/Helpers/AnyCodable.swift

@@ -7,7 +7,7 @@ public struct AnyCodable {
         self.value = value
     }
 
-    init(_ value: Any) {
+    public init(value: Any) {
         self.value = value
     }
 
@@ -25,7 +25,7 @@ extension AnyCodable: Codable {
         let container = try decoder.singleValueContainer()
 
         if container.decodeNil() {
-            self.init(())
+            self.init(value:())
         } else if let bool = try? container.decode(Bool.self) {
             self.init(bool)
         } else if let int = try? container.decode(Int.self) {
@@ -37,9 +37,9 @@ extension AnyCodable: Codable {
         } else if let string = try? container.decode(String.self) {
             self.init(string)
         } else if let array = try? container.decode([AnyCodable].self) {
-            self.init(array.map { $0.value })
+            self.init(value: array.map { $0.value })
         } else if let dictionary = try? container.decode([String: AnyCodable].self) {
-            self.init(dictionary.mapValues { $0.value })
+            self.init(value: dictionary.mapValues { $0.value })
         } else {
             throw DecodingError.dataCorruptedError(
                 in: container,
@@ -52,6 +52,8 @@ extension AnyCodable: Codable {
         var container = encoder.singleValueContainer()
 
         switch self.value {
+        case is NSNull:
+            try container.encodeNil()
         case is Void:
             try container.encodeNil()
         case let bool as Bool:
@@ -87,9 +89,9 @@ extension AnyCodable: Codable {
         case let url as URL:
             try container.encode(url)
         case let array as [Any]:
-            try container.encode(array.map { AnyCodable($0) })
+            try container.encode(array.map { AnyCodable(value: $0) })
         case let dictionary as [String: Any]:
-            try container.encode(dictionary.mapValues { AnyCodable($0) })
+            try container.encode(dictionary.mapValues { AnyCodable(value: $0) })
         default:
             let context = EncodingError.Context(
                 codingPath: container.codingPath,
@@ -170,34 +172,34 @@ extension AnyCodable: CustomDebugStringConvertible {
 extension AnyCodable: ExpressibleByNilLiteral, ExpressibleByBooleanLiteral, ExpressibleByIntegerLiteral, ExpressibleByFloatLiteral, ExpressibleByStringLiteral, ExpressibleByArrayLiteral, ExpressibleByDictionaryLiteral {
 
     public init(nilLiteral: ()) {
-        self.init(nil ?? ())
+        self.init(value: nil ?? ())
     }
 
     public init(booleanLiteral value: Bool) {
-        self.init(value)
+        self.init(value: value)
     }
 
     public init(integerLiteral value: Int) {
-        self.init(value)
+        self.init(value: value)
     }
 
     public init(floatLiteral value: Double) {
-        self.init(value)
+        self.init(value: value)
     }
 
     public init(extendedGraphemeClusterLiteral value: String) {
-        self.init(value)
+        self.init(value: value)
     }
 
     public init(stringLiteral value: String) {
-        self.init(value)
+        self.init(value: value)
     }
 
     public init(arrayLiteral elements: Any...) {
-        self.init(elements)
+        self.init(value: elements)
     }
 
     public init(dictionaryLiteral elements: (AnyHashable, Any)...) {
-        self.init(Dictionary<AnyHashable, Any>(elements, uniquingKeysWith: { (first, _) in first }))
+        self.init(value: Dictionary<AnyHashable, Any>(elements, uniquingKeysWith: { (first, _) in first }))
     }
 }

Core/Sources/Helpers/Data+tryString.swift

@@ -1,10 +1,17 @@
-import Domain
 import Foundation
 
+public struct InvalidCoding: Error {
+    let localizedDescription: String
+
+    public init(message: String) {
+        self.localizedDescription = message
+    }
+}
+
 public extension Data {
     func toString(using: String.Encoding = .utf8) throws -> String {
         guard let str = String(data: self, encoding: using) else {
-            throw CommonError.invalidCoding(message: "Could not get String from Data value")
+            throw InvalidCoding(message: "Could not get String from Data value")
         }
         return str
     }

Core/Sources/Helpers/JSONDecoder+Helper.swift

@@ -20,4 +20,10 @@ public extension JSONDecoder {
         })
         return decoder
     }
+
+    static var normalized: JSONDecoder {
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        return decoder
+    }
 }

Core/Sources/Helpers/JSONEncoder+Helper.swift

@@ -20,4 +20,11 @@ public extension JSONEncoder {
         encoder.outputFormatting = [.withoutEscapingSlashes, .sortedKeys]
         return encoder
     }
+
+    static var normalized: JSONEncoder {
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        encoder.outputFormatting = [.withoutEscapingSlashes, .sortedKeys]
+        return encoder
+    }
 }

Core/Sources/Helpers/OneOrMany.swift

@@ -0,0 +1,151 @@
+/// A utility enum that models values which may appear as either a single item or an array of items,
+/// commonly seen in JSON APIs that are not schema-consistent.
+/// 
+/// `OneOrMany` normalizes access to such values while preserving the original shape when re-encoding.
+/// Use the `array` property to always work with `[T]`, regardless of whether the source was a single
+/// value or an array.
+///
+/// - Generic Parameter:
+///   - T: The element type. Must conform to `RawCodable`.
+///
+/// - Conforms To:
+///   - `RawCodable` (and, by extension, `Codable` if `RawCodable` refines it)
+///
+/// - Decoding Behavior:
+///   - Attempts to decode an array `[T]` first. If that fails, falls back to decoding a single `T`.
+///   - This means that if both `[T]` and `T` could plausibly decode from the same payload, the array
+///     form wins.
+///   - `null` is not accepted; use `OneOrMany<T>?` if the field can be `null` or omitted.
+///
+/// - Encoding Behavior:
+///   - Preserves shape: `.one` encodes as a single `T`; `.many` encodes as `[T]`.
+///
+/// - Normalization:
+///   - Use `array` to always obtain `[T]` for iteration and higher-level logic.
+///
+/// - Bridging:
+///   - The `raw` property exposes an `AnyCodable` representation of the wrapped value(s), satisfying
+///     `RawCodable` requirements.
+///
+/// - Use Cases:
+///   - Fields like `"tag": "swift"` vs `"tag": ["swift", "ios"]`
+///
+/// - Examples:
+///   ```swift
+///   struct Response: Codable {
+///       let tags: OneOrMany<Tag>
+///   }
+///
+///   // JSON: { "tags": "swift" }
+///   // -> Response.tags == .one(Tag("swift"))
+///   // -> Response.tags.array == [Tag("swift")]
+///
+///   // JSON: { "tags": ["swift", "ios"] }
+///   // -> Response.tags == .many([Tag("swift"), Tag("ios")])
+///   // -> Response.tags.array == [Tag("swift"), Tag("ios")]
+///
+///   // Encoding preserves shape:
+///   // OneOrMany.one(Tag("swift"))  -> "swift"
+///   // OneOrMany.many([Tag("swift"), Tag("ios")]) -> ["swift", "ios"]
+///   ```
+///
+/// - See Also:
+///   - `RawCodable`
+///   - `AnyCodable`
+///
+///
+/// Case: `.one`
+/// Wraps a single value of type `T`.
+///
+///
+/// Case: `.many`
+/// Wraps multiple values as an array `[T]`.
+///
+///
+/// Property: `array`
+/// A normalized view of the contents as `[T]`.
+/// - If the receiver is `.one(v)`, returns `[v]`.
+/// - If the receiver is `.many(vs)`, returns `vs` unchanged.
+///
+///
+/// Property: `raw`
+/// The `RawCodable` raw representation as `AnyCodable`, mirroring the underlying shape:
+/// - For `.one(v)`, returns `AnyCodable(v)`.
+/// - For `.many(vs)`, returns `AnyCodable(vs)`.
+///
+///
+/// Initializer: `init(from:)`
+/// Decodes the value from a single-value container, preferring arrays.
+/// - Parameters:
+///   - decoder: The decoder to read data from.
+/// - Throws: An error if neither `[T]` nor `T` can be decoded from the payload.
+///
+///
+/// Method: `encode(to:)`
+/// Encodes the value into a single-value container, preserving shape.
+/// - Parameters:
+///   - encoder: The encoder to write data to.
+/// - Throws: An error if encoding fails.
+public enum OneOrMany<T: RawCodable>: RawCodable {
+    case one(T)
+    case many([T])
+
+    /// A normalized view of the wrapped value(s) as an array.
+    /// 
+    /// This property allows you to work with the contents uniformly as `[T]`,
+    /// regardless of whether the underlying representation is a single value
+    /// (`.one`) or an array (`.many`).
+    ///
+    /// Behavior:
+    /// - If the receiver is `.one(value)`, returns `[value]`.
+    /// - If the receiver is `.many(values)`, returns `values` unchanged.
+    ///
+    /// Notes:
+    /// - Order and duplicates are preserved.
+    /// - This is a computed convenience; accessing it does not mutate the enum.
+    /// - If you need to preserve the original shape for re-encoding, use the enum
+    ///   cases directly; `array` is only for normalized access.
+    ///
+    /// Example:
+    /// ```swift
+    /// switch tags.array {
+    /// case []:
+    ///     // no tags
+    /// default:
+    ///     // iterate uniformly over tags
+    ///     for tag in tags.array { /* ... */ }
+    /// }
+    /// ```
+    public var array: [T] {
+        switch self {
+        case .one(let v): return [v]
+        case .many(let v): return v
+        }
+    }
+
+    public var raw: AnyCodable? {
+        switch self {
+        case .one(let v): return .init(v)
+        case .many(let v): return .init(v)
+        }
+    }
+
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.singleValueContainer()
+
+        if let many = try? c.decode([T].self) {
+            self = .many(many)
+            return
+        }
+
+        self = .one(try c.decode(T.self))
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var c = encoder.singleValueContainer()
+        switch self {
+        case .one(let v): try c.encode(v)
+        case .many(let v): try c.encode(v)
+        }
+    }
+}

Core/Sources/Helpers/Optional+Helpers.swift

@@ -0,0 +1,6 @@
+public extension Optional {
+    func orThrow(_ error: Error) throws -> Wrapped {
+        if let value = self { return value }
+        throw error
+    }
+}