@an5/adapters 0.2.10 → 0.2.13

package/README.md

@@ -13,7 +13,7 @@ Standalone runtime database adapter and query engine for AN5 ORM. Provides conne
 - **Field Math Operators** — Atomic updates with `increment`, `decrement`, `multiply`, `divide`, `set`
 - **Vector Search** — Similarity search using NBase, pgvector (PostgreSQL), `VECTOR_DISTANCE` (MSSQL), or in-memory cosine/euclidean/dot similarity
 - **Real Transactions** — Interactive and callback transactions (`$transaction(async tx => ...)` and `$begin()/$commit()/$rollback()`)
-- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, and Rust
+- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, Rust, Java, Kotlin, and Swift
 - **Google Sheets Database** — Use spreadsheets as a live database with full CRUD and SQL syntax support
 
 ---
@@ -52,6 +52,78 @@ cargo add an5-adapters
 
 The crate is driver-agnostic — it depends on `sqlx` with `any`, so the app enables the driver it needs. See [crates.io](https://crates.io/crates/an5-adapters) and [docs.rs](https://docs.rs/an5-adapters).
 
+### Java
+
+```bash
+# Included in the npm package under java/, which ships its own pom.xml
+```
+
+`java/` is a Maven module with **no dependencies**: the adapter speaks JDBC through
+`java.sql`, so the app picks the driver it already has — `org.xerial:sqlite-jdbc`,
+`org.postgresql:postgresql` or `com.microsoft.sqlserver:mssql-jdbc`. That is what lets one
+runtime serve all three engines and what keeps it usable on Android, where an adapter that
+dragged in three drivers would not fit.
+
+```xml
+<dependency>
+  <groupId>io.github.an5orm</groupId>
+  <artifactId>an5-adapters-java</artifactId>
+  <version>0.2.13</version>
+</dependency>
+```
+
+From a checkout the same module is built and installed into `~/.m2`:
+
+```bash
+mvn -f java/pom.xml install
+mvn -f java/pom.xml test
+```
+
+### Kotlin
+
+```bash
+# Included in the npm package under kotlin/, which ships build.gradle.kts
+```
+
+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. The Kotlin runtime depends on the Java one
+rather than reimplementing it, so the dialect rules and the where builder exist once:
+
+```kotlin
+dependencies {
+    implementation("io.github.an5orm:an5-adapters-kotlin:0.2.13")
+}
+```
+
+From a checkout the Kotlin module resolves its Java sibling from `~/.m2` — declared as
+`mavenLocal()` in `build.gradle.kts`, so the checkout builds without publishing anything
+first:
+
+```bash
+mvn -f java/pom.xml install
+gradle -p kotlin build
+```
+
+Both JVM modules publish to Maven Central, and each release ships both
+`io.github.an5orm:an5-adapters-java:<version>` and
+`io.github.an5orm:an5-adapters-kotlin:<version>`: a `v*` tag runs the
+`publish-maven` job in `.github/workflows/publish.yml` (`mvn -Prelease deploy` and
+`gradle publish`), and a manual run is available through the workflow's `publish-maven`
+input. It needs the repository secrets `MAVEN_CENTRAL_USERNAME` and `MAVEN_CENTRAL_TOKEN`
+(a Central Portal token), `MAVEN_GPG_PRIVATE_KEY` and `MAVEN_GPG_PASSPHRASE`.
+
+### Swift
+
+```swift
+.package(url: "https://github.com/an5ORM/an5Adapters.git", from: "0.2.13")
+```
+
+A SwiftPM package that links the **system** SQLite — the database every Apple platform
+already ships, so there is no bundled engine and the same file works on device and in the
+simulator. Building it needs SQLite's headers (`apt-get install libsqlite3-dev` on Linux).
+The runtime takes a `SQLDriver`, so an app that already has a database layer can put GRDB or
+SQLite.swift underneath instead.
+
 ---
 
 ## NBase — Neural Vector Database
@@ -139,6 +211,65 @@ If NBase is unreachable, `vectorSearch` logs a warning and falls back to the
 database's native vector support, then to in-memory similarity, so an outage
 degrades performance rather than breaking queries.
 
+---
+
+## SQLite — vector search without a vector database
+
+For host-language-free distance calculation, build the shared
+[AN5 C extension](native/sqlite/README.md) with
+`npm run build:sqlite:native` and pass the printed library path as `sqliteVec`.
+It runs cosine, Euclidean and dot-product distances natively, with SSE2 on
+x86-64 and query-vector caching. The existing fallback remains available when
+an extension is not loaded.
+
+SQLite has no vector type, so a `VECTOR(n)` column stores a **BLOB of
+little-endian float32** — 4 bytes per dimension. Write a plain array of numbers
+and the adapter encodes it; read it back and you get the same array. A column
+that already holds JSON text (`'[0.1, 0.2]'`) keeps working, so nothing has to
+be migrated.
+
+```ts
+await db.table('Article').create({ data: { title: '…', embedding: queryEmbedding } });
+
+const row = await db.table('Article').findFirst({ where: { title: '…' } });
+row.embedding; // number[]
+```
+
+The search is ranked **inside the database**, trying four strategies in order:
+
+| Order | Strategy | Needs | Reaches |
+|-------|----------|-------|---------|
+| 1 | `sqlite-vec` | The extension loaded | Scalar distances over ordinary tables |
+| 2 | `udf` | A driver that can register a function | `BLOB` and legacy text columns |
+| 3 | `sql` | JSON1 (built in since SQLite 3.38) | Legacy text columns |
+| 4 | `memory` | Nothing | Any column, whole table loaded |
+
+Strategies 1-3 transfer only the rows that match, which is the reason to prefer
+them. A row whose stored vector cannot be scored is left out rather than returned
+with a null distance.
+
+[sqlite-vec](https://github.com/asg017/sqlite-vec) supplies native vector distance
+functions for exact search. The adapter scans an ordinary table with those
+functions; it does not create or synchronize a `vec0` virtual table:
+
+```ts
+const db = createAn5Adapter({
+  connectionString: 'sqlite:///app.db',
+  sqliteVec: require('sqlite-vec').getLoadablePath(),
+});
+```
+
+`vectorStrategy` pins one strategy instead of probing — `'auto'` (the default),
+`'sqlite-vec'`, `'udf'`, `'sql'` or `'memory'`. Every other runtime implements
+the same four strategies with the same order; `sqlx` (Rust) and JDBC (Java,
+Kotlin) use `sql` for JSON text and `memory` for BLOB columns without
+driver-specific vector functions.
+
+```python
+from an5_adapter import create_an5_adapter
+db = create_an5_adapter("sqlite:///app.db", sqlite_vec="vec0", vector_strategy="auto")
+```
+
 
 ## Usage
 
@@ -274,10 +405,40 @@ db.transaction(perform_transfer)
 | `count(args)` | Count matching records |
 | `aggregate(args)` | Compute `_count`, `_sum`, `_avg`, `_min`, `_max` |
 | `groupBy(args)` | Group by fields with aggregations and pagination |
-| `vectorSearch(args)` | Semantic vector similarity search |
+| `vectorSearch(args)` | Semantic vector similarity search; SQLite ranks it in the database (sqlite-vec, `an5_vec_*`, `json_each`), everything else uses the engine's native support or scores in memory |
+
+Generated TypeScript field metadata marks schema primary keys with `isId: true`.
+SQL and Google Sheets `create` use this marker to identify custom primary-key
+names before falling back to `id` or `...Id` for older metadata. Regenerate the
+client to enable this behavior for existing custom-key schemas.
+
+`createMany` uses a bulk statement when every row supplies the same columns.
+Rows with different column sets or missing generated UUID keys are inserted
+individually so omitted columns retain their defaults and UUID keys are assigned. Bulk failures are propagated without retrying
+individual rows. Wrap mixed-column inserts in `$transaction` when they must
+succeed or roll back together.
+
+For SQL adapters, `skipDuplicates: true` skips only unique or primary-key
+violations. Connection failures and other constraint errors are propagated.
+Google Sheets does not enforce unique constraints; this flag does not deduplicate
+sheet rows, and failed batch appends are propagated without individual retries.
+
+For SQL adapters, `findMany` and `groupBy` accept `skip` without `take` to
+return all remaining rows or groups. Supply `orderBy` for stable row pagination;
+`groupBy` orders by its grouping fields when pagination has no explicit ordering.
+With relation metadata configured, `groupBy.where` supports the same relation
+filters as `findMany.where`, including `some`, `none`, `every`, `is`, and `isNot`.
 
 ---
 
 ## License
 
 MIT
+
+### Google Sheets desktop OAuth
+
+Google Sheets connections accept `accessToken`, `refreshToken`, `oauthClientId`, optional `oauthClientSecret`, and `tokenExpiresAt` (Unix milliseconds). The VS Code connection UI can generate and store this URI after browser sign-in and spreadsheet selection. Values in the semicolon-delimited URI must be URL encoded. Keep offline credentials in secure storage; do not commit them.
+
+The adapter refreshes expired access tokens before requests, shares concurrent refresh requests, and retries authentication failures once after refreshing. Revoked credentials report a reconnect error. Existing service account, API key and access-token-only configurations remain supported.
+
+For web applications, use a Google Web OAuth client and per-user access tokens. The browser adapter rejects offline desktop credentials and service account private keys. A browser connection manager must handle account selection, token reacquisition and SQLite persistence; see the [browser connection design](https://an5orm.github.io/docs/guides/browser-connections/).

package/dist/an5Adapter.d.ts

@@ -1,6 +1,7 @@
 import { An5SheetsAdapter, An5SheetsAdapterConfig, SheetsTableClient } from './googlesheets';
 import type { An5AdapterConfig, Dialect, TransactionHandle } from './base/types';
 import { type NBaseAdapterConfig, type NBaseVectorClient } from './nbase';
+import { type SqliteVectorSupport, type VectorStrategyPreference } from './sqlite/vector';
 export type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
 export { setAdapterMetadata, createAdapterProxy, type AdapterMetadata } from './base/metadata';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
@@ -36,6 +37,14 @@ export declare class An5Adapter {
     private requireEngine;
     private requireSheetsAdapter;
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
+    /**
+     * The SQLite engine's vector hooks, or null when this is not a SQLite adapter.
+     * `vectorSearch` needs them to load sqlite-vec and register the distance
+     * functions; a connection with no hooks still searches in memory.
+     */
+    sqliteVectorSupport(): Promise<SqliteVectorSupport | null>;
+    /** `vectorStrategy` from the config, so a project can pin one strategy. */
+    get vectorStrategy(): VectorStrategyPreference | undefined;
     /** INTERNAL: used by AdapterTableClient for DML statements needing row count */
     _executeRaw(query: string, params?: Record<string, any>): Promise<number>;
     /** Execute a raw query with positional values → @p_0, @p_1, ... per dialect */
@@ -141,11 +150,30 @@ export declare class AdapterTableClient<T = any> {
     constructor(adapter: An5Adapter | An5AdapterTx, modelName: string);
     get dialect(): Dialect;
     get tableName(): string;
+    /** The table name this model maps to, before any quoting is applied. */
+    private get mappedTableName();
+    /**
+     * The bare table name, for helpers that take a string literal. `@@map` values
+     * may be pre-quoted or schema-qualified, neither of which `pragma_table_info`
+     * accepts, so the last segment is unwrapped here.
+     */
+    get rawTableName(): string;
     private get nolock();
     /** Build the shared context used by parseWhere to resolve relations and self references. */
     private whereContext;
     private doExec;
     private doExecuteRaw;
+    /**
+     * Encode every `VECTOR(n)` value on its way into SQLite.
+     *
+     * The column holds a float32 BLOB, which is a third of the size of the JSON
+     * text it replaces and is what sqlite-vec reads. Values that already arrived
+     * as text or bytes are left alone, so rows written by an older version stay
+     * readable.
+     */
+    private encodeVectorFields;
+    /** Decode `VECTOR(n)` columns back into `number[]` after a read. */
+    private decodeVectorFields;
     findMany(args?: {
         where?: any;
         orderBy?: any;
@@ -246,6 +274,15 @@ export declare class AdapterTableClient<T = any> {
     }): Promise<(T & {
         distance: number;
     })[]>;
+    /**
+     * Rank the vector column in the client. This is the last resort for every
+     * provider, and the only option on SQLite connections that offer neither
+     * sqlite-vec, a driver function nor JSON1.
+     *
+     * The whole table is loaded, so it is only reasonable for a table small
+     * enough to fit in memory.
+     */
+    private scoreVectorsInMemory;
 }
 export declare function createAn5Adapter(config: AnyAdapterConfig): AnyAdapter;
 export declare function createAn5Adapter<TModels extends object>(config: AnyAdapterConfig): import('./typed').TypedAn5Adapter<TModels>;