@an5/adapters 0.2.10 → 0.2.13

package/swift/Sources/An5Adapters/Types.swift

@@ -0,0 +1,127 @@
+import Foundation
+
+/// One row, keyed by column name.
+///
+/// A name-to-value dictionary rather than a positional array because a generated model
+/// reads its fields by name, and because a missing column and a `NULL` column are
+/// different things: the first is absent from the dictionary, the second is present with a
+/// `nil` value.
+public typealias Row = [String: Any?]
+
+/// A filter tree: scalar values, operator maps, and nested `AND`/`OR`/`NOT` groups.
+public typealias Where = [String: Any?]
+
+/// A write payload: column values, plus any relation writes the metadata declares.
+///
+/// Named `Values` rather than `Data` because `Data` is Foundation's byte buffer, and a
+/// typealias that shadows it makes every `Data(bytes:count:)` in a driver fail to compile.
+public typealias Values = [String: Any?]
+
+/// An eager-load description: relation name to `true`, or to a nested description.
+public typealias Include = [String: Any?]
+
+/// A parameter value bound into a statement.
+///
+/// Limited to what a SQL driver can bind. `Date`, `UUID`, `Data` and the numeric types all
+/// have a defined encoding, which is what lets a generated model pass a `UUID` for an
+/// `@id` column without converting it by hand.
+public enum SQLValue {
+    case null
+    case integer(Int64)
+    case real(Double)
+    case text(String)
+    case blob(Data)
+    case bool(Bool)
+    case date(Date)
+    case uuid(UUID)
+
+    /// The value to hand back as an untyped Swift value.
+    ///
+    /// A `NULL` becomes `nil`, and everything else the natural Swift type, so an
+    /// already-encoded value can travel through the untyped `[Any?]` entry points without
+    /// being encoded a second time.
+    public var unwrapped: Any? {
+        switch self {
+        case .null: return nil
+        case .bool(let value): return value
+        case .integer(let value): return value
+        case .real(let value): return value
+        case .text(let value): return value
+        case .blob(let value): return value
+        case .date(let value): return value
+        case .uuid(let value): return value
+        }
+    }
+
+    /// Converts a Swift value into something bindable, or `nil` when there is no encoding.
+    ///
+    /// `Optional` is unwrapped rather than rejected so a generated model can pass a nullable
+    /// column straight through; `NSNull` is accepted as an explicit null because that is
+    /// what a JSON decoder produces for a missing value.
+    public static func encode(_ value: Any?) -> SQLValue? {
+        switch value {
+        case nil, is NSNull:
+            return .null
+        case let already as SQLValue:
+            return already
+        case let bool as Bool:
+            return .bool(bool)
+        case let number as Int:
+            return .integer(Int64(number))
+        case let number as Int64:
+            return .integer(number)
+        case let number as Double:
+            return .real(number)
+        case let number as Float:
+            return .real(Double(number))
+        case let decimal as Decimal:
+            return .real(NSDecimalNumber(decimal: decimal).doubleValue)
+        case let number as NSNumber:
+            // An NSNumber wraps either a floating-point or an integral value, and the only
+            // portable way to tell is whether it survives the round trip through int64 —
+            // CFNumberIsFloatType is not available on every platform Swift builds for.
+            let whole = number.doubleValue
+            return whole == Double(number.int64Value) ? .integer(number.int64Value) : .real(whole)
+        case let text as String:
+            return .text(text)
+        case let data as Data:
+            return .blob(data)
+        case let date as Date:
+            return .date(date)
+        case let uuid as UUID:
+            return .uuid(uuid)
+        default:
+            return nil
+        }
+    }
+}
+
+/// Everything the runtime can fail with.
+///
+/// One error type with a reason, rather than a family of types: a caller catching an AN5
+/// failure almost always wants to show the message, and a switch over cases that never
+/// differ in handling is noise.
+public enum An5Error: Error, CustomStringConvertible {
+    case unsupported(String)
+    case configuration(String)
+    case invalidQuery(String)
+    case driver(String)
+    case readOnly(String)
+
+    public var description: String {
+        switch self {
+        case .unsupported(let detail):
+            return "Unsupported: \(detail)"
+        case .configuration(let detail):
+            return "Configuration error: \(detail)"
+        case .invalidQuery(let detail):
+            return "Invalid query: \(detail)"
+        case .driver(let detail):
+            return "Database error: \(detail)"
+        case .readOnly(let detail):
+            return "\(detail) is read-only"
+        }
+    }
+
+    public var localizedDescription: String { description }
+}

package/swift/Sources/An5Adapters/Vectors.swift

@@ -0,0 +1,86 @@
+import Foundation
+
+/// The distance metrics a vector search understands, and the math behind them.
+///
+/// Each metric is turned into a distance before sorting, so ascending order always means
+/// "closer": cosine similarity and dot product would otherwise have to be sorted descending,
+/// which is the kind of detail no caller should have to remember.
+public enum DistanceMetric: String, Sendable {
+    case cosine
+    case euclidean
+    case dot
+
+    public static func distance(_ metric: DistanceMetric, _ left: [Double], _ right: [Double]) -> Double {
+        switch metric {
+        case .cosine: return 1 - Vectors.cosineSimilarity(left, right)
+        case .euclidean: return Vectors.euclideanDistance(left, right)
+        case .dot: return -Vectors.dotProduct(left, right)
+        }
+    }
+}
+
+public enum Vectors {
+
+    /// Cosine similarity in `-1...1`; `0` when the lengths differ or either side is empty.
+    public static func cosineSimilarity(_ left: [Double], _ right: [Double]) -> Double {
+        guard left.count == right.count, !left.isEmpty else { return 0 }
+        var dot = 0.0
+        var leftMagnitude = 0.0
+        var rightMagnitude = 0.0
+        for index in left.indices {
+            dot += left[index] * right[index]
+            leftMagnitude += left[index] * left[index]
+            rightMagnitude += right[index] * right[index]
+        }
+        guard leftMagnitude != 0, rightMagnitude != 0 else { return 0 }
+        return dot / (leftMagnitude.squareRoot() * rightMagnitude.squareRoot())
+    }
+
+    /// L2 distance; `0` when the lengths differ or either side is empty.
+    public static func euclideanDistance(_ left: [Double], _ right: [Double]) -> Double {
+        guard left.count == right.count, !left.isEmpty else { return 0 }
+        var sum = 0.0
+        for index in left.indices {
+            let difference = left[index] - right[index]
+            sum += difference * difference
+        }
+        return sum.squareRoot()
+    }
+
+    /// Inner product; `0` when the lengths differ.
+    public static func dotProduct(_ left: [Double], _ right: [Double]) -> Double {
+        guard left.count == right.count else { return 0 }
+        return zip(left, right).reduce(0) { $0 + $1.0 * $1.1 }
+    }
+
+    /// Reads a stored vector back out of a cell.
+    ///
+    /// All three vector stores AN5 targets hand the column back as text — SQL Server's
+    /// `VECTOR`, PostgreSQL's `vector`, and SQLite's JSON blob — so the in-memory fallback
+    /// parses the same `[0.1, 0.2]` form. A row whose length does not match the query vector
+    /// yields `nil` rather than a silently wrong score.
+    ///
+    /// - Parameter expectedLength: the query vector's length, or `0` to accept any length.
+    public static func parse(_ value: Any?, expectedLength: Int) -> [Double]? {
+        guard let value, !(value is NSNull) else { return nil }
+        if let numbers = value as? [Double] {
+            return expectedLength > 0 && numbers.count != expectedLength ? nil : numbers
+        }
+        let text = "\(value)".trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let open = text.firstIndex(of: "["), let close = text.lastIndex(of: "]"), close > open else {
+            return nil
+        }
+        let body = text[text.index(after: open)..<close]
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if body.isEmpty { return nil }
+        let parsed = body.split(separator: ",").compactMap { Double($0.trimmingCharacters(in: .whitespaces)) }
+        guard parsed.count == body.split(separator: ",").count else { return nil }
+        guard !parsed.isEmpty, expectedLength == 0 || parsed.count == expectedLength else { return nil }
+        return parsed
+    }
+
+    /// Renders a vector the way the vector stores expect it, as `[0.1, 0.2]`.
+    public static func format(_ vector: [Double]) -> String {
+        "[" + vector.map { "\($0)" }.joined(separator: ", ") + "]"
+    }
+}

package/swift/Sources/An5Adapters/ViewClient.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+/// A read-only client for a database view.
+///
+/// Reads go straight to the underlying table client, which already knows how to select from
+/// an arbitrary name. Every mutation is refused rather than attempted: a view has no rows to
+/// write, and the databases disagree about whether the statement is even legal, so the error
+/// is raised here where it can name the reason.
+public struct ViewClient {
+
+    public let adapter: An5Adapter
+    public let view: String
+
+    private var client: TableClient { adapter.table(view) }
+
+    public init(adapter: An5Adapter, view: String) {
+        self.adapter = adapter
+        self.view = view
+    }
+
+    public func findMany() throws -> [Row] { try client.findMany() }
+    public func findMany(_ query: Query) throws -> [Row] { try client.findMany(query) }
+    public func findMany(filter: Where) throws -> [Row] { try client.findMany(filter: filter) }
+    public func findFirst(filter: Where) throws -> Row? { try client.findFirst(filter: filter) }
+    public func findUnique(filter: Where) throws -> Row? { try client.findUnique(filter: filter) }
+    public func count(_ filter: Where? = nil) throws -> Int { try client.count(filter) }
+    public func aggregate(_ aggregate: Aggregate) throws -> Row { try client.aggregate(aggregate) }
+    public func groupBy(_ aggregate: Aggregate) throws -> [Row] { try client.groupBy(aggregate) }
+
+    public func vectorSearch(
+        _ vector: [Double],
+        take: Int = 10,
+        filter: Where? = nil,
+        vectorField: String = "embedding",
+        metric: DistanceMetric = .cosine
+    ) throws -> [Row] {
+        try client.vectorSearch(vector, take: take, filter: filter, vectorField: vectorField, metric: metric)
+    }
+
+    public func create(_ data: Values) throws -> Row { throw readOnly("create") }
+    public func update(filter: Where, data: Values) throws -> Row? { throw readOnly("update") }
+    public func updateMany(filter: Where?, data: Values) throws -> Int { throw readOnly("updateMany") }
+    public func delete(filter: Where) throws -> Row? { throw readOnly("delete") }
+    public func deleteMany(filter: Where? = nil) throws -> Int { throw readOnly("deleteMany") }
+    public func upsert(filter: Where, create: Values, update: Values) throws -> Row { throw readOnly("upsert") }
+
+    private func readOnly(_ operation: String) -> An5Error {
+        .readOnly("view '\(view)' — \(operation) is not allowed on it")
+    }
+}

package/swift/Sources/CSQLite/module.modulemap

@@ -0,0 +1,8 @@
+module CSQLite [system] {
+    // The real header, not a hand-written copy of the declarations: a copied subset drifts
+    // from the library it claims to describe, and the compiler then accepts calls with the
+    // wrong signatures.
+    header "shim.h"
+    link "sqlite3"
+    export *
+}

package/swift/Sources/CSQLite/shim.h

@@ -0,0 +1,9 @@
+#ifndef AN5_CSQLITE_SHIM_H
+#define AN5_CSQLITE_SHIM_H
+
+/* The system SQLite's own header. A module map needs one header to anchor the module to;
+   re-declaring the handful of functions AN5 calls here would let the compiler accept a
+   signature the installed library does not have. */
+#include <sqlite3.h>
+
+#endif /* AN5_CSQLITE_SHIM_H */

package/swift/Tests/An5AdaptersTests/QuerySemanticsTests.swift

@@ -0,0 +1,51 @@
+import Foundation
+import XCTest
+@testable import An5Adapters
+
+/// Runs the shared query contract in `test/fixtures/query-semantics.json` through the Swift
+/// SQL builder and a real SQLite database.
+///
+/// The same fixture gates the TypeScript, Python, Go and Java builders, which is the point: a
+/// where tree that means one thing in one client and another in the next is a bug in the
+/// client, and only a shared fixture catches it.
+final class QuerySemanticsTests: XCTestCase {
+
+    private static let fixtureURL = URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()   // An5AdaptersTests
+        .deletingLastPathComponent()   // Tests
+        .deletingLastPathComponent()   // swift
+        .deletingLastPathComponent()   // an5Adapters
+        .appendingPathComponent("test/fixtures/query-semantics.json")
+
+    func testSharedContract() throws {
+        let data = try Data(contentsOf: Self.fixtureURL)
+        let fixture = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        let rows = try XCTUnwrap(fixture["rows"] as? [[String: Any]])
+        let cases = try XCTUnwrap(fixture["cases"] as? [[String: Any]])
+
+        let driver = try SQLiteDriver(path: ":memory:")
+        let adapter = An5Adapter(driver: driver, connectionString: "sqlite::memory:")
+        try adapter.execute(
+            "CREATE TABLE users (id INTEGER, score INTEGER)"
+        )
+        for row in rows {
+            try adapter.execute(
+                "INSERT INTO users VALUES (?, ?)",
+                [row["id"] as Any, row["score"] as Any]
+            )
+        }
+
+        for testCase in cases {
+            let name = testCase["name"] as? String ?? "<unnamed>"
+            let filter = testCase["where"] as? [String: Any?] ?? [:]
+            let expected = (testCase["ids"] as? [Int]) ?? []
+
+            let clause = SQLBuilder.whereClause(filter, dialect: .sqlite)
+            let sql = "SELECT id FROM users" + (clause.isEmpty ? "" : " WHERE \(clause.sql)") + " ORDER BY id"
+            let found = try adapter.query(sql, clause.parameters.map { $0 as Any? })
+            let actual = found.compactMap { ($0["id"] as? NSNumber)?.intValue }
+
+            XCTAssertEqual(actual, expected, name)
+        }
+    }
+}