@an5/adapters 0.2.10 → 0.2.13

package/java/src/test/java/Json.java

@@ -0,0 +1,174 @@
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A minimal JSON reader for the test suite.
+ *
+ * <p>The adapter itself has no JSON dependency — it never parses a document, it only ever
+ * reads and writes vector literals — so pulling one in for production code to satisfy a
+ * test would be the wrong trade. This reads exactly the subset the shared query-semantics
+ * fixture uses: objects, arrays, strings, numbers, booleans and null.
+ */
+final class Json {
+
+  private final String source;
+  private int position;
+
+  private Json(String source) {
+    this.source = source;
+  }
+
+  static Object parse(String text) {
+    Json parser = new Json(text);
+    parser.skipWhitespace();
+    Object value = parser.readValue();
+    parser.skipWhitespace();
+    return value;
+  }
+
+  @SuppressWarnings("unchecked")
+  static Map<String, Object> asObject(Object value) {
+    return value instanceof Map ? (Map<String, Object>) value : new LinkedHashMap<String, Object>();
+  }
+
+  @SuppressWarnings("unchecked")
+  static List<Object> asList(Object value) {
+    return value instanceof List ? (List<Object>) value : new ArrayList<Object>();
+  }
+
+  private Object readValue() {
+    skipWhitespace();
+    char ch = peek();
+    switch (ch) {
+      case '{':
+        return readObject();
+      case '[':
+        return readArray();
+      case '"':
+        return readString();
+      case 't':
+        expect("true");
+        return Boolean.TRUE;
+      case 'f':
+        expect("false");
+        return Boolean.FALSE;
+      case 'n':
+        expect("null");
+        return null;
+      default:
+        return readNumber();
+    }
+  }
+
+  private Map<String, Object> readObject() {
+    Map<String, Object> object = new LinkedHashMap<String, Object>();
+    position++;
+    skipWhitespace();
+    if (peek() == '}') {
+      position++;
+      return object;
+    }
+    while (true) {
+      skipWhitespace();
+      String key = readString();
+      skipWhitespace();
+      position++; // ':'
+      object.put(key, readValue());
+      skipWhitespace();
+      char ch = peek();
+      position++;
+      if (ch == '}') {
+        return object;
+      }
+    }
+  }
+
+  private List<Object> readArray() {
+    List<Object> array = new ArrayList<Object>();
+    position++;
+    skipWhitespace();
+    if (peek() == ']') {
+      position++;
+      return array;
+    }
+    while (true) {
+      array.add(readValue());
+      skipWhitespace();
+      char ch = peek();
+      position++;
+      if (ch == ']') {
+        return array;
+      }
+    }
+  }
+
+  private String readString() {
+    StringBuilder out = new StringBuilder();
+    position++;
+    while (true) {
+      char ch = source.charAt(position++);
+      if (ch == '"') {
+        return out.toString();
+      }
+      if (ch != '\\') {
+        out.append(ch);
+        continue;
+      }
+      char escaped = source.charAt(position++);
+      switch (escaped) {
+        case 'n':
+          out.append('\n');
+          break;
+        case 't':
+          out.append('\t');
+          break;
+        case 'r':
+          out.append('\r');
+          break;
+        case 'b':
+          out.append('\b');
+          break;
+        case 'f':
+          out.append('\f');
+          break;
+        case 'u':
+          out.append((char) Integer.parseInt(source.substring(position, position + 4), 16));
+          position += 4;
+          break;
+        default:
+          out.append(escaped);
+      }
+    }
+  }
+
+  private Object readNumber() {
+    int start = position;
+    while (position < source.length() && "+-.eE0123456789".indexOf(source.charAt(position)) >= 0) {
+      position++;
+    }
+    String text = source.substring(start, position);
+    if (text.indexOf('.') < 0 && text.indexOf('e') < 0 && text.indexOf('E') < 0) {
+      return Long.valueOf(text);
+    }
+    return Double.valueOf(text);
+  }
+
+  private void expect(String literal) {
+    if (!source.startsWith(literal, position)) {
+      throw new IllegalArgumentException("expected " + literal + " at offset " + position);
+    }
+    position += literal.length();
+  }
+
+  private char peek() {
+    return position < source.length() ? source.charAt(position) : '\0';
+  }
+
+  private void skipWhitespace() {
+    while (position < source.length() && Character.isWhitespace(source.charAt(position))) {
+      position++;
+    }
+  }
+}

package/java/src/test/java/QuerySemantics.java

@@ -0,0 +1,111 @@
+import an5.adapters.base.Dialect;
+import an5.adapters.base.SqlBuilder;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Runs the shared query contract in {@code test/fixtures/query-semantics.json} through the
+ * Java SQL builder and a real SQLite database.
+ *
+ * <p>The same fixture gates the TypeScript, Python and Go 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.
+ *
+ * <p>Reads the fixture path from {@code args[0]}, or from {@code ../test/fixtures} when run
+ * from the adapter directory.
+ */
+public final class QuerySemantics {
+
+  private QuerySemantics() {}
+
+  public static void main(String[] args) throws Exception {
+    String fixturePath =
+        args.length > 0 ? args[0] : "../test/fixtures/query-semantics.json";
+    Map<String, Object> fixture = Json.asObject(Json.parse(read(fixturePath)));
+
+    List<Object> rows = Json.asList(fixture.get("rows"));
+    int failures = 0;
+    for (Object entry : Json.asList(fixture.get("cases"))) {
+      Map<String, Object> testCase = Json.asObject(entry);
+      String name = String.valueOf(testCase.get("name"));
+      Map<String, Object> where = Json.asObject(testCase.get("where"));
+      List<Object> expected = Json.asList(testCase.get("ids"));
+      try {
+        List<Long> actual = run(rows, where);
+        List<Long> expectedIds = new ArrayList<Long>();
+        for (Object id : expected) {
+          expectedIds.add(((Number) id).longValue());
+        }
+        if (!actual.equals(expectedIds)) {
+          System.out.println("FAIL " + name + ": expected " + expectedIds + ", got " + actual);
+          failures++;
+        } else {
+          System.out.println("ok   " + name);
+        }
+      } catch (Exception error) {
+        System.out.println("FAIL " + name + ": " + error);
+        failures++;
+      }
+    }
+
+    if (failures > 0) {
+      System.out.println("java query contract: " + failures + " case(s) failed");
+      System.exit(1);
+    }
+    System.out.println("java query contract: all cases passed");
+  }
+
+  private static List<Long> run(List<Object> rows, Map<String, Object> where) throws Exception {
+    Connection connection = DriverManager.getConnection("jdbc:sqlite::memory:");
+    try {
+      Statement statement = connection.createStatement();
+      statement.execute("CREATE TABLE users (id INTEGER, score INTEGER)");
+      for (Object entry : rows) {
+        Map<String, Object> row = Json.asObject(entry);
+        statement.execute(
+            "INSERT INTO users VALUES ("
+                + ((Number) row.get("id")).longValue()
+                + ", "
+                + ((Number) row.get("score")).longValue()
+                + ")");
+      }
+
+      Map<String, Object> params = new LinkedHashMap<String, Object>();
+      SqlBuilder.Where clause = SqlBuilder.parseWhere(where, Dialect.SQLITE, params, "");
+      List<Object> values = new ArrayList<Object>(params.values());
+      String sql =
+          "SELECT id FROM users"
+              + (clause.isEmpty() ? "" : " WHERE " + clause.sql)
+              + " ORDER BY id";
+
+      java.sql.PreparedStatement prepared = connection.prepareStatement(sql);
+      for (int i = 0; i < values.size(); i++) {
+        prepared.setObject(i + 1, values.get(i));
+      }
+      ResultSet results = prepared.executeQuery();
+      List<Long> ids = new ArrayList<Long>();
+      while (results.next()) {
+        ids.add(results.getLong(1));
+      }
+      results.close();
+      prepared.close();
+      return ids;
+    } finally {
+      connection.close();
+    }
+  }
+
+  private static String read(String path) throws IOException {
+    return new String(Files.readAllBytes(Paths.get(path)), StandardCharsets.UTF_8);
+  }
+}

package/kotlin/build.gradle.kts

@@ -0,0 +1,145 @@
+plugins {
+    kotlin("jvm") version "2.0.21"
+    `java-library`
+    `maven-publish`
+    signing
+}
+
+// Gradle rather than Maven because Kotlin on Android is built with Gradle, and a runtime a
+// phone app cannot resolve is not a mobile runtime. Maven consumers can still use the
+// published Maven coordinates; this module publishes both.
+group = "io.github.an5orm"
+version = "0.2.13"
+
+repositories {
+    // The Java runtime is a sibling checkout, not a published artifact during development:
+    // `mvn -f java/pom.xml install` puts it in ~/.m2 and this resolves it from there. Every
+    // other dependency still comes from Central, so a consumer without a local install is
+    // unaffected.
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    // The Java adapter is the implementation; this module is the Kotlin surface over it.
+    // One SQL builder and one set of dialect rules, so a where tree cannot mean one thing in
+    // Java and another in Kotlin.
+    api("io.github.an5orm:an5-adapters-java:${version}")
+
+    // `api`, not `implementation`: a row's accessors return stdlib types, so consumers see
+    // them in their own signatures.
+    api(kotlin("stdlib"))
+
+    // Tests run against the same SQLite the other runtimes use, which needs no licence and
+    // runs on every platform the workspace builds on.
+    testImplementation("org.xerial:sqlite-jdbc:3.46.1.3")
+}
+
+java {
+    // Java 8 bytecode: Android desugars Java 8 but not newer language features, so a runtime
+    // compiled to a newer target cannot be used on a device.
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+    // Sources are required by Maven Central; the javadoc jar is empty because the sources are
+    // Kotlin and only a Kotlin-aware generator would fill it.
+    withSourcesJar()
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
+    }
+}
+
+sourceSets {
+    named("main") { kotlin.srcDir("src/main/kotlin") }
+    named("test") { kotlin.srcDir("src/test/kotlin") }
+}
+
+// The runtime's tests are a `main()` program, not JUnit classes, so they need a runner
+// rather than a test framework: `useJUnitPlatform()` with no engine on the classpath makes
+// the launcher refuse to start, and an engine added to make it start would find zero tests
+// and pass without running anything. `smoke` runs the program, and `check` — so `build` —
+// depends on it.
+val smoke = tasks.register<JavaExec>("smoke") {
+    group = "verification"
+    description = "Runs the Kotlin runtime smoke against a real SQLite database."
+    classpath = sourceSets.getByName("test").runtimeClasspath
+    mainClass.set("an5.adapters.An5Smoke")
+}
+
+tasks.named("check") {
+    dependsOn(smoke)
+}
+
+tasks.test {
+    // An5Smoke is executed by `smoke`; there is nothing here for a test framework to find.
+    testLogging {
+        events("passed", "failed", "skipped")
+    }
+}
+
+val javadocJar = tasks.register<Jar>("javadocJar") {
+    archiveClassifier.set("javadoc")
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("maven") {
+            from(components["java"])
+            artifact(javadocJar)
+            pom {
+                name.set("AN5 ORM Kotlin adapter")
+                description.set(
+                    "Kotlin runtime for AN5 ORM: dialect-aware CRUD, relation eager loading " +
+                        "and vector search over the AN5 Java adapter.",
+                )
+                url.set("https://github.com/an5ORM/an5Adapters")
+                licenses {
+                    license {
+                        name.set("MIT License")
+                        url.set("https://opensource.org/licenses/MIT")
+                    }
+                }
+                developers {
+                    developer {
+                        name.set("AN5 ORM")
+                        organization.set("AN5")
+                        url.set("https://github.com/an5ORM")
+                    }
+                }
+                scm {
+                    connection.set("scm:git:https://github.com/an5ORM/an5Adapters.git")
+                    developerConnection.set("scm:git:ssh://git@github.com/an5ORM/an5Adapters.git")
+                    url.set("https://github.com/an5ORM/an5Adapters")
+                }
+            }
+        }
+    }
+    repositories {
+        // The Sonatype Central Portal accepts legacy OSSRH clients on this endpoint, so Gradle
+        // uploads reach the same repository as the Maven side's central-publishing plugin.
+        // Credentials come from the environment; `publishToMavenLocal` never touches them.
+        maven {
+            name = "central"
+            url = uri(
+                System.getenv("MAVEN_CENTRAL_URL")
+                    ?: "https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/",
+            )
+            credentials {
+                username = System.getenv("MAVEN_CENTRAL_USERNAME")
+                password = System.getenv("MAVEN_CENTRAL_TOKEN")
+            }
+        }
+    }
+}
+
+// Signing is conditional: a checkout without a key still runs `publishToMavenLocal` and
+// `build`, and only a release machine supplies MAVEN_GPG_PRIVATE_KEY.
+signing {
+    val signingKey = System.getenv("MAVEN_GPG_PRIVATE_KEY")
+    if (!signingKey.isNullOrBlank()) {
+        useInMemoryPgpKeys(signingKey, System.getenv("MAVEN_GPG_PASSPHRASE"))
+        sign(publishing.publications)
+    }
+}

package/kotlin/settings.gradle.kts

@@ -0,0 +1,10 @@
+// Gradle needs this to treat the runtime as its own build rather than as part of whatever
+// happens to be checked out next to it. Only the name and repositories: the build itself
+// lives in build.gradle.kts.
+rootProject.name = "an5-adapters-kotlin"
+
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+    }
+}

package/kotlin/src/main/kotlin/an5/adapters/Aggregate.kt

@@ -0,0 +1,89 @@
+package an5.adapters
+
+/**
+ * Builds an aggregate or a grouped aggregate.
+ *
+ * One builder covers both because the metrics are the same; [groupedBy] is what turns a
+ * flat `aggregate` into a `groupBy`.
+ *
+ * ```
+ * db.table("Order").aggregate {
+ *     count()
+ *     sum("total")
+ *     where("status" eq "paid")
+ * }
+ *
+ * db.table("Order").groupBy("customerId") {
+ *     sum("total")
+ *     orderBy("_sum_total", Sort.DESC)
+ *     take(5)
+ * }
+ * ```
+ */
+class AggregateBuilder {
+    private var counts = false
+    private val sums = mutableListOf<String>()
+    private val averages = mutableListOf<String>()
+    private val minimums = mutableListOf<String>()
+    private val maximums = mutableListOf<String>()
+    private val clauses = mutableListOf<Where>()
+    private val groups = mutableListOf<String>()
+    private val order = mutableListOf<Map<String, String>>()
+    private var offset = 0
+    private var limit: Int? = null
+
+    /** Adds `COUNT(*)`. */
+    fun count() {
+        counts = true
+    }
+
+    fun sum(vararg columns: String) = apply { sums += columns }
+
+    fun avg(vararg columns: String) = apply { averages += columns }
+
+    fun min(vararg columns: String) = apply { minimums += columns }
+
+    fun max(vararg columns: String) = apply { maximums += columns }
+
+    /** Restricts the rows the aggregate runs over. */
+    fun where(clause: Where) {
+        clauses += clause
+    }
+
+    /** Orders the grouped rows; a flat aggregate returns one row, so it is ignored there. */
+    fun orderBy(column: String, direction: Sort = Sort.ASC) {
+        order += mapOf(column to direction.sql)
+    }
+
+    fun skip(count: Int) {
+        offset = count.coerceAtLeast(0)
+    }
+
+    fun take(count: Int?) {
+        limit = count
+    }
+
+    /** The `GROUP BY` columns. Empty means a flat aggregate rather than a grouped one. */
+    fun groupedBy(vararg columns: String): AggregateBuilder = apply { groups += columns }
+
+    internal fun build(): an5.adapters.An5GroupBy {
+        val aggregate = an5.adapters.An5GroupBy()
+        if (counts) aggregate.count()
+        aggregate.sum(*sums.toTypedArray())
+        aggregate.avg(*averages.toTypedArray())
+        aggregate.min(*minimums.toTypedArray())
+        aggregate.max(*maximums.toTypedArray())
+        if (clauses.isNotEmpty()) {
+            val filter =
+                if (clauses.size == 1) clauses[0] else andOf(*clauses.toTypedArray())
+            aggregate.where(filter.toJavaWhere())
+        }
+        aggregate.by(*groups.toTypedArray())
+        if (order.isNotEmpty()) {
+            aggregate.orderBy(order.toList())
+        }
+        aggregate.skip(offset)
+        aggregate.take(limit)
+        return aggregate
+    }
+}

package/kotlin/src/main/kotlin/an5/adapters/An5.kt

@@ -0,0 +1,91 @@
+package an5.adapters
+
+import java.util.UUID
+
+/**
+ * The AN5 runtime for Kotlin.
+ *
+ * A thin, idiomatic front door over the JVM adapter: the dialect rules, the where builder
+ * and the row mapping all live in one place, so the Kotlin API can stay small enough to
+ * read in a sitting while still behaving exactly like the Java one.
+ *
+ * ```
+ * val db = An5("sqlite:///app.db")
+ * val users = db.table("User")
+ * users.create(mapOf("name" to "Ada", "score" to 10))
+ * val adults = users.findMany { where("age" gte 18); orderBy("name"); take(10) }
+ * ```
+ *
+ * Not thread-safe, exactly like the other AN5 runtimes: a transaction holds one open
+ * connection that every statement in the block has to share.
+ */
+class An5 internal constructor(
+    private val delegate: an5.adapters.An5Adapter,
+) : AutoCloseable {
+
+    /** Opens a runtime for a connection string. */
+    constructor(connectionString: String) : this(an5.adapters.An5Adapter(connectionString))
+
+    /** The dialect the connection string points at. */
+    val dialect: Dialect get() = delegate.dialect()
+
+    /** The table client for a model. */
+    fun table(model: String): TableClient = TableClient(delegate, model)
+
+    /**
+     * Pins one SQLite vector strategy instead of probing for the fastest one available:
+     * `sqlite-vec`, `udf`, `sql` or `memory`.
+     *
+     * SQLite has no vector type, so a `VECTOR(n)` column is ranked by the sqlite-vec
+     * extension, a distance function the driver registers, `json_each` in plain SQL, or
+     * in the client. `null` probes. Plain JDBC reaches `json_each` and the in-memory
+     * path; the first two need a driver built for them.
+     */
+    fun vectorStrategy(strategy: String?) {
+        delegate.setVectorStrategy(strategy ?: "")
+    }
+
+    /** A read-only client for a database view. */
+    fun view(name: String): ViewClient = ViewClient(delegate, name)
+
+    /** Runs a query and returns its rows as ordered maps keyed by column label. */
+    fun queryRaw(sql: String, vararg params: Any?): List<Row> = delegate.queryRaw(sql, *params)
+
+    /** Runs a statement that returns no rows and gives back the affected row count. */
+    fun executeRaw(sql: String, vararg params: Any?): Int = delegate.executeRaw(sql, *params)
+
+    /**
+     * Calls a stored procedure and returns its rows.
+     *
+     * SQLite has none, and says so rather than emitting `EXEC`, which is not valid SQL.
+     */
+    fun queryProc(name: String, params: List<Any?> = emptyList()): List<Row> =
+        delegate.queryProc(name, params)
+
+    /** Calls a stored procedure for its effect. */
+    fun executeProc(name: String, params: List<Any?> = emptyList()): Int =
+        delegate.executeProc(name, params)
+
+    /**
+     * Runs [block] inside a transaction, committing on return and rolling back on failure.
+     *
+     * The [An5] handed to the block shares the transaction's connection, so statements
+     * inside it commit or roll back together. Nesting is rejected rather than flattened:
+     * an inner commit would make the outer rollback a partial save.
+     */
+    fun <T> transaction(block: (An5) -> T): T {
+        val result = arrayOfNulls<Any?>(1)
+        delegate.transaction<Unit> { scoped ->
+            result[0] = block(An5(scoped))
+        }
+        @Suppress("UNCHECKED_CAST")
+        return result[0] as T
+    }
+
+    override fun close() = delegate.close()
+
+    override fun toString(): String = "An5(${delegate.dialect().id()})"
+}
+
+/** A generated identifier, for callers that need the value before the insert. */
+fun newId(): String = UUID.randomUUID().toString()