@an5/adapters 0.2.11 → 0.2.13

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

@@ -0,0 +1,130 @@
+package an5.adapters
+
+/**
+ * Builds a query.
+ *
+ * Every field has a default, so [query] with an empty block means the same thing an
+ * omitted filter means in the other adapters: no filter, no order, no limit.
+ *
+ * ```
+ * val adults = db.table("User").findMany {
+ *     where("age" gte 18)
+ *     orderBy("name")
+ *     take(10)
+ * }
+ * ```
+ */
+class QueryBuilder {
+    private val clauses = mutableListOf<Where>()
+    private val order = mutableListOf<Map<String, String>>()
+    private var offset = 0
+    private var limit: Int? = null
+    private var columns: List<String>? = null
+    private val relations = mutableMapOf<String, Any?>()
+
+    /** Restricts the rows. Repeated calls are combined with `AND`. */
+    fun where(clause: Where) {
+        clauses += clause
+    }
+
+    fun orderBy(column: String, direction: Sort = Sort.ASC) {
+        order += mapOf(column to direction.sql)
+    }
+
+    /** Orders by several columns at once, each with its own direction. */
+    fun orderBy(columns: List<Pair<String, Sort>>) {
+        order.addAll(columns.map { (column, direction) -> mapOf(column to direction.sql) })
+    }
+
+    /** Skips this many rows. Negative values are treated as zero. */
+    fun skip(count: Int) {
+        offset = count.coerceAtLeast(0)
+    }
+
+    /** Caps the number of rows; `null` means no limit. */
+    fun take(count: Int?) {
+        limit = count
+    }
+
+    /** Restricts the returned columns; relations and `_count` are eager-loaded instead. */
+    fun select(vararg columns: String) {
+        this.columns = columns.toList()
+    }
+
+    /** Eager-loads relations. Repeated calls merge. */
+    fun include(relations: Include) {
+        this.relations += relations
+    }
+
+    internal fun build(): an5.adapters.An5Query {
+        val query = an5.adapters.An5Query()
+        if (clauses.isNotEmpty()) {
+            query.where(if (clauses.size == 1) clauses[0].toJavaWhere() else andOf(*clauses.toTypedArray()).toJavaWhere())
+        }
+        if (order.isNotEmpty()) {
+            query.orderBy(order.toList())
+        }
+        query.skip(offset)
+        query.take(limit)
+        columns?.let { query.select(*it.toTypedArray()) }
+        if (relations.isNotEmpty()) {
+            query.include(relations.toJavaMap())
+        }
+        return query
+    }
+}
+
+/** Builds a query with [block], ready to hand to a table client. */
+fun query(block: QueryBuilder.() -> Unit): an5.adapters.An5Query = QueryBuilder().apply(block).build()
+
+// ─── Filter building ────────────────────────────────────────────────────────────────
+// Named after the operators they produce rather than Kotlin's own vocabulary, so a filter
+// reads the same in Kotlin as it does in every other AN5 client.
+
+/** `"age" gte 18` — greater than or equal. */
+infix fun String.gte(value: Any?): Where = mapOf(this to mapOf("gte" to value))
+
+/** `"age" lte 18` — less than or equal. */
+infix fun String.lte(value: Any?): Where = mapOf(this to mapOf("lte" to value))
+
+/** `"age" gt 18` — greater than. */
+infix fun String.gt(value: Any?): Where = mapOf(this to mapOf("gt" to value))
+
+/** `"age" lt 18` — less than. */
+infix fun String.lt(value: Any?): Where = mapOf(this to mapOf("lt" to value))
+
+/** `"name" eq "Ada"` — equality. */
+infix fun String.eq(value: Any?): Where = mapOf(this to mapOf("equals" to value))
+
+/** `"name" neq "Ada"` — inequality. */
+infix fun String.neq(value: Any?): Where = mapOf(this to mapOf("not" to value))
+
+/** `"name" contains "da"` — a substring match; case sensitivity follows the dialect. */
+infix fun String.contains(value: String): Where = mapOf(this to mapOf("contains" to value))
+
+/** `"name" startsWith "Ad"`. */
+infix fun String.startsWith(value: String): Where = mapOf(this to mapOf("startsWith" to value))
+
+/** `"name" endsWith "ce"`. */
+infix fun String.endsWith(value: String): Where = mapOf(this to mapOf("endsWith" to value))
+
+/** `"id".isNull()` — the column is `NULL`. */
+fun String.isNull(): Where = mapOf(this to null)
+
+/** `"id".isNotNull()` — the column has a value. */
+fun String.isNotNull(): Where = mapOf(this to mapOf("not" to null))
+
+/** `"id" inList listOf(1, 2)` — an empty list matches nothing. */
+infix fun <T> String.inList(values: List<T>): Where = mapOf(this to mapOf("in" to values))
+
+/** `"id" notInList listOf(1, 2)` — an empty list matches everything. */
+infix fun <T> String.notInList(values: List<T>): Where = mapOf(this to mapOf("notIn" to values))
+
+/** Any of [clauses]; an empty list matches nothing. */
+fun orOf(vararg clauses: Where): Where = mapOf("OR" to clauses.toList())
+
+/** All of [clauses]; an empty list matches everything. */
+fun andOf(vararg clauses: Where): Where = mapOf("AND" to clauses.toList())
+
+/** None of [clauses]; an empty list matches everything. */
+fun notOf(vararg clauses: Where): Where = mapOf("NOT" to clauses.toList())

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

@@ -0,0 +1,166 @@
+package an5.adapters
+
+import java.math.BigDecimal
+import java.sql.Timestamp
+import java.time.Instant
+import java.time.LocalDate
+import java.time.LocalDateTime
+import java.time.OffsetDateTime
+import java.time.ZoneOffset
+import java.util.UUID
+
+/**
+ * Typed reads off a row.
+ *
+ * A column comes back from JDBC as whatever the driver decided: an `INT` may arrive as
+ * `Integer`, `Long` or `BigDecimal` depending on the driver and the declared width, and a
+ * `NUMERIC` column that fits in a `Long` still arrives as `BigDecimal`. These accessors
+ * take any of them, so generated client code never has to cast — and never silently
+ * truncates a decimal on the way.
+ */
+
+/** The column's value as a [String], or `null` when it is `NULL`. */
+fun Row.string(column: String): String? = this[column]?.toString()
+
+/** The column's value as an [Int], or [fallback] when it is `NULL`. */
+fun Row.int(column: String, fallback: Int = 0): Int = number(column)?.toInt() ?: fallback
+
+/** The column's value as a [Long], or [fallback] when it is `NULL`. */
+fun Row.long(column: String, fallback: Long = 0L): Long = number(column)?.toLong() ?: fallback
+
+/** The column's value as a [Double], or [fallback] when it is `NULL`. */
+fun Row.double(column: String, fallback: Double = 0.0): Double = number(column)?.toDouble() ?: fallback
+
+/** The column's value as a [Boolean]; `NULL` reads as [fallback]. */
+fun Row.bool(column: String, fallback: Boolean = false): Boolean =
+    when (val value = this[column]) {
+        null -> fallback
+        is Boolean -> value
+        is Number -> value.toInt() != 0
+        else -> value.toString().toBooleanStrictOrNull() ?: fallback
+    }
+
+/** The column's value as a [ByteArray], or `null` when it is `NULL` or not binary. */
+fun Row.bytes(column: String): ByteArray? = this[column] as? ByteArray
+
+/** The column's value boxed, or [fallback] when it is `NULL`. */
+@Suppress("UNCHECKED_CAST")
+fun <T : Any> Row.valueOr(column: String, fallback: T): T = (this[column] as? T) ?: fallback
+
+/** The column's value, or `null` when it is `NULL`. */
+@Suppress("UNCHECKED_CAST")
+fun <T> Row.value(column: String): T? = this[column] as? T
+
+/** The eager-loaded relation rows under [relation], or an empty list. */
+@Suppress("UNCHECKED_CAST")
+fun Row.related(relation: String): List<Row> = (this[relation] as? List<Row>) ?: emptyList()
+
+/** The eager-loaded single relation under [relation], or `null`. */
+@Suppress("UNCHECKED_CAST")
+fun Row.relatedOne(relation: String): Row? = this[relation] as? Row
+
+/** The `_count` totals for a query that asked for them. */
+fun Row.relationCount(relation: String): Int =
+    ((this["_count"] as? Map<*, *>)?.get(relation) as? Number)?.toInt() ?: 0
+
+/**
+ * Copies the row into a data class.
+ *
+ * ```
+ * data class User(val id: String, val name: String?)
+ * fun Row.toUser() = User(string("id")!!, string("name"))
+ * ```
+ */
+inline fun <T> Row.decode(transform: Row.() -> T): T = transform()
+
+private fun Row.number(column: String): Number? = when (val value = this[column]) {
+    null -> null
+    is Number -> value
+    is Boolean -> if (value) 1 else 0
+    else -> value.toString().trim().toDoubleOrNull()
+}
+// ─── Nullable reads ────────────────────────────────────────────────────────────────
+//
+// The `*OrNull` family, for a generated model whose column is optional: a nullable column
+// that read as `0` or `""` would write the default back on the next update instead of
+// leaving it alone.
+
+/** The column's value as a [String], or `null` when it is `NULL` or missing. */
+fun Row.stringOrNull(column: String): String? = this[column]?.toString()
+
+/** The column's value as an [Int], or `null` when it is `NULL`, missing or not numeric. */
+fun Row.intOrNull(column: String): Int? = asNumber(column)?.toInt()
+
+/** The column's value as a [Long], or `null` when it is `NULL`, missing or not numeric. */
+fun Row.longOrNull(column: String): Long? = asNumber(column)?.toLong()
+
+/** The column's value as a [Double], or `null` when it is `NULL`, missing or not numeric. */
+fun Row.doubleOrNull(column: String): Double? = asNumber(column)?.toDouble()
+
+/**
+ * The column's value as a [BigDecimal], or `null`.
+ *
+ * Goes through the string form rather than the `Double` constructor: a `DECIMAL` column read
+ * as a `Double` would already have lost the digits that do not fit in a binary fraction.
+ */
+fun Row.decimalOrNull(column: String): BigDecimal? = when (val value = this[column]) {
+    null -> null
+    is BigDecimal -> value
+    is java.math.BigInteger -> BigDecimal(value)
+    is Number -> BigDecimal.valueOf(value.toLong())
+    else -> value.toString().trim().toBigDecimalOrNull()
+}
+
+/** The column's value as a [Boolean], or `null` when it is `NULL` or not recognisable. */
+fun Row.boolOrNull(column: String): Boolean? = when (val value = this[column]) {
+    null -> null
+    is Boolean -> value
+    is Number -> value.toInt() != 0
+    else -> value.toString().trim().toBooleanStrictOrNull()
+}
+
+/** The column's value as a [LocalDateTime], or `null`. */
+fun Row.localDateTimeOrNull(column: String): LocalDateTime? = when (val value = this[column]) {
+    null -> null
+    is LocalDateTime -> value
+    is Timestamp -> value.toLocalDateTime()
+    is java.sql.Date -> value.toLocalDate().atStartOfDay()
+    is OffsetDateTime -> value.toLocalDateTime()
+    is Instant -> LocalDateTime.ofInstant(value, ZoneOffset.UTC)
+    is Number -> LocalDateTime.ofInstant(Instant.ofEpochMilli(value.toLong()), ZoneOffset.UTC)
+    else -> runCatching { LocalDateTime.parse(value.toString().trim().replace(' ', 'T')) }.getOrNull()
+}
+
+/** The column's value as a [LocalDate], or `null`. */
+fun Row.localDateOrNull(column: String): LocalDate? = when (val value = this[column]) {
+    null -> null
+    is LocalDate -> value
+    is java.sql.Date -> value.toLocalDate()
+    else -> localDateTimeOrNull(column)?.toLocalDate()
+}
+
+/** The column's value as a [UUID], or `null`. */
+fun Row.uuidOrNull(column: String): UUID? = stringOrNull(column)?.let { text ->
+    runCatching { UUID.fromString(text) }.getOrNull()
+}
+
+/** The column's value as a [ByteArray], or `null`. */
+fun Row.bytesOrNull(column: String): ByteArray? = this[column] as? ByteArray
+
+/**
+ * The column's value as a vector, or `null` 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.
+ */
+fun Row.vectorOrNull(column: String): DoubleArray? =
+    an5.adapters.base.SqliteVectors.decodeVector(this[column], 0)
+
+private fun Row.asNumber(column: String): Number? = when (val value = this[column]) {
+    null -> null
+    is Number -> value
+    is Boolean -> if (value) 1 else 0
+    else -> value.toString().trim().toDoubleOrNull()
+}

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

@@ -0,0 +1,169 @@
+package an5.adapters
+
+/**
+ * CRUD and queries for one table.
+ *
+ * A wrapper over the JVM table client: the schema knowledge and the SQL live there, and
+ * this adds the Kotlin call shapes — a [query] block for filters, named arguments for
+ * writes — without reimplementing anything.
+ */
+class TableClient internal constructor(
+    adapter: an5.adapters.An5Adapter,
+    model: String,
+) {
+    private val delegate: an5.adapters.An5TableClient = adapter.table(model)
+
+    /** The model this client reads and writes. */
+    val model: String get() = delegate.modelName()
+
+    // ─── Reads ────────────────────────────────────────────────────────────────────
+
+    /** Every row, unfiltered. */
+    fun findMany(): List<Row> = delegate.findMany()
+
+    /** The rows matching the query the block builds. */
+    fun findMany(block: QueryBuilder.() -> Unit): List<Row> = delegate.findMany(query(block))
+
+    /** The rows matching [where], with the optional refinements [block] adds. */
+    fun findMany(where: Where, block: QueryBuilder.() -> Unit = {}): List<Row> =
+        delegate.findMany(QueryBuilder().apply { this.where(where); block() }.build())
+
+    /** The first matching row, or `null`. Always limited to one row server-side. */
+    fun findFirst(block: QueryBuilder.() -> Unit): Row? =
+        delegate.findFirst(QueryBuilder().apply(block).build())
+
+    fun findFirst(where: Where): Row? = delegate.findFirst(where.toJavaFilter())
+
+    /** The row [where] identifies, or `null`. */
+    fun findUnique(where: Where): Row? = delegate.findUnique(where.toJavaFilter())
+
+    /** How many rows match. */
+    fun count(where: Where? = null): Long = delegate.count(where?.toJavaWhere())
+
+    // ─── Writes ───────────────────────────────────────────────────────────────────
+
+    /**
+     * Inserts a row and returns it, re-read so server-side defaults come back with it.
+     *
+     * A model with an `@id` column and no value for it gets a generated identifier, which
+     * is what makes a client-created row addressable without a database-side default.
+     */
+    fun create(data: Data): Row = delegate.create(data.toJavaData())
+
+    fun create(data: Data, block: QueryBuilder.() -> Unit): Row =
+        delegate.create(data.toJavaData(), QueryBuilder().apply(block).build())
+
+    /**
+     * Inserts many rows, one statement each.
+     *
+     * Row-at-a-time on purpose: a batch would share one parameter list, so a single bad
+     * row would lose every good row with it.
+     */
+    fun createMany(rows: List<Data>, skipDuplicates: Boolean = false): Int =
+        affected(delegate.createMany(rows.map { it.toJavaData() }, skipDuplicates))
+
+    /** Updates the rows matching [where] and returns the first of them re-read. */
+    fun update(where: Where, data: Data): Row? = delegate.update(where.toJavaFilter(), data.toJavaData())
+
+    /** Updates every matching row and gives back how many changed. */
+    fun updateMany(where: Where?, data: Data): Int =
+        affected(delegate.updateMany(where?.toJavaWhere(), data.toJavaData()))
+
+    /** Deletes the matching rows and returns the one that was there first. */
+    fun delete(where: Where): Row? = delegate.delete(where.toJavaFilter())
+
+    /** Deletes every matching row, or the whole table when [where] is `null`. */
+    fun deleteMany(where: Where? = null): Int = affected(delegate.deleteMany(where?.toJavaWhere()))
+
+    /** Updates the matching row when it exists, creates it otherwise. */
+    fun upsert(where: Where, create: Data, update: Data): Row =
+        delegate.upsert(where.toJavaFilter(), create.toJavaData(), update.toJavaData())
+
+    // ─── Aggregation ──────────────────────────────────────────────────────────────
+
+    /**
+     * One row of aggregate values, keyed `_count`, `_sum_<field>` and so on.
+     *
+     * ```
+     * db.table("Order").aggregate { count(); sum("total"); avg("total") }
+     * ```
+     */
+    fun aggregate(block: AggregateBuilder.() -> Unit): Row =
+        delegate.aggregate(AggregateBuilder().apply(block).build())
+
+    /** One row per group, each carrying the group's `_count` and aggregates. */
+    fun groupBy(vararg by: String, block: AggregateBuilder.() -> Unit = {}): List<Row> =
+        delegate.groupBy(AggregateBuilder().apply(block).groupedBy(*by).build())
+
+    // ─── Vector search ────────────────────────────────────────────────────────────
+
+    /**
+     * The rows nearest [vector], by the database's own vector functions where it has
+     * them and in memory where it does not.
+     */
+    @JvmOverloads
+    fun vectorSearch(
+        vector: DoubleArray,
+        take: Int = 10,
+        where: Where? = null,
+        vectorField: String = "embedding",
+        metric: DistanceMetric = DistanceMetric.COSINE,
+    ): List<Row> = delegate.vectorSearch(vector, take, where?.toJavaWhere(), vectorField, metric.sql)
+
+    override fun toString(): String = "TableClient($model)"
+}
+
+/** A wrapper over the JVM view client: reads work, writes are refused. */
+class ViewClient internal constructor(
+    adapter: an5.adapters.An5Adapter,
+    viewName: String,
+) {
+    private val delegate: an5.adapters.An5ViewClient = adapter.view(viewName)
+
+    /** The view this client reads. */
+    val name: String get() = delegate.viewName()
+
+    fun findMany(): List<Row> = delegate.findMany()
+
+    fun findMany(block: QueryBuilder.() -> Unit): List<Row> = delegate.findMany(query(block))
+
+    fun findFirst(where: Where): Row? = delegate.findFirst(where.toJavaFilter())
+
+    fun findUnique(where: Where): Row? = delegate.findUnique(where.toJavaFilter())
+
+    fun count(where: Where? = null): Long = delegate.count(where?.toJavaWhere())
+
+    fun aggregate(block: AggregateBuilder.() -> Unit): Row =
+        delegate.aggregate(AggregateBuilder().apply(block).build())
+
+    fun groupBy(vararg by: String, block: AggregateBuilder.() -> Unit = {}): List<Row> =
+        delegate.groupBy(AggregateBuilder().apply(block).groupedBy(*by).build())
+
+    @JvmOverloads
+    fun vectorSearch(
+        vector: DoubleArray,
+        take: Int = 10,
+        where: Where? = null,
+        vectorField: String = "embedding",
+        metric: DistanceMetric = DistanceMetric.COSINE,
+    ): List<Row> = delegate.vectorSearch(vector, take, where?.toJavaWhere(), vectorField, metric.sql)
+
+    fun create(data: Data): Row = delegate.create(data.toJavaData())
+
+    fun update(where: Where, data: Data): Row? = delegate.update(where.toJavaFilter(), data.toJavaData())
+
+    fun updateMany(where: Where?, data: Data): Int =
+        affected(delegate.updateMany(where?.toJavaWhere(), data.toJavaData()))
+
+    fun delete(where: Where): Row? = delegate.delete(where.toJavaFilter())
+
+    fun deleteMany(where: Where? = null): Int = affected(delegate.deleteMany(where?.toJavaWhere()))
+
+    fun upsert(where: Where, create: Data, update: Data): Row =
+        delegate.upsert(where.toJavaFilter(), create.toJavaData(), update.toJavaData())
+
+    override fun toString(): String = "ViewClient($name)"
+}
+
+/** The affected row count a write returned. */
+private fun affected(result: Map<String, Any?>): Int = (result["count"] as? Number)?.toInt() ?: 0

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

@@ -0,0 +1,77 @@
+package an5.adapters
+
+/**
+ * The database dialects AN5 speaks.
+ *
+ * A typealias rather than a second enum: the JVM adapter already decides quoting,
+ * pagination and the `WITH (NOLOCK)` hint, and a copy of the enum here would be a second
+ * source of truth that could drift from the one that produces the SQL.
+ */
+typealias Dialect = an5.adapters.base.Dialect
+
+/** One row, keyed by column label, in the order the query selected the columns. */
+typealias Row = Map<String, Any?>
+
+/** A filter tree: scalar values, operator maps, and nested `AND`/`OR`/`NOT` groups. */
+typealias Where = Map<String, Any?>
+
+/** A write payload: column values, plus any relation writes the metadata declares. */
+typealias Data = Map<String, Any?>
+
+/** An eager-load description: relation name to `true`, or to a nested query description. */
+typealias Include = Map<String, Any?>
+
+/** Sort direction, with the SQL each one writes. */
+enum class Sort(val sql: String) {
+    ASC("asc"),
+    DESC("desc"),
+}
+
+/**
+ * The distance metrics a vector search understands.
+ *
+ * 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.
+ */
+enum class DistanceMetric(val sql: String) {
+    COSINE("cosine"),
+    EUCLIDEAN("euclidean"),
+    DOT("dot"),
+}
+
+/**
+ * Rebuilds a Kotlin value as a plain Java one.
+ *
+ * Kotlin's `Map` and `List` interfaces are read-only, so they are not assignable to the
+ * `java.util.Map` parameters the JVM adapter declares. Every value that crosses that
+ * boundary goes through here, which is also what lets the public API use `mapOf` — the
+ * literal everyone writes — instead of `mutableMapOf`.
+ */
+internal fun Any?.toJava(): Any? = when (this) {
+    is Map<*, *> -> toJavaMap()
+    is Iterable<*> -> map { it.toJava() }
+    is Array<*> -> map { it.toJava() }
+    is IntArray -> map { it }
+    is DoubleArray -> map { it }
+    is LongArray -> map { it }
+    else -> this
+}
+
+/** The map as the adapter takes it: mutable, with string keys and values converted. */
+internal fun Map<*, *>.toJavaMap(): MutableMap<String, Any?> {
+    val target = LinkedHashMap<String, Any?>(size)
+    for ((key, value) in this) {
+        target[key.toString()] = value.toJava()
+    }
+    return target
+}
+
+/** The filter tree as the adapter takes it, or `null` when there is none. */
+internal fun Where?.toJavaWhere(): MutableMap<String, Any?>? = this?.toJavaMap()
+
+/** The filter tree as the adapter takes it; for parameters that are not optional. */
+internal fun Where.toJavaFilter(): MutableMap<String, Any?> = toJavaMap()
+
+/** The payload as the adapter takes it. */
+internal fun Data.toJavaData(): MutableMap<String, Any?> = toJavaMap()