@an5/adapters 0.2.4 → 0.2.6

package/README.md

@@ -1,304 +1,189 @@
-# 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 through its own subpath:
-
-```typescript
-import { createAn5SheetsAdapter, An5SheetsAdapter } 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 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#), and Golang
+- **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
+```
+
+---
+
+## 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

package/dist/an5Adapter.d.ts

@@ -1,12 +1,14 @@
 import { An5SheetsAdapter, An5SheetsAdapterConfig, SheetsTableClient } from './googlesheets';
 import type { An5AdapterConfig, Dialect, TransactionHandle } from './base/types';
 export type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
-export { setAdapterMetadata, type AdapterMetadata } from './base/metadata';
+export { setAdapterMetadata, createAdapterProxy, type AdapterMetadata } from './base/metadata';
+export type { TypedAn5Adapter, AdapterAPI } from './typed';
 export type AnyAdapter = An5Adapter | An5SheetsAdapter;
 export type AnyAdapterConfig = An5AdapterConfig | An5SheetsAdapterConfig | {
     connectionString: string;
 };
 export declare class An5Adapter {
+    [key: string]: any;
     private _engine;
     private _engineType;
     private _engineConfig;
@@ -29,28 +31,92 @@ export declare class An5Adapter {
         timeout?: number;
     }): Promise<R>;
     $transaction<R>(list: Promise<R>[]): Promise<R[]>;
+    $begin(): Promise<An5AdapterTx>;
     table<T = any>(modelName: string): AdapterTableClient<T> | SheetsTableClient<T>;
+    private _listeners;
+    private _middlewares;
+    $on(event: 'query' | 'error' | 'warn' | 'info' | string, callback: (...args: any[]) => void): this;
+    $off(event: string, callback: (...args: any[]) => void): this;
+    $emit(event: string, ...args: any[]): void;
+    $use(middleware: (params: {
+        model?: string;
+        action: string;
+        args: any;
+        run: (args: any) => Promise<any>;
+    }) => Promise<any>): this;
+    view<T = any>(viewName: string): ViewClient<T>;
+    $queryProc<T = any>(procName: string, params?: Record<string, any> | any[]): Promise<T[]>;
+    $executeProc(procName: string, params?: Record<string, any> | any[]): Promise<number>;
     readRange<T = any>(range: string): Promise<T[][]>;
     writeRange(range: string, values: any[][]): Promise<void>;
     appendRange(range: string, values: any[][]): Promise<void>;
     listSheets(): Promise<string[]>;
     deleteSheet(name: string): Promise<void>;
 }
+export declare class ViewClient<T = any> {
+    readonly adapter: An5Adapter | An5AdapterTx;
+    readonly viewName: string;
+    private readonly tableClient;
+    constructor(adapter: An5Adapter | An5AdapterTx, viewName: string);
+    get dialect(): Dialect;
+    get tableName(): string;
+    findMany(args?: {
+        where?: any;
+        orderBy?: any;
+        skip?: number;
+        take?: number;
+        select?: any;
+        include?: any;
+    }): Promise<T[]>;
+    findFirst(args?: {
+        where?: any;
+        orderBy?: any;
+        select?: any;
+        include?: any;
+    }): Promise<T | null>;
+    findUnique(args: {
+        where: any;
+        select?: any;
+        include?: any;
+    }): Promise<T | null>;
+    count(args?: {
+        where?: any;
+    }): Promise<number>;
+    aggregate(args: any): Promise<any>;
+    groupBy(args: any): Promise<any[]>;
+    vectorSearch(args: any): Promise<(T & {
+        distance: number;
+    })[]>;
+    create(): Promise<never>;
+    createMany(): Promise<never>;
+    update(): Promise<never>;
+    updateMany(): Promise<never>;
+    delete(): Promise<never>;
+    deleteMany(): Promise<never>;
+    upsert(): Promise<never>;
+}
 export declare class An5AdapterTx {
     private readonly handle;
     readonly dialect: Dialect;
+    [key: string]: any;
+    private closed;
     constructor(handle: TransactionHandle, dialect: Dialect);
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
     _executeRaw(query: string, params?: Record<string, any>): Promise<number>;
+    $commit(): Promise<void>;
+    $rollback(): Promise<void>;
     table<T = any>(modelName: string): AdapterTableClient<T>;
+    private ensureOpen;
 }
 export declare class AdapterTableClient<T = any> {
-    private readonly adapter;
-    private readonly modelName;
+    readonly adapter: An5Adapter | An5AdapterTx;
+    readonly modelName: string;
     constructor(adapter: An5Adapter | An5AdapterTx, modelName: string);
-    private get dialect();
-    private get tableName();
+    get dialect(): Dialect;
+    get tableName(): string;
     private get nolock();
+    /** Build the shared context used by parseWhere to resolve relations and self references. */
+    private whereContext;
     private doExec;
     private doExecuteRaw;
     findMany(args?: {
@@ -59,20 +125,26 @@ export declare class AdapterTableClient<T = any> {
         skip?: number;
         take?: number;
         select?: any;
+        include?: any;
     }): Promise<T[]>;
     findFirst(args?: {
         where?: any;
         orderBy?: any;
         select?: any;
+        include?: any;
     }): Promise<T | null>;
     findUnique(args: {
         where: any;
+        select?: any;
+        include?: any;
     }): Promise<T | null>;
     count(args?: {
         where?: any;
     }): Promise<number>;
     create(args: {
-        data: Partial<T>;
+        data: Partial<T> | any;
+        include?: any;
+        select?: any;
     }): Promise<T>;
     createMany(args: {
         data: Partial<T>[];
@@ -82,7 +154,9 @@ export declare class AdapterTableClient<T = any> {
     }>;
     update(args: {
         where: any;
-        data: Partial<T>;
+        data: Partial<T> | any;
+        include?: any;
+        select?: any;
     }): Promise<T>;
     updateMany(args: {
         where?: any;
@@ -111,9 +185,13 @@ export declare class AdapterTableClient<T = any> {
         where?: any;
         vectorField?: string;
         distanceMetric?: 'cosine' | 'euclidean' | 'dot';
+        vectorElementType?: 'float32' | 'float16' | 'uint8';
     }): Promise<(T & {
         distance: number;
     })[]>;
 }
 export declare function createAn5Adapter(config: AnyAdapterConfig): AnyAdapter;
+export declare function createAn5Adapter<TModels extends object>(config: AnyAdapterConfig): import('./typed').TypedAn5Adapter<TModels>;
 export declare const createAdapter: typeof createAn5Adapter;
+export declare function createBrowserSqliteAdapter(config: any): An5Adapter;
+export declare function executorFromAdapter(adapterLike: any): any;