Add JSON objects and arrays to allowed LiveMap values

Public API based on [1] at 6d43429.

[1] ably/ably-js#2052

Author: lawrence-forooghian

Sources/AblyLiveObjects/Internal/InternalDefaultLiveMap.swift

@@ -716,9 +716,13 @@ internal final class InternalDefaultLiveMap: Sendable {
             switch string {
             case let .string(string):
                 return .primitive(.string(string))
-            case .json:
-                // TODO: Understand how to handle JSON values (https://github.com/ably/specification/pull/333/files#r2164561055)
-                notYetImplemented()
+            case let .json(objectOrArray):
+                switch objectOrArray {
+                case let .array(array):
+                    return .primitive(.jsonArray(array))
+                case let .object(object):
+                    return .primitive(.jsonObject(object))
+                }
             }
         }
 

Sources/AblyLiveObjects/Internal/InternalLiveMapValue.swift

@@ -52,6 +52,16 @@ internal enum InternalLiveMapValue: Sendable, Equatable {
         primitiveValue?.dataValue
     }
 
+    /// If this `InternalLiveMapValue` has case `primitive` with a JSON array value, this returns that value. Else, it returns `nil`.
+    internal var jsonArrayValue: [JSONValue]? {
+        primitiveValue?.jsonArrayValue
+    }
+
+    /// If this `InternalLiveMapValue` has case `primitive` with a JSON object value, this returns that value. Else, it returns `nil`.
+    internal var jsonObjectValue: [String: JSONValue]? {
+        primitiveValue?.jsonObjectValue
+    }
+
     // MARK: - Equatable Implementation
 
     public static func == (lhs: InternalLiveMapValue, rhs: InternalLiveMapValue) -> Bool {

Sources/AblyLiveObjects/Public/PublicTypes.swift

@@ -175,7 +175,7 @@ public protocol BatchContextLiveMap: AnyObject, Sendable {
     /// Mirrors the ``LiveMap/get(key:)`` method and returns the value associated with a key in the map.
     ///
     /// - Parameter key: The key to retrieve the value for.
-    /// - Returns: A ``LiveObject``, a primitive type (string, number, boolean, or binary data) or `nil` if the key doesn't exist in a map or the associated ``LiveObject`` has been deleted. Always `nil` if this map object is deleted.
+    /// - Returns: A ``LiveObject``, a primitive type (string, number, boolean, JSON-serializable object or array ,or binary data) or `nil` if the key doesn't exist in a map or the associated ``LiveObject`` has been deleted. Always `nil` if this map object is deleted.
     func get(key: String) -> LiveMapValue?
 
     /// Returns the number of key-value pairs in the map.
@@ -226,14 +226,14 @@ public protocol BatchContextLiveCounter: AnyObject, Sendable {
 /// Conflicts in a LiveMap are automatically resolved with last-write-wins (LWW) semantics,
 /// meaning that if two clients update the same key in the map, the update with the most recent timestamp wins.
 ///
-/// Keys must be strings. Values can be another ``LiveObject``, or a primitive type, such as a string, number, boolean, or binary data (see ``PrimitiveObjectValue``).
+/// Keys must be strings. Values can be another ``LiveObject``, or a primitive type, such as a string, number, boolean, JSON-serializable object or array, or binary data (see ``PrimitiveObjectValue``).
 public protocol LiveMap: LiveObject where Update == LiveMapUpdate {
     /// Returns the value associated with a given key. Returns `nil` if the key doesn't exist in a map or if the associated ``LiveObject`` has been deleted.
     ///
     /// Always returns `nil` if this map object is deleted.
     ///
     /// - Parameter key: The key to retrieve the value for.
-    /// - Returns: A ``LiveObject``, a primitive type (string, number, boolean, or binary data) or `nil` if the key doesn't exist in a map or the associated ``LiveObject`` has been deleted. Always `nil` if this map object is deleted.
+    /// - Returns: A ``LiveObject``, a primitive type (string, number, boolean, JSON-serializable object or array, or binary data) or `nil` if the key doesn't exist in a map or the associated ``LiveObject`` has been deleted. Always `nil` if this map object is deleted.
     func get(key: String) throws(ARTErrorInfo) -> LiveMapValue?
 
     /// Returns the number of key-value pairs in the map.
@@ -291,6 +291,8 @@ public enum PrimitiveObjectValue: Sendable, Equatable {
     case number(Double)
     case bool(Bool)
     case data(Data)
+    case jsonArray([JSONValue])
+    case jsonObject([String: JSONValue])
 
     // MARK: - Convenience getters for associated values
 
@@ -325,6 +327,22 @@ public enum PrimitiveObjectValue: Sendable, Equatable {
         }
         return nil
     }
+
+    /// If this `PrimitiveObjectValue` has case `jsonArray`, this returns the associated value. Else, it returns `nil`.
+    public var jsonArrayValue: [JSONValue]? {
+        if case let .jsonArray(value) = self {
+            return value
+        }
+        return nil
+    }
+
+    /// If this `PrimitiveObjectValue` has case `jsonObject`, this returns the associated value. Else, it returns `nil`.
+    public var jsonObjectValue: [String: JSONValue]? {
+        if case let .jsonObject(value) = self {
+            return value
+        }
+        return nil
+    }
 }
 
 /// The `LiveCounter` class represents a counter that can be incremented or decremented and is synchronized across clients in realtime.

Sources/AblyLiveObjects/Utility/JSONValue.swift

@@ -25,7 +25,7 @@ import Foundation
 ///  ```
 ///
 /// > Note: To write a `JSONValue` that corresponds to the `null` JSON value, you must explicitly write `.null`. `JSONValue` deliberately does not implement the `ExpressibleByNilLiteral` protocol in order to avoid confusion between a value of type `JSONValue?` and a `JSONValue` with case `.null`.
-internal indirect enum JSONValue: Sendable, Equatable {
+public indirect enum JSONValue: Sendable, Equatable {
     case object([String: JSONValue])
     case array([JSONValue])
     case string(String)
@@ -36,7 +36,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     // MARK: - Convenience getters for associated values
 
     /// If this `JSONValue` has case `object`, this returns the associated value. Else, it returns `nil`.
-    internal var objectValue: [String: JSONValue]? {
+    public var objectValue: [String: JSONValue]? {
         if case let .object(objectValue) = self {
             objectValue
         } else {
@@ -45,7 +45,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     }
 
     /// If this `JSONValue` has case `array`, this returns the associated value. Else, it returns `nil`.
-    internal var arrayValue: [JSONValue]? {
+    public var arrayValue: [JSONValue]? {
         if case let .array(arrayValue) = self {
             arrayValue
         } else {
@@ -54,7 +54,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     }
 
     /// If this `JSONValue` has case `string`, this returns the associated value. Else, it returns `nil`.
-    internal var stringValue: String? {
+    public var stringValue: String? {
         if case let .string(stringValue) = self {
             stringValue
         } else {
@@ -63,7 +63,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     }
 
     /// If this `JSONValue` has case `number`, this returns the associated value. Else, it returns `nil`.
-    internal var numberValue: NSNumber? {
+    public var numberValue: NSNumber? {
         if case let .number(numberValue) = self {
             numberValue
         } else {
@@ -72,7 +72,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     }
 
     /// If this `JSONValue` has case `bool`, this returns the associated value. Else, it returns `nil`.
-    internal var boolValue: Bool? {
+    public var boolValue: Bool? {
         if case let .bool(boolValue) = self {
             boolValue
         } else {
@@ -81,7 +81,7 @@ internal indirect enum JSONValue: Sendable, Equatable {
     }
 
     /// Returns true if and only if this `JSONValue` has case `null`.
-    internal var isNull: Bool {
+    public var isNull: Bool {
         if case .null = self {
             true
         } else {
@@ -91,37 +91,37 @@ internal indirect enum JSONValue: Sendable, Equatable {
 }
 
 extension JSONValue: ExpressibleByDictionaryLiteral {
-    internal init(dictionaryLiteral elements: (String, JSONValue)...) {
+    public init(dictionaryLiteral elements: (String, JSONValue)...) {
         self = .object(.init(uniqueKeysWithValues: elements))
     }
 }
 
 extension JSONValue: ExpressibleByArrayLiteral {
-    internal init(arrayLiteral elements: JSONValue...) {
+    public init(arrayLiteral elements: JSONValue...) {
         self = .array(elements)
     }
 }
 
 extension JSONValue: ExpressibleByStringLiteral {
-    internal init(stringLiteral value: String) {
+    public init(stringLiteral value: String) {
         self = .string(value)
     }
 }
 
 extension JSONValue: ExpressibleByIntegerLiteral {
-    internal init(integerLiteral value: Int) {
+    public init(integerLiteral value: Int) {
         self = .number(value as NSNumber)
     }
 }
 
 extension JSONValue: ExpressibleByFloatLiteral {
-    internal init(floatLiteral value: Double) {
+    public init(floatLiteral value: Double) {
         self = .number(value as NSNumber)
     }
 }
 
 extension JSONValue: ExpressibleByBooleanLiteral {
-    internal init(booleanLiteral value: Bool) {
+    public init(booleanLiteral value: Bool) {
         self = .bool(value)
     }
 }

Tests/AblyLiveObjectsTests/InternalDefaultLiveMapTests.swift

@@ -81,7 +81,7 @@ struct InternalDefaultLiveMapTests {
             #expect(result?.numberValue == 123.456)
         }
 
-        // @spec RTLM5d2e
+        // @specOneOf(1/3) RTLM5d2e - When `string` is a string
         @Test
         func returnsStringValue() throws {
             let logger = TestLogger()
@@ -92,6 +92,28 @@ struct InternalDefaultLiveMapTests {
             #expect(result?.stringValue == "test")
         }
 
+        // @specOneOf(2/3) RTLM5d2e - When `string` is a JSON array
+        @Test
+        func returnsJSONArrayValue() throws {
+            let logger = TestLogger()
+            let entry = TestFactories.internalMapEntry(data: ObjectData(string: .json(.array(["foo"]))))
+            let coreSDK = MockCoreSDK(channelState: .attaching)
+            let map = InternalDefaultLiveMap(testsOnly_data: ["key": entry], objectID: "arbitrary", logger: logger, userCallbackQueue: .main, clock: MockSimpleClock())
+            let result = try map.get(key: "key", coreSDK: coreSDK, delegate: MockLiveMapObjectPoolDelegate())
+            #expect(result?.jsonArrayValue == ["foo"])
+        }
+
+        // @specOneOf(3/3) RTLM5d2e - When `string` is a JSON object
+        @Test
+        func returnsJSONObjectValue() throws {
+            let logger = TestLogger()
+            let entry = TestFactories.internalMapEntry(data: ObjectData(string: .json(.object(["foo": "bar"]))))
+            let coreSDK = MockCoreSDK(channelState: .attaching)
+            let map = InternalDefaultLiveMap(testsOnly_data: ["key": entry], objectID: "arbitrary", logger: logger, userCallbackQueue: .main, clock: MockSimpleClock())
+            let result = try map.get(key: "key", coreSDK: coreSDK, delegate: MockLiveMapObjectPoolDelegate())
+            #expect(result?.jsonObjectValue == ["foo": "bar"])
+        }
+
         // @spec RTLM5d2f1
         @Test
         func returnsNilWhenReferencedObjectDoesNotExist() throws {
@@ -389,6 +411,8 @@ struct InternalDefaultLiveMapTests {
                     "bytes": TestFactories.internalMapEntry(data: ObjectData(bytes: Data([0x01, 0x02, 0x03]))), // RTLM5d2c
                     "number": TestFactories.internalMapEntry(data: ObjectData(number: NSNumber(value: 42))), // RTLM5d2d
                     "string": TestFactories.internalMapEntry(data: ObjectData(string: .string("hello"))), // RTLM5d2e
+                    "jsonArray": TestFactories.internalMapEntry(data: ObjectData(string: .json(.array(["foo"])))), // RTLM5d2e
+                    "jsonObject": TestFactories.internalMapEntry(data: ObjectData(string: .json(.object(["foo": "bar"])))), // RTLM5d2e
                     "mapRef": TestFactories.internalMapEntry(data: ObjectData(objectId: "map:ref@123")), // RTLM5d2f2
                     "counterRef": TestFactories.internalMapEntry(data: ObjectData(objectId: "counter:ref@456")), // RTLM5d2f2
                 ],
@@ -403,23 +427,27 @@ struct InternalDefaultLiveMapTests {
             let keys = try map.keys(coreSDK: coreSDK, delegate: delegate)
             let values = try map.values(coreSDK: coreSDK, delegate: delegate)
 
-            #expect(size == 6)
-            #expect(entries.count == 6)
-            #expect(keys.count == 6)
-            #expect(values.count == 6)
+            #expect(size == 8)
+            #expect(entries.count == 8)
+            #expect(keys.count == 8)
+            #expect(values.count == 8)
 
             // Verify the correct values are returned by `entries`
             let booleanEntry = entries.first { $0.key == "boolean" } // RTLM5d2b
             let bytesEntry = entries.first { $0.key == "bytes" } // RTLM5d2c
             let numberEntry = entries.first { $0.key == "number" } // RTLM5d2d
             let stringEntry = entries.first { $0.key == "string" } // RTLM5d2e
+            let jsonArrayEntry = entries.first { $0.key == "jsonArray" } // RTLM5d2e
+            let jsonObjectEntry = entries.first { $0.key == "jsonObject" } // RTLM5d2e
             let mapRefEntry = entries.first { $0.key == "mapRef" } // RTLM5d2f2
             let counterRefEntry = entries.first { $0.key == "counterRef" } // RTLM5d2f2
 
             #expect(booleanEntry?.value.boolValue == true) // RTLM5d2b
             #expect(bytesEntry?.value.dataValue == Data([0x01, 0x02, 0x03])) // RTLM5d2c
             #expect(numberEntry?.value.numberValue == 42) // RTLM5d2d
             #expect(stringEntry?.value.stringValue == "hello") // RTLM5d2e
+            #expect(jsonArrayEntry?.value.jsonArrayValue == ["foo"]) // RTLM5d2e
+            #expect(jsonObjectEntry?.value.jsonObjectValue == ["foo": "bar"]) // RTLM5d2e
             #expect(mapRefEntry?.value.liveMapValue as AnyObject === referencedMap as AnyObject) // RTLM5d2f2
             #expect(counterRefEntry?.value.liveCounterValue as AnyObject === referencedCounter as AnyObject) // RTLM5d2f2
         }