@an5/adapters 0.2.5 → 0.2.9

package/README.md

@@ -1,305 +1,283 @@
-# an5Adapters
-
-Standalone runtime adapters for AN5 ORM. Provides connection pooling, query execution, typed table clients in TypeScript, Python, .NET, and Google Sheets API.
-
-Adapters are runtime packages only. They do not import generated `an5Client` artifacts; generated clients or applications can pass model metadata explicitly when table-name mapping or field type coercion is needed.
-
-## Features
-
-- **Connection pooling** — Managed connection pools with configurable limits
-- **Type-safe table clients** — Generic CRUD operations with type inference
-- **Full query support** — WHERE, ORDER BY, pagination, aggregates
-- **Vector search** — Cosine, euclidean, and dot product similarity
-- **Transactions** — Begin/commit/rollback with automatic cleanup
-- **Cross-language** — Same API in TypeScript, Python, and .NET
-- **Google Sheets** — Use spreadsheets as a database with the same CRUD API
-
-## Installation
-
-### TypeScript
-
-```bash
-npm install @an5/adapters
-```
-
-### Python
-
-```bash
-pip install an5-adapters
-```
-
-### .NET
-
-```bash
-dotnet add package An5Adapters
-```
-
-## Usage
-
-### TypeScript
-
-```typescript
-import { createAn5Adapter, setAdapterMetadata } from '@an5/adapters';
-
-setAdapterMetadata({
-  modelToTable: { User: 'dbo.users' },
-  modelFields: {
-    User: {
-      id: { ts: 'string', sql: 'uniqueidentifier', isId: true },
-      active: { ts: 'boolean', sql: 'bit' },
-    },
-  },
-});
-
-const db = createAn5Adapter({
-  connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass',
-});
-
-// Table client
-const users = db.table<User>('users');
-await users.findMany({ where: { active: true }, take: 10 });
-
-// Raw queries
-const rows = await db.exec('SELECT * FROM users WHERE id = @id', { id: '123' });
-
-// Transactions
-await db.$transaction(async (tx) => {
-  await tx.table('users').create({ data: { name: 'John' } });
-});
-```
-
-### Python
-
-```python
-from an5_adapter import create_an5_adapter
-from base.metadata import set_adapter_metadata
-
-set_adapter_metadata({
-    "modelToTable": {"User": "dbo.users"},
-    "modelFields": {
-        "User": {
-            "id": {"py": "str", "sql": "uniqueidentifier", "isId": True},
-            "active": {"py": "bool", "sql": "bit"},
-        }
-    },
-})
-
-db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
-
-# Table client
-users = db.table("User")
-users.find_many(where={"active": True}, take=10)
-
-# Raw queries
-rows = db.exec("SELECT * FROM users WHERE id = ?", params=["123"])
-
-# Transactions
-db.transaction(lambda tx: tx.table("User").create({"name": "John"}))
-```
-
-### .NET
-
-```csharp
-using System.Collections.Generic;
-using An5Orm;
-
-var db = new An5Adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass");
-
-// Table client
-var users = db.Table<User>("dbo.users");
-var activeUsers = users.FindMany(
-    "IsActive = @p",
-    new Dictionary<string, object> { ["p"] = true });
-
-// Raw queries
-var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id",
-    new Dictionary<string, object> { ["id"] = "123" });
-
-// Create / Update / Delete
-users.Create(new User { Name = "John", IsActive = true });
-users.Update(existingUser);            // uses the Id property as the key
-users.Delete("123");
-
-// Transactions (must return a value; use db.Transaction<int> for void-style)
-db.Transaction(tx =>
-{
-    tx.Table<User>("dbo.users").Create(new User { Name = "John" });
-    return 0;
-});
-```
-
-Note: `QueryRaw`/`FindMany` take parameters as a `Dictionary<string, object>`,
-not anonymous objects. See `dotnet/An5Adapter.cs` for the full API.
-
-### Google Sheets
-
-```typescript
-import { createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
-
-const db = createAn5SheetsAdapter({
-  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
-  // Option 1: client email + private key
-  clientEmail: 'sa@project.iam.gserviceaccount.com',
-  privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
-  // Option 2: full service account JSON
-  // credentials: { client_email: '...', private_key: '...' },
-  // Optional: map model names to sheet names
-  sheetMapping: { users: 'UsersData', orders: 'OrdersData' },
-});
-
-// Table client (same API as SQL adapters)
-const users = db.table<User>('users');
-await users.findMany({ where: { active: true }, take: 10 });
-await users.create({ data: { name: 'John', email: 'john@example.com' } });
-await users.update({ where: { email: 'john@example.com' }, data: { name: 'Johnny' } });
-await users.delete({ where: { email: 'john@example.com' } });
-
-// Raw range access (Google Sheets specific)
-const rawData = await db.readRange('Sheet1!A1:C10');
-await db.writeRange('Sheet1!A1:B2', [['Name', 'Age'], ['Alice', '30']]);
-await db.appendRange('Sheet1!A:A', [['Bob', '25']]);
-
-// Auto-creates sheet + header row on first create()
-await db.table('orders').create({ data: { id: '1', total: 100 } });
-
-// List, delete sheets
-const sheets = await db.listSheets();
-await db.deleteSheet('OldSheet');
-
-// Clear data (keeps headers) or delete all rows
-await db.table('users').clear();
-await db.table('users').deleteAll();
-```
-
-### Browser Mode (Google Sheets)
-
-For browser environments (React, Vue, Svelte, Next.js client components), import from `@an5/adapters/browser` and configure `accessToken` or `apiKey`. In browser mode, the adapter uses native `fetch()` without importing Node.js modules (`googleapis`, `crypto`, `fs`).
-
-```typescript
-import { createAn5SheetsAdapter } from '@an5/adapters/browser';
-
-// Option 1: OAuth2 Access Token (e.g. from Firebase Auth or Google Sign-In)
-const db = createAn5SheetsAdapter({
-  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
-  accessToken: userOAuthAccessToken,
-});
-
-// Option 2: Google API Key
-const db2 = createAn5SheetsAdapter({
-  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
-  apiKey: 'AIzaSy...',
-});
-```
-
-### Integrated factory (auto-detect adapter)
-
-```typescript
-import { createAn5Adapter, An5Adapter } from '@an5/adapters';
-
-// Auto-detects from connection string
-const sqlDb = createAn5Adapter({ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass' });
-
-const sheetsDb = createAn5Adapter({
-  connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
-});
-
-// Or use the Sheets config object directly (also auto-detected)
-const sheetsDb2 = createAn5Adapter({
-  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
-  clientEmail: 'sa@project.iam.gserviceaccount.com',
-  privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
-});
-
-// Constructor form also delegates googlesheets:// to the Sheets adapter
-const sheetsDb3 = new An5Adapter({
-  connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
-});
-```
-
-**Notes:**
-- Each model/table maps to a **sheet tab** (first row = headers)
-- Sheets without header rows get auto-created on first `create()`
-- Type coercion can use optional adapter metadata (`setAdapterMetadata`) for field types and model-to-table mapping
-- Numeric strings (without leading zeros) are auto-coerced; `"00123"` stays string
-- Boolean strings `"true"` / `"false"` are auto-coerced
-- Sheet names with spaces are automatically escaped (A1 notation)
-- Supports service account JSON or individual `clientEmail`+`privateKey`
-- Automatic retry with exponential backoff for rate limits (429/500/503)
-
-### Provider Imports
-
-Use the package root for normal SQL applications:
-
-```typescript
-import { createAn5Adapter, An5Adapter } from '@an5/adapters';
-```
-
-The Sheets adapter is exposed from the package root and through its own subpath:
-
-```typescript
-import { createAn5SheetsAdapter, An5SheetsAdapter, SheetsTableClient, parseSheetsConnectionString } from '@an5/adapters';
-import { An5SheetsAdapter, createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
-import { parseSheetsConnectionString } from '@an5/adapters/googlesheets';
-```
-
-Browser builds (no Node.js modules) use `@an5/adapters/browser`. The public SQL factory `createAn5Adapter` lives in `typescript/src/an5Adapter.ts` and auto-detects `googlesheets://` connection strings.
-
-## API Reference
-
-### An5Adapter / An5SheetsAdapter
-
-| Method | Description |
-|--------|-------------|
-| `exec(query, params)` | Execute query, return rows (SQL only) |
-| `table<T>(name)` | Get typed table client |
-| `$transaction(fn)` | Execute in transaction |
-| `$connect()` | Open connection / authenticate |
-| `$disconnect()` | Close connection / clear auth |
-| `readRange(range)` | Read raw sheet range (Sheets only) |
-| `writeRange(range, values)` | Write raw sheet range (Sheets only) |
-| `appendRange(range, values)` | Append rows to sheet (Sheets only) |
-| `listSheets()` | List all sheet tab names (Sheets only) |
-| `deleteSheet(name)` | Delete a sheet tab (Sheets only) |
-
-### AdapterTableClient / SheetsTableClient
-
-| Method | Description |
-|--------|-------------|
-| `findMany(args)` | Query multiple rows |
-| `findFirst(args)` | Query single row |
-| `findUnique(where)` | Find by unique key |
-| `count(where)` | Count rows |
-| `create(data)` | Insert row |
-| `createMany(data)` | Bulk insert |
-| `update(where, data)` | Update row |
-| `updateMany(where, data)` | Update multiple rows |
-| `delete(where)` | Delete row |
-| `deleteMany(where)` | Delete multiple rows |
-| `upsert(where, create, update)` | Insert or update |
-| `aggregate(args)` | SUM, AVG, MIN, MAX, COUNT |
-| `groupBy(args)` | Group by fields |
-| `vectorSearch(args)` | Semantic similarity search |
-| `clear()` | Clear all data rows, keep headers (Sheets only) |
-| `deleteAll()` | Delete all data rows including headers (Sheets only) |
-
-## Provider Layout
-
-- TypeScript source providers live under `typescript/src/{base,mssql,postgres,mysql,sqlite,googlesheets}`; `npm run build` compiles them into `dist/` (also exposed via `@an5/adapters/base`, `@an5/adapters/mssql`, … subpaths).
-- Python providers live under `python/{base,mssql,postgres}`, with `python/an5_adapter.py` kept as the public facade. `npm run build:python` (or `python -m build --outdir dist-py`) builds the package into `dist-py/`.
-- .NET providers live under `dotnet/{Base,Mssql,Postgres}`, with `dotnet/an5Adapter.cs` kept as the public facade.
-- Adapters do not depend on generated `an5-client` artifacts; generated clients may pass metadata in explicitly when they need model/table mapping.
-
-## Testing
-
-```bash
-# TypeScript/Node
-node test/unit.test.js
-
-# Python
-python -m compileall python
-python test/smoke.py
-```
-
-## License
-
-MIT
+# @an5/adapters
+
+Standalone runtime database adapter and query engine for AN5 ORM. Provides connection pooling, SQL dialect query building (`parseWhere`, `buildOrderBy`, `quote`), dynamic model proxy access, eager loading (`include`), nested writes, vector search, transactions, and typed table clients across TypeScript, Python, .NET (C#), Golang, and Google Sheets.
+
+## Features
+
+- **Dynamic Model Access** — Access models directly via `db.user.findMany()` or `db.User.create()` (proxy resolves casing/plurals via metadata); `db.table('User')` is the escape hatch for runtime-known model names
+- **Typed Model Access** — Bind generated delegates for full type-safety: `createAn5Adapter<{ user: UserTableClient }>({...})`, plus the `TypedAn5Adapter` / `AdapterAPI` helper types
+- **Relations & Eager Loading** — Query nested relations with `include`, relation-level `select`, `where`, `orderBy`, pagination, and `_count`
+- **Nested Writes** — Create and update records with nested relation writes (`create`, `update`, `disconnect`)
+- **Query Builder & Dialects** — Dialect-aware SQL formatting for MSSQL, PostgreSQL, MySQL, and SQLite
+- **Aggregations & GroupBy** — Standard ORM aggregates (`_count`, `_sum`, `_avg`, `_min`, `_max`) and `groupBy`
+- **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
+- **Google Sheets Database** — Use spreadsheets as a live database with full CRUD and SQL syntax support
+
+---
+
+## Installation
+
+### TypeScript
+
+```bash
+npm install @an5/adapters
+```
+
+### Python
+
+```bash
+pip install an5-adapters
+```
+
+### .NET
+
+```bash
+dotnet add package An5Adapters
+```
+
+### Go
+
+```bash
+# Included in the npm package under golang/ or via go module
+```
+
+### Rust
+
+```bash
+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).
+
+---
+
+## NBase — Neural Vector Database
+
+[NBase](https://github.com/N2FlowJS/nbase) is a partitioned vector database with
+HNSW, LSH and KNN indexing behind a REST API. an5 can run vector search there
+instead of loading every row into memory, which matters once a table holds
+millions of embeddings.
+
+The rows stay in your relational table: only the vectors move to NBase, each one
+tagged with its row id, and search results are hydrated from the table.
+
+### Configure
+
+NBase is configured through the connection string, like every other backend:
+
+```ts
+import { createAn5Adapter } from '@an5/adapters';
+
+const db = createAn5Adapter({ connectionString: 'nbase://localhost:1307' });
+await db.$connect(); // probes NBase
+```
+
+Accepted forms:
+
+| Form | Result |
+|------|--------|
+| `nbase://localhost:1307` | `http://localhost:1307` |
+| `nbase:localhost:1307` | `http://localhost:1307` |
+| `nbase:http://localhost:1307` | `http://localhost:1307` |
+| `nbase:https://vectors.example.com` | `https://vectors.example.com` |
+| `nbase://localhost:1307?token=t&timeoutMs=500&method=hnsw` | options applied |
+
+`?token`, `?timeoutMs`, `?method`, `?idField` and `?modelField` are read from the
+query string, and a path is kept as a base path for deployments behind a
+reverse proxy.
+
+This adapter is **vector-only**: it has no relational database, so a search
+returns the NBase hits — id, metadata and `distance` — instead of table rows.
+
+### Search
+
+With an `nbase://` connection string, search returns the hits themselves:
+
+```ts
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id: 'Article:42', an5Id: '42', an5Model: 'Article', distance: 0.11 }
+```
+
+### Search rows from your own table
+
+To get real rows back, keep your database connection string and point it at the
+same NBase instance. NBase is still configured with a connection string, never a
+params object:
+
+```ts
+const db = createAn5Adapter({
+  connectionString: 'sqlserver://localhost:1433;database=mydb',
+  nbase: 'nbase://localhost:1307',
+});
+
+await db.table('Article').indexVectorsInNBase({ vectorField: 'embedding' });
+// → { indexed: 1200 }
+
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id, title, ..., distance }
+```
+
+Vectors are tagged with their row id, so a hit is hydrated from the table by
+that id and the result keeps the `{ ...row, distance }` shape the other engines
+return.
+
+### Standalone client
+
+```ts
+import { createNBaseVectorClient } from '@an5/adapters/nbase';
+
+const nbase = createNBaseVectorClient({ url: 'http://localhost:1307' });
+await nbase.health();
+await nbase.addVectors([{ id: 'a:1', vector: [0.1, 0.2], metadata: { an5Id: '1' } }]);
+const { results } = await nbase.search([0.1, 0.2], { k: 5, distanceMetric: 'cosine' });
+```
+
+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.
+
+
+## Usage
+
+### TypeScript
+
+```typescript
+import { createAn5Adapter } from '@an5/adapters';
+
+const db = createAn5Adapter({
+  connectionString: process.env.DATABASE_URL!,
+});
+
+// Dynamic model access
+const users = await db.user.findMany({
+  where: { active: true },
+  include: {
+    orders: {
+      where: { status: 'paid' },
+      orderBy: { total: 'desc' },
+      take: 5,
+    },
+    _count: true,
+  },
+  take: 10,
+});
+
+// Nested writes
+const created = await db.user.create({
+  data: {
+    email: 'alpha@example.com',
+    name: 'Alpha',
+    orders: {
+      create: [
+        { total: 100, status: 'open' },
+        { total: 250, status: 'paid' },
+      ],
+    },
+  },
+  include: { orders: true, _count: true },
+});
+
+// Atomic updates
+await db.user.update({
+  where: { id: created.id },
+  data: {
+    score: { increment: 10 },
+  },
+});
+
+// Aggregations
+const stats = await db.order.aggregate({
+  _count: true,
+  _sum: { total: true },
+  _avg: { total: true },
+});
+console.log(stats._count._all, stats._sum.total, stats._avg.total);
+
+// Transactions
+await db.$transaction(async (tx) => {
+  await tx.user.update({
+    where: { id: created.id },
+    data: { score: { increment: 5 } },
+  });
+  await tx.order.create({
+    data: { userId: created.id, total: 50, status: 'paid' },
+  });
+});
+
+// Raw query
+const rawRows = await db.$queryRawUnsafe('SELECT * FROM users WHERE active = @p_0', 1);
+
+// Disconnect
+await db.$disconnect();
+```
+
+### Python
+
+```python
+from an5_adapter import create_an5_adapter
+
+db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
+
+# Dynamic model access
+users = db.user.find_many(where={"active": True}, take=10)
+
+# Nested create
+created = db.user.create({
+    "data": {
+        "email": "alpha@example.com",
+        "name": "Alpha",
+    }
+})
+
+# Transactions
+def perform_transfer(tx):
+    tx.user.update({"where": {"id": "u1"}, "data": {"score": {"increment": 10}}})
+
+db.transaction(perform_transfer)
+```
+
+---
+
+## API Reference
+
+### `An5Adapter`
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `db[modelName]` | Dynamic proxy returning `AdapterTableClient` for the model |
+| `table<T>(name)` | Explicitly returns `AdapterTableClient<T>` |
+| `exec(query, params)` | Execute raw parameterized query returning rows |
+| `$queryRawUnsafe(sql, ...args)` | Positional raw query |
+| `$executeRaw(sql, ...args)` | Raw DML execution returning affected count |
+| `$transaction(fn)` | Callback transaction with automatic commit/rollback |
+| `$begin()` | Interactive transaction returning `An5AdapterTx` |
+| `$connect()` | Open connection / pool |
+| `$disconnect()` | Close connections |
+
+### `AdapterTableClient`
+
+| Method | Description |
+|--------|-------------|
+| `findMany(args)` | Query multiple records with `where`, `orderBy`, `skip`, `take`, `select`, `include` |
+| `findFirst(args)` | Query first matching record |
+| `findUnique(args)` | Query unique record by unique filter |
+| `create(args)` | Insert a record with support for nested relation writes |
+| `createMany(args)` | Bulk insert records |
+| `update(args)` | Update record with field math operations & nested relation writes |
+| `updateMany(args)` | Update multiple records |
+| `delete(args)` | Delete a single record |
+| `deleteMany(args)` | Delete multiple records |
+| `upsert(args)` | Insert or update a record |
+| `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 |
+
+---
+
+## License
+
+MIT