@swiftbrowser/native 0.0.0-stage → 0.10.0

package/swift/Sources/SwiftBrowserProtocol/JSONValue.swift

@@ -0,0 +1,268 @@
+import Foundation
+
+/// A JSON value, the shape every op, prop and event crosses the bridge in.
+///
+/// Props are kept as JSON on the tree and read through the typed views in
+/// Props.swift and Style.swift, so an element kind or field this package does
+/// not know yet is carried, not dropped: the protocol grows faster than any
+/// renderer (docs/ops-protocol.md).
+public enum JSONValue: Equatable, Hashable, Sendable {
+    case null
+    case bool(Bool)
+    case number(Double)
+    case string(String)
+    case array([JSONValue])
+    case object([String: JSONValue])
+}
+
+public typealias JSONObject = [String: JSONValue]
+
+// MARK: - Reading
+
+extension JSONValue {
+    public var isNull: Bool {
+        if case .null = self { return true }
+        return false
+    }
+
+    public var bool: Bool? {
+        if case .bool(let value) = self { return value }
+        return nil
+    }
+
+    public var double: Double? {
+        if case .number(let value) = self { return value }
+        return nil
+    }
+
+    public var int: Int? {
+        guard case .number(let value) = self, value.isFinite, value == value.rounded() else { return nil }
+        return Int(value)
+    }
+
+    public var string: String? {
+        if case .string(let value) = self { return value }
+        return nil
+    }
+
+    public var array: [JSONValue]? {
+        if case .array(let value) = self { return value }
+        return nil
+    }
+
+    public var object: JSONObject? {
+        if case .object(let value) = self { return value }
+        return nil
+    }
+
+    /// A member of an object (`.null` when absent or not an object).
+    public subscript(key: String) -> JSONValue {
+        if case .object(let members) = self, let value = members[key] { return value }
+        return .null
+    }
+
+    /// An element of an array (`.null` when out of range or not an array).
+    public subscript(index: Int) -> JSONValue {
+        if case .array(let elements) = self, elements.indices.contains(index) { return elements[index] }
+        return .null
+    }
+}
+
+extension Dictionary where Key == String, Value == JSONValue {
+    /// The member as a value with `.null` for a missing key, so chains of
+    /// subscripts read like the TypeScript they mirror.
+    public func value(_ key: String) -> JSONValue { self[key] ?? .null }
+    public func string(_ key: String) -> String? { self[key]?.string }
+    public func double(_ key: String) -> Double? { self[key]?.double }
+    public func int(_ key: String) -> Int? { self[key]?.int }
+    public func bool(_ key: String) -> Bool? { self[key]?.bool }
+    public func array(_ key: String) -> [JSONValue]? { self[key]?.array }
+    public func object(_ key: String) -> JSONObject? { self[key]?.object }
+}
+
+// MARK: - Literals
+
+extension JSONValue: ExpressibleByStringLiteral, ExpressibleByIntegerLiteral, ExpressibleByFloatLiteral,
+    ExpressibleByBooleanLiteral, ExpressibleByNilLiteral, ExpressibleByArrayLiteral, ExpressibleByDictionaryLiteral
+{
+    public init(stringLiteral value: String) { self = .string(value) }
+    public init(integerLiteral value: Int) { self = .number(Double(value)) }
+    public init(floatLiteral value: Double) { self = .number(value) }
+    public init(booleanLiteral value: Bool) { self = .bool(value) }
+    public init(nilLiteral: ()) { self = .null }
+    public init(arrayLiteral elements: JSONValue...) { self = .array(elements) }
+    public init(dictionaryLiteral elements: (String, JSONValue)...) {
+        self = .object(Dictionary(elements, uniquingKeysWith: { _, last in last }))
+    }
+}
+
+// MARK: - Codable
+
+extension JSONValue: Codable {
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        if container.decodeNil() {
+            self = .null
+        } else if let value = try? container.decode(Bool.self) {
+            self = .bool(value)
+        } else if let value = try? container.decode(Double.self) {
+            self = .number(value)
+        } else if let value = try? container.decode(String.self) {
+            self = .string(value)
+        } else if let value = try? container.decode([JSONValue].self) {
+            self = .array(value)
+        } else if let value = try? container.decode(JSONObject.self) {
+            self = .object(value)
+        } else {
+            throw DecodingError.dataCorruptedError(in: container, debugDescription: "not a JSON value")
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch self {
+        case .null: try container.encodeNil()
+        case .bool(let value): try container.encode(value)
+        case .number(let value): try container.encode(value)
+        case .string(let value): try container.encode(value)
+        case .array(let value): try container.encode(value)
+        case .object(let value): try container.encode(value)
+        }
+    }
+}
+
+// MARK: - Parsing and printing
+
+extension JSONValue {
+    /// Parses one JSON document.
+    public static func parse(_ data: Data) throws -> JSONValue {
+        try JSONDecoder().decode(JSONValue.self, from: data)
+    }
+
+    public static func parse(_ text: String) throws -> JSONValue {
+        try parse(Data(text.utf8))
+    }
+
+    /// Parses JSON Lines: one document per non-empty line (headless mode's
+    /// op stream, the snapshots under Examples/*/__snapshots__).
+    public static func parseLines(_ text: String) throws -> [JSONValue] {
+        try text.split(whereSeparator: \.isNewline).compactMap { line in
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+            return trimmed.isEmpty ? nil : try parse(trimmed)
+        }
+    }
+
+    /// The value as compact JSON with object keys sorted, so the same value
+    /// always prints the same bytes (tests compare them; the headless runtime
+    /// prints sorted keys too).
+    public var json: String {
+        var out = ""
+        write(into: &out)
+        return out
+    }
+
+    private func write(into out: inout String) {
+        switch self {
+        case .null:
+            out += "null"
+        case .bool(let value):
+            out += value ? "true" : "false"
+        case .number(let value):
+            out += JSONValue.format(value)
+        case .string(let value):
+            JSONValue.writeString(value, into: &out)
+        case .array(let elements):
+            out += "["
+            for (index, element) in elements.enumerated() {
+                if index > 0 { out += "," }
+                element.write(into: &out)
+            }
+            out += "]"
+        case .object(let members):
+            out += "{"
+            for (index, key) in members.keys.sorted().enumerated() {
+                if index > 0 { out += "," }
+                JSONValue.writeString(key, into: &out)
+                out += ":"
+                members[key]!.write(into: &out)
+            }
+            out += "}"
+        }
+    }
+
+    /// Integral doubles print as integers (`12`, not `12.0`), as JavaScript prints them.
+    static func format(_ value: Double) -> String {
+        guard value.isFinite else { return "null" }
+        if value == value.rounded(), abs(value) < 1e15 { return String(Int64(value)) }
+        return String(value)
+    }
+
+    static func writeString(_ value: String, into out: inout String) {
+        out += "\""
+        for scalar in value.unicodeScalars {
+            switch scalar {
+            case "\"": out += "\\\""
+            case "\\": out += "\\\\"
+            case "\n": out += "\\n"
+            case "\r": out += "\\r"
+            case "\t": out += "\\t"
+            case "\u{08}": out += "\\b"
+            case "\u{0C}": out += "\\f"
+            default:
+                if scalar.value < 0x20 {
+                    out += String(format: "\\u%04x", scalar.value)
+                } else {
+                    out.unicodeScalars.append(scalar)
+                }
+            }
+        }
+        out += "\""
+    }
+}
+
+// MARK: - Bridging to Foundation objects
+
+extension JSONValue {
+    /// From what `JSONSerialization` (and a JavaScript engine's bridging)
+    /// produces: `NSNull`, numbers, strings, arrays and dictionaries.
+    public init(any value: Any?) {
+        switch value {
+        case nil, is NSNull:
+            self = .null
+        case let value as NSNumber:
+            // A Bool bridged to NSNumber keeps the objCType of a char (`c`);
+            // every other number reads as a double.
+            if String(cString: value.objCType) == "c" || String(cString: value.objCType) == "B" {
+                self = .bool(value.boolValue)
+            } else {
+                self = .number(value.doubleValue)
+            }
+        case let value as Bool:
+            self = .bool(value)
+        case let value as Int:
+            self = .number(Double(value))
+        case let value as Double:
+            self = .number(value)
+        case let value as String:
+            self = .string(value)
+        case let value as [Any?]:
+            self = .array(value.map { JSONValue(any: $0) })
+        case let value as [String: Any?]:
+            self = .object(value.mapValues { JSONValue(any: $0) })
+        default:
+            self = .null
+        }
+    }
+
+    /// The value as Foundation objects, for a `JSONSerialization` or an engine bridge.
+    public var anyObject: Any {
+        switch self {
+        case .null: return NSNull()
+        case .bool(let value): return value
+        case .number(let value): return value
+        case .string(let value): return value
+        case .array(let elements): return elements.map(\.anyObject)
+        case .object(let members): return members.mapValues(\.anyObject)
+        }
+    }
+}

package/swift/Sources/SwiftBrowserProtocol/Op.swift

@@ -0,0 +1,100 @@
+import Foundation
+
+/// One render op (docs/ops-protocol.md, "Ops"). The five that shape the tree
+/// are typed; the rest (`defaults`, `request`, `swiftdata`, `imagedata`, and
+/// headless mode's `event` echo) are carried with their fields.
+public enum Op: Equatable, Sendable {
+    /// Create a detached element.
+    case create(id: Int, kind: String, props: JSONObject)
+    /// Replace the element's props entirely.
+    case update(id: Int, props: JSONObject)
+    /// Insert element `id` as child `index` of `parent`, moving it if already attached.
+    case insert(parent: Int, id: Int, index: Int)
+    /// Detach and destroy the element and its subtree.
+    case remove(id: Int)
+    /// End of a render pass; with `animation`, every change of the pass animates.
+    case commit(animation: AnimationSpec?)
+    /// Any other op, by name, with the whole object.
+    case other(name: String, fields: JSONObject)
+
+    /// The op's name as the JSON names it.
+    public var name: String {
+        switch self {
+        case .create: return "create"
+        case .update: return "update"
+        case .insert: return "insert"
+        case .remove: return "remove"
+        case .commit: return "commit"
+        case .other(let name, _): return name
+        }
+    }
+}
+
+public struct OpDecodingError: Error, CustomStringConvertible, Equatable {
+    public let message: String
+    public init(_ message: String) { self.message = message }
+    public var description: String { message }
+}
+
+extension Op {
+    /// Decodes one op from its JSON object.
+    public init(json: JSONValue) throws {
+        guard let fields = json.object else { throw OpDecodingError("an op is a JSON object, got \(json.json)") }
+        guard let name = fields.string("op") else { throw OpDecodingError("an op needs an \"op\" field: \(json.json)") }
+        func id(_ key: String) throws -> Int {
+            guard let value = fields.int(key) else { throw OpDecodingError("\(name) needs an integer \"\(key)\": \(json.json)") }
+            return value
+        }
+        switch name {
+        case "create":
+            guard let kind = fields.string("kind") else { throw OpDecodingError("create needs a \"kind\": \(json.json)") }
+            self = .create(id: try id("id"), kind: kind, props: fields.object("props") ?? [:])
+        case "update":
+            self = .update(id: try id("id"), props: fields.object("props") ?? [:])
+        case "insert":
+            self = .insert(parent: try id("parent"), id: try id("id"), index: try id("index"))
+        case "remove":
+            self = .remove(id: try id("id"))
+        case "commit":
+            self = .commit(animation: fields["animation"].flatMap(AnimationSpec.init(json:)))
+        default:
+            self = .other(name: name, fields: fields)
+        }
+    }
+
+    /// Decodes a JSON array of ops (what a render pass crosses the bridge as).
+    public static func decodeArray(_ data: Data) throws -> [Op] {
+        let value = try JSONValue.parse(data)
+        guard let elements = value.array else { throw OpDecodingError("a batch of ops is a JSON array") }
+        return try elements.map(Op.init(json:))
+    }
+
+    public static func decodeArray(_ text: String) throws -> [Op] {
+        try decodeArray(Data(text.utf8))
+    }
+
+    /// Decodes JSON Lines, one op per line (headless mode, the snapshots).
+    public static func decodeLines(_ text: String) throws -> [Op] {
+        try JSONValue.parseLines(text).map(Op.init(json:))
+    }
+
+    /// The op as JSON (sorted keys), for logs and tests.
+    public var json: JSONValue {
+        switch self {
+        case .create(let id, let kind, let props):
+            return .object(["op": "create", "id": .number(Double(id)), "kind": .string(kind), "props": .object(props)])
+        case .update(let id, let props):
+            return .object(["op": "update", "id": .number(Double(id)), "props": .object(props)])
+        case .insert(let parent, let id, let index):
+            return .object(["op": "insert", "parent": .number(Double(parent)), "id": .number(Double(id)), "index": .number(Double(index))])
+        case .remove(let id):
+            return .object(["op": "remove", "id": .number(Double(id))])
+        case .commit(let animation):
+            var fields: JSONObject = ["op": "commit"]
+            if let animation { fields["animation"] = animation.json }
+            return .object(fields)
+        case .other(_, let fields):
+            return .object(fields)
+        }
+    }
+}