@an5/adapters 0.2.0 → 0.2.2

package/README.md

@@ -1,45 +1,45 @@
-# an5Adapters
-
+# 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';
+
+## 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' },
@@ -50,27 +50,27 @@ setAdapterMetadata({
     },
   },
 });
-
-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
+
+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
 
@@ -83,112 +83,112 @@ set_adapter_metadata({
         }
     },
 })
-
-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 An5Orm;
-
-var db = new An5Adapter(connectionString);
-
-// Table client
-var users = db.Table<User>("dbo.users");
-var activeUsers = users.FindMany("IsActive = @p", new { p = true });
-
-// Raw queries
-var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id", new { id = "123" });
-
-// Transactions
-db.Transaction(tx => {
-    tx.Table<User>("dbo.users").Create(new User { Name = "John" });
-});
-```
-
-### Google Sheets
-
-```typescript
-import { createAn5Adapter } from '@an5/adapters';
 
-const db = createAn5Adapter({
-  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();
-```
-
-### Integrated factory (auto-detect adapter)
-
-```typescript
-import { createAn5Adapter, createAdapter, 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 = createAdapter({
-  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)
+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 An5Orm;
+
+var db = new An5Adapter(connectionString);
+
+// Table client
+var users = db.Table<User>("dbo.users");
+var activeUsers = users.FindMany("IsActive = @p", new { p = true });
+
+// Raw queries
+var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id", new { id = "123" });
+
+// Transactions
+db.Transaction(tx => {
+    tx.Table<User>("dbo.users").Create(new User { Name = "John" });
+});
+```
+
+### Google Sheets
+
+```typescript
+import { createAn5SheetsAdapter } from 'an5-adapters';
+
+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();
+```
+
+### Integrated factory (auto-detect adapter)
+
+```typescript
+import { createAn5Adapter, createAdapter, 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 = createAdapter({
+  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)
 
@@ -197,67 +197,67 @@ const sheetsDb3 = new An5Adapter({
 Use the package root for normal applications:
 
 ```typescript
-import { createAn5Adapter } from '@an5/adapters';
+import { createAn5Adapter, createAn5SheetsAdapter } from 'an5-adapters';
 ```
 
 Provider folders are still available to source-level consumers through `typescript/*`, but the public factory in `typescript/an5Adapter.ts` is the preferred entry point. The old `unified.ts` entry point has been removed because the factory now lives directly in `An5Adapter`.
-
-## 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 providers live under `typescript/{base,mssql,postgres,mysql,sqlite,googlesheets}`.
-- Python providers live under `python/{base,mssql,postgres}`, with `python/an5_adapter.py` kept as the public facade.
-- .NET providers live under `dotnet/{Base,Mssql,Postgres}`, with `dotnet/an5Adapter.cs` kept as the public facade.
-- Adapters do not depend on generated `an5Client` 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
+
+## 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 providers live under `typescript/{base,mssql,postgres,mysql,sqlite,googlesheets}`.
+- Python providers live under `python/{base,mssql,postgres}`, with `python/an5_adapter.py` kept as the public facade.
+- .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

package/package.json

@@ -1,46 +1,54 @@
-{
+{
   "name": "@an5/adapters",
-  "version": "0.2.0",
-  "description": "Standalone language adapters for AN5 ORM - TypeScript, Python, .NET query execution.",
-  "license": "MIT",
-  "main": "typescript/index.js",
-  "types": "typescript/index.d.ts",
-  "exports": {
-    ".": "./typescript/index.js",
-    "./typescript": "./typescript/index.js",
-    "./typescript/*": "./typescript/*",
-    "./python": "./python/an5_adapter.py",
-    "./dotnet": "./dotnet/An5Adapter.cs",
-    "./config": "./typescript/config.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/an5ORM/an5Adapters.git"
-  },
-  "keywords": ["an5", "orm", "adapter", "typescript", "python", "dotnet"],
+  "version": "0.2.2",
+  "description": "Standalone language adapters for AN5 ORM - TypeScript, Python, .NET query execution.",
+  "license": "MIT",
+  "main": "typescript/index.js",
+  "types": "typescript/index.d.ts",
+  "exports": {
+    ".": "./typescript/index.js",
+    "./browser": "./typescript/browser.js",
+    "./typescript": "./typescript/index.js",
+    "./typescript/*": "./typescript/*",
+    "./python": "./python/an5_adapter.py",
+    "./dotnet": "./dotnet/An5Adapter.cs",
+    "./config": "./typescript/config.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/an5ORM/an5Adapters.git"
+  },
+  "keywords": [
+    "an5",
+    "orm",
+    "adapter",
+    "typescript",
+    "python",
+    "dotnet"
+  ],
   "files": [
     "typescript/**/*.{ts,js,d.ts}",
     "python/**/*.py",
     "dotnet/**/*",
     "README.md"
   ],
-  "scripts": {
+  "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node test/unit.test.js",
-    "test:python": "python -m compileall python 2>&1"
-  },
-  "dependencies": {
-    "googleapis": "^134.0.0",
-    "mssql": "^12.5.5",
-    "pg": "^8.13.0"
-  },
-  "devDependencies": {
-    "@types/mssql": "^9.1.8",
-    "@types/node": "^20.11.0",
-    "@types/pg": "^8.11.0",
-    "typescript": "^6.0.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+    "test": "node test/unit.test.js",
+    "test:python": "python -m compileall python 2>&1"
+  },
+  "dependencies": {
+    "googleapis": "^134.0.0",
+    "mssql": "^12.5.5",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/mssql": "^9.1.8",
+    "@types/node": "^20.11.0",
+    "@types/pg": "^8.11.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/typescript/an5Adapter.d.ts

@@ -7,8 +7,10 @@ export type AnyAdapterConfig = An5AdapterConfig | An5SheetsAdapterConfig | {
     connectionString: string;
 };
 export declare class An5Adapter {
-    private engine;
-    private sheetsAdapter;
+    private _engine;
+    private _engineType;
+    private _engineConfig;
+    sheetsAdapter: An5SheetsAdapter | null;
     get dialect(): Dialect;
     constructor(adapterConfig: An5AdapterConfig | An5SheetsAdapterConfig);
     private requireEngine;