@an5/adapters 0.2.10 → 0.2.13

package/swift/Sources/An5Adapters/Metadata.swift

@@ -0,0 +1,183 @@
+import Foundation
+
+/// One column of a model, as emitted by the generator into the metadata.
+public struct FieldMeta: Equatable, Sendable {
+    public let name: String
+    public let type: String
+    public let sqlType: String?
+    public let isOptional: Bool
+    public let hasDefault: Bool
+    public let isId: Bool
+    public let description: String?
+
+    public init(
+        name: String,
+        type: String,
+        sqlType: String? = nil,
+        isOptional: Bool = false,
+        hasDefault: Bool = false,
+        isId: Bool = false,
+        description: String? = nil
+    ) {
+        self.name = name
+        self.type = type
+        self.sqlType = sqlType
+        self.isOptional = isOptional
+        self.hasDefault = hasDefault
+        self.isId = isId
+        self.description = description
+    }
+}
+
+extension FieldMeta {
+
+/// Decodes one field entry out of the metadata the generated client passes in.
+public init?(field: [String: Any?]) {
+    guard let name = field["name"] as? String else { return nil }
+    self.init(
+        name: name,
+        type: field["type"] as? String ?? "string",
+        sqlType: (field["sql"] as? String) ?? (field["sqlType"] as? String),
+        isOptional: (field["isOptional"] as? Bool) ?? (field["optional"] as? Bool) ?? false,
+        hasDefault: (field["hasDefault"] as? Bool) ?? (field["default"] as? Bool) ?? false,
+        isId: (field["isId"] as? Bool) ?? (field["id"] as? Bool) ?? false,
+        description: field["description"] as? String
+    )
+}
+
+}
+
+/// One relation of a model.
+///
+/// `relationType` is `"one"` or `"many"`. The two sides of the join are named the way the
+/// foreign key is stored: `foreignKey` is the column on the related model that points back,
+/// `localKey` the column on this model it points to.
+public struct RelationDef: Equatable, Sendable {
+    public let modelName: String
+    public let relationType: String
+    public let foreignKey: String
+    public let localKey: String
+
+    public var isMany: Bool { relationType == "many" }
+
+    public init(modelName: String, relationType: String, foreignKey: String, localKey: String) {
+        self.modelName = modelName
+        self.relationType = relationType.isEmpty ? "many" : relationType
+        self.foreignKey = foreignKey
+        self.localKey = localKey
+    }
+}
+
+extension RelationDef {
+
+public init?(relation: [String: Any?]) {
+    guard let modelName = (relation["modelName"] as? String)
+            ?? (relation["model_name"] as? String)
+            ?? (relation["model"] as? String) else { return nil }
+    self.init(
+        modelName: modelName,
+        relationType: (relation["relationType"] as? String)
+            ?? (relation["relation_type"] as? String)
+            ?? (relation["type"] as? String)
+            ?? "many",
+        foreignKey: (relation["foreignKey"] as? String) ?? (relation["foreign_key"] as? String) ?? "",
+        localKey: (relation["localKey"] as? String) ?? (relation["local_key"] as? String) ?? ""
+    )
+}
+
+}
+
+/// The generated models' table names, columns and relations.
+///
+/// A value type rather than a process-wide singleton: a Swift app may hold more than one
+/// database — a local on-device SQLite and a synced server one — and a global registry would
+/// make the second one's table names overwrite the first's.
+public struct Metadata: Sendable {
+
+    public let modelToTable: [String: String]
+    public let modelFields: [String: [FieldMeta]]
+    public let relationMap: [String: [String: RelationDef]]
+
+    public static let empty = Metadata(modelToTable: [:], modelFields: [:], relationMap: [:])
+
+    public init(
+        modelToTable: [String: String],
+        modelFields: [String: [FieldMeta]],
+        relationMap: [String: [String: RelationDef]]
+    ) {
+        self.modelToTable = modelToTable
+        self.modelFields = modelFields
+        self.relationMap = relationMap
+    }
+
+    /// The metadata the generated client passes in, accepting either spelling of each key.
+    public init?(_ raw: [String: Any?]) {
+        let tables = (raw["model_to_table"] as? [String: Any?]) ?? (raw["modelToTable"] as? [String: Any?])
+        guard let tables else { return nil }
+
+        var parsedTables: [String: String] = [:]
+        for (model, table) in tables {
+            if let text = table as? String { parsedTables[model] = text }
+        }
+
+        var parsedFields: [String: [FieldMeta]] = [:]
+        if let fields = (raw["model_fields"] as? [String: Any?]) ?? (raw["modelFields"] as? [String: Any?]) {
+            for (model, entries) in fields {
+                guard let list = entries as? [Any] else { continue }
+                parsedFields[model] = list.compactMap { entry in
+                    (entry as? [String: Any?]).flatMap { FieldMeta(field: $0) }
+                }
+            }
+        }
+
+        var parsedRelations: [String: [String: RelationDef]] = [:]
+        if let relations = (raw["relation_map"] as? [String: Any?])
+            ?? (raw["relationMap"] as? [String: Any?])
+            ?? (raw["RELATION_MAP"] as? [String: Any?]) {
+            for (model, entries) in relations {
+                guard let list = entries as? [String: Any?] else { continue }
+                var forModel: [String: RelationDef] = [:]
+                for (name, entry) in list {
+                    if let definition = (entry as? [String: Any?]).flatMap({ RelationDef(relation: $0) }) {
+                        forModel[name] = definition
+                    }
+                }
+                parsedRelations[model] = forModel
+            }
+        }
+
+        self.init(modelToTable: parsedTables, modelFields: parsedFields, relationMap: parsedRelations)
+    }
+
+    /// The model's name as the metadata keys it, accepting a different capitalisation.
+    ///
+    /// The generated client registers tables under their PascalCase name while the metadata
+    /// keys them in camelCase. A plain lookup would find no columns at all and silently skip
+    /// `isId` — never generating the primary key.
+    public func modelKey(_ modelName: String) -> String {
+        if modelToTable[modelName] != nil || modelFields[modelName] != nil { return modelName }
+        let camel = modelName.prefix(1).lowercased() + modelName.dropFirst()
+        if modelToTable[camel] != nil || modelFields[camel] != nil { return camel }
+        let lower = modelName.lowercased()
+        if modelToTable[lower] != nil || modelFields[lower] != nil { return lower }
+        return modelName
+    }
+
+    /// The table a model maps to, or the model name when the schema declared none.
+    public func table(_ modelName: String) -> String {
+        modelToTable[modelKey(modelName)] ?? modelName
+    }
+
+    public func fields(_ modelName: String) -> [FieldMeta] {
+        modelFields[modelKey(modelName)] ?? modelFields[modelName] ?? []
+    }
+
+    /// The primary key column, or `nil` when the schema marked none.
+    public func idField(_ modelName: String) -> FieldMeta? {
+        fields(modelName).first { $0.isId }
+    }
+
+    public func relations(_ modelName: String) -> [String: RelationDef] {
+        relationMap[modelName] ?? relationMap[modelKey(modelName)] ?? [:]
+    }
+}

package/swift/Sources/An5Adapters/Query.swift

@@ -0,0 +1,105 @@
+import Foundation
+
+/// A query's filters, ordering, paging, projection and eager loads.
+///
+/// Every field has a default, so `Query()` means the same thing an omitted filter means in
+/// the other adapters: no filter, no order, no limit.
+public struct Query {
+
+    public var filter: Where?
+    public var orderBy: [[String: String]]
+    public var skip: Int
+    public var take: Int?
+    public var select: [String]?
+    public var include: Include?
+
+    public init(
+        filter: Where? = nil,
+        orderBy: [[String: String]] = [],
+        skip: Int = 0,
+        take: Int? = nil,
+        select: [String]? = nil,
+        include: Include? = nil
+    ) {
+        self.filter = filter
+        self.orderBy = orderBy
+        self.skip = max(0, skip)
+        self.take = take
+        self.select = select
+        self.include = include
+    }
+
+    /// The same query with a row cap, leaving the caller's query untouched.
+    ///
+    /// Mutating it instead would silently cap every later use of the value, so a
+    /// `findFirst` would quietly limit a caller's subsequent `findMany`.
+    public func limited(to take: Int?) -> Query {
+        var copy = self
+        copy.take = take
+        return copy
+    }
+
+    // ─── Filter building ────────────────────────────────────────────────────────
+    // Named after the operators they produce rather than Swift's own vocabulary, so a
+    // filter reads the same in Swift as it does in every other AN5 client.
+
+    /// `"age" >= 18`
+    public static func gte(_ column: String, _ value: Any?) -> Where { [column: ["gte": value]] }
+    /// `"age" <= 18`
+    public static func lte(_ column: String, _ value: Any?) -> Where { [column: ["lte": value]] }
+    /// `"age" > 18`
+    public static func gt(_ column: String, _ value: Any?) -> Where { [column: ["gt": value]] }
+    /// `"age" < 18`
+    public static func lt(_ column: String, _ value: Any?) -> Where { [column: ["lt": value]] }
+    /// `"name" == "Ada"`
+    public static func equals(_ column: String, _ value: Any?) -> Where { [column: ["equals": value]] }
+    /// `"name" != "Ada"`
+    public static func not(_ column: String, _ value: Any?) -> Where { [column: ["not": value]] }
+    /// `"name" contains "da"`
+    public static func contains(_ column: String, _ value: String) -> Where { [column: ["contains": value]] }
+    /// `"name" startsWith "Ad"`
+    public static func startsWith(_ column: String, _ value: String) -> Where { [column: ["startsWith": value]] }
+    /// `"name" endsWith "ce"`
+    public static func endsWith(_ column: String, _ value: String) -> Where { [column: ["endsWith": value]] }
+    /// `"id"` is `NULL`.
+    public static func isNull(_ column: String) -> Where { [column: NSNull()] }
+    /// `"id"` is not `NULL`.
+    public static func isNotNull(_ column: String) -> Where { [column: ["not": NSNull()]] }
+    /// `"id"` in `values`; an empty list matches nothing.
+    public static func `in`(_ column: String, _ values: [Any?]) -> Where { [column: ["in": values]] }
+    /// `"id"` not in `values`; an empty list matches everything.
+    public static func notIn(_ column: String, _ values: [Any?]) -> Where { [column: ["notIn": values]] }
+
+    /// Any of `filters`; an empty list matches nothing.
+    public static func or(_ filters: Where...) -> Where { ["OR": filters] }
+    /// All of `filters`; an empty list matches everything.
+    public static func and(_ filters: Where...) -> Where { ["AND": filters] }
+    /// None of `filters`; an empty list matches everything.
+    public static func not(_ filters: Where...) -> Where { ["NOT": filters] }
+}
+
+/// Which aggregates a query computes.
+///
+/// One type covers both a flat aggregate and a grouped one, because the metrics are the
+/// same; `by` is what makes it a group.
+public struct Aggregate {
+    public var count = false
+    public var sum: [String] = []
+    public var average: [String] = []
+    public var minimum: [String] = []
+    public var maximum: [String] = []
+    public var filter: Where?
+    public var by: [String] = []
+    public var orderBy: [[String: String]] = []
+    public var skip = 0
+    public var take: Int?
+
+    public init() {}
+
+    public var isEmpty: Bool { !count && sum.isEmpty && average.isEmpty && minimum.isEmpty && maximum.isEmpty }
+}
+
+public enum SortDirection: String, Sendable {
+    case asc = "ASC"
+    case desc = "DESC"
+}

package/swift/Sources/An5Adapters/Row+Accessors.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+extension Row {
+
+    // Typed reads off a row.
+    //
+    // A cast is not enough: a `BOOL` column arrives as an `Int` from one driver and a `Bool`
+    // from another, a `NUMERIC` that fits in an `Int` still arrives as a `Decimal`, and a
+    // date column arrives as a `String`, a `Double` of epoch seconds, or an `NSDate`. Each
+    // accessor accepts every form, so a generated model never has to know which driver is
+    // underneath it.
+    //
+    // A missing column and a `NULL` column are different things: a lookup yields
+    // `Any??`, and these flatten it so "absent" reads as `nil` rather than as a nested
+    // optional the caller has to unwrap by hand.
+
+    /// The column's value as text, or `nil` for a SQL `NULL`.
+    public func string(_ column: String) -> String? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let text = value as? String { return text }
+        if let data = value as? Data { return String(data: data, encoding: .utf8) }
+        return String(describing: value)
+    }
+
+    public func int(_ column: String) -> Int? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let number = value as? NSNumber { return number.intValue }
+        if let text = value as? String { return Int(text.trimmingCharacters(in: .whitespaces)) }
+        return nil
+    }
+
+    public func int64(_ column: String) -> Int64? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let number = value as? NSNumber { return number.int64Value }
+        if let text = value as? String { return Int64(text.trimmingCharacters(in: .whitespaces)) }
+        return nil
+    }
+
+    public func double(_ column: String) -> Double? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let number = value as? NSNumber { return number.doubleValue }
+        if let text = value as? String { return Double(text.trimmingCharacters(in: .whitespaces)) }
+        return nil
+    }
+
+    /// The column's value as an exact decimal.
+    ///
+    /// Taken from the string form where there is one: a `Double` has already lost the digits
+    /// that do not fit in a binary fraction, so `Decimal(double)` would preserve the loss.
+    public func decimal(_ column: String) -> Decimal? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let decimal = value as? Decimal { return decimal }
+        if let text = value as? String { return Decimal(string: text, locale: Locale(identifier: "en_US_POSIX")) }
+        if let number = value as? NSNumber { return Decimal(string: number.stringValue) }
+        return nil
+    }
+
+    public func bool(_ column: String) -> Bool? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let flag = value as? Bool { return flag }
+        if let number = value as? NSNumber { return number.intValue != 0 }
+        if let text = value as? String {
+            switch text.lowercased() {
+            case "1", "true": return true
+            case "0", "false": return false
+            default: return nil
+            }
+        }
+        return nil
+    }
+
+    /// The column's value as a date, accepting the text forms the engines produce.
+    ///
+    /// Timestamps come back with or without a `T` separator and with an optional offset, and
+    /// a driver with no date type hands back epoch seconds, so all three are read here.
+    public func date(_ column: String) -> Date? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let date = value as? Date { return date }
+        if let number = value as? NSNumber { return Date(timeIntervalSince1970: number.doubleValue) }
+        guard var text = value as? String else { return nil }
+        text = text.trimmingCharacters(in: .whitespaces)
+        guard !text.isEmpty else { return nil }
+        text = text.replacingOccurrences(of: " ", with: "T")
+
+        let withZone = DateFormatter()
+        withZone.locale = Locale(identifier: "en_US_POSIX")
+        withZone.dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSSSSXXXXX"
+        if let date = withZone.date(from: text) { return date }
+        if let date = withZone.date(from: text + "Z") { return date }
+
+        let plain = DateFormatter()
+        plain.locale = Locale(identifier: "en_US_POSIX")
+        plain.dateFormat = "yyyy-MM-dd'T'HH:mm:ss"
+        return plain.date(from: text)
+    }
+
+    /// The column's value as bytes, or `nil` for a text column.
+    public func data(_ column: String) -> Data? {
+        guard let value = self[column] ?? nil else { return nil }
+        if let data = value as? Data { return data }
+        if let text = value as? String { return text.data(using: .utf8) }
+        return nil
+    }
+
+    /// The column's value as a vector, or `nil` for `NULL`.
+    ///
+    /// A `VECTOR(n)` column holds float32 bytes, but a column written before that
+    /// encoding held JSON text, so both are accepted; so is an array a driver has
+    /// already decoded. Decoding is the same code the ranking query uses, which is
+    /// what keeps a column readable as the vector it is stored as.
+    public func vector(_ column: String) -> [Double]? {
+        SqliteVectors.decode(self[column] ?? nil)
+    }
+
+    /// The eager-loaded relation rows under `relation`, or an empty list.
+    public func related(_ relation: String) -> [Row] {
+        (self[relation] ?? nil) as? [Row] ?? []
+    }
+
+    /// The eager-loaded single relation under `relation`, or `nil`.
+    public func relatedOne(_ relation: String) -> Row? {
+        (self[relation] ?? nil) as? Row
+    }
+
+    /// The `_count` total for a relation, or `0`.
+    public func relationCount(_ relation: String) -> Int {
+        ((self["_count"] ?? nil) as? [String: Int])?[relation] ?? 0
+    }
+}