@an5/adapters 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# 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 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)
+- 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 applications:
+
+```typescript
+import { createAn5Adapter } 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

package/dotnet/An5Adapter.cs

@@ -0,0 +1,275 @@
+// An5Adapter.cs
+// Standalone .NET runtime adapter for AN5 ORM.
+
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+
+namespace An5Orm
+{
+// ─── Adapter ────────────────────────────────────────────────────────────────
+
+    public class An5Adapter : IDisposable
+    {
+        public string ConnectionString { get; }
+        public Dialect Dialect => _engine.Dialect;
+        private readonly IQueryEngine _engine;
+        private readonly int _commandTimeout;
+
+        public An5Adapter(string connectionString, int commandTimeout = 60)
+        {
+            ConnectionString = connectionString ?? throw new ArgumentNullException(nameof(connectionString));
+            _commandTimeout = commandTimeout;
+            _engine = DialectDetector.Detect(connectionString) switch
+            {
+                Dialect.Postgres => new PostgresEngine(connectionString, commandTimeout),
+                _ => new MssqlEngine(connectionString, commandTimeout)
+            };
+        }
+
+        public An5Adapter(An5AdapterOptions options) : this(options.ConnectionString, options.CommandTimeout) { }
+
+        // ── Raw query execution ────────────────────────────────────────────────
+
+        public List<Dictionary<string, object>> QueryRaw(string sql, Dictionary<string, object> parameters = null)
+            => _engine.QueryRaw(sql, parameters);
+
+        public List<T> QueryRaw<T>(string sql, Dictionary<string, object> parameters = null) where T : new()
+            => _engine.QueryRaw<T>(sql, parameters);
+
+        public int ExecuteRaw(string sql, Dictionary<string, object> parameters = null)
+            => _engine.ExecuteRaw(sql, parameters);
+
+        // ── Transaction ────────────────────────────────────────────────────────
+
+        public An5Transaction BeginTransaction()
+        {
+            return new An5Transaction(_engine.BeginTransaction());
+        }
+
+        public TResult Transaction<TResult>(Func<An5Adapter, TResult> fn)
+        {
+            using var txScope = _engine.BeginTransaction();
+            try
+            {
+                var result = fn(this);
+                txScope.Commit();
+                return result;
+            }
+            catch
+            {
+                txScope.Rollback();
+                throw;
+            }
+        }
+
+        // ── Table client factory ───────────────────────────────────────────────
+
+        public AdapterTableClient<T> Table<T>(string tableName) where T : new()
+            => new AdapterTableClient<T>(this, tableName, _engine.Dialect);
+
+        public void Dispose() { }
+    }
+
+// ─── Transaction wrapper ───────────────────────────────────────────────────
+
+    public class An5Transaction : IDisposable
+    {
+        private readonly An5TransactionBase _inner;
+
+        internal An5Transaction(An5TransactionBase inner) => _inner = inner;
+
+        public void Commit() => _inner.Commit();
+        public void Rollback() => _inner.Rollback();
+        public void Dispose() => _inner.Dispose();
+    }
+
+// ─── Typed Table Client ────────────────────────────────────────────────────
+
+    public class AdapterTableClient<T> where T : new()
+    {
+        private readonly An5Adapter _adapter;
+        private readonly string _tableName;
+        private readonly Dialect _dialect;
+
+        public AdapterTableClient(An5Adapter adapter, string tableName, Dialect dialect)
+        {
+            _adapter = adapter;
+            _tableName = SqlQuote.QuoteTable(tableName, dialect);
+            _dialect = dialect;
+        }
+
+        private string Nolock => _dialect == Dialect.Mssql ? " WITH (NOLOCK)" : "";
+
+        private string BuildPagination(string orderBy, int? skip, int? take)
+        {
+            if (take == null) return "";
+            if (_dialect == Dialect.Postgres)
+                return $" LIMIT {take.Value} OFFSET {skip ?? 0}";
+            var o = !string.IsNullOrEmpty(orderBy) ? $" ORDER BY {orderBy}" : " ORDER BY (SELECT NULL)";
+            return $"{o} OFFSET {skip ?? 0} ROWS FETCH NEXT {take.Value} ROWS ONLY";
+        }
+
+        public List<T> FindMany(string whereClause = null, Dictionary<string, object> parameters = null,
+            string orderBy = null, int? skip = null, int? take = null)
+        {
+            var sb = new StringBuilder($"SELECT * FROM {_tableName}{Nolock}");
+            if (!string.IsNullOrEmpty(whereClause)) sb.Append($" WHERE {whereClause}");
+            if (take != null && _dialect == Dialect.Postgres)
+            {
+                if (!string.IsNullOrEmpty(orderBy)) sb.Append($" ORDER BY {orderBy}");
+                sb.Append(BuildPagination(orderBy, skip, take));
+            }
+            else
+            {
+                if (!string.IsNullOrEmpty(orderBy)) sb.Append($" ORDER BY {orderBy}");
+                sb.Append(BuildPagination(orderBy, skip, take));
+            }
+            return _adapter.QueryRaw<T>(sb.ToString(), parameters);
+        }
+
+        public T FindFirst(string whereClause = null, Dictionary<string, object> parameters = null, string orderBy = null)
+        {
+            var rows = FindMany(whereClause, parameters, orderBy, skip: null, take: 1);
+            return rows.Count > 0 ? rows[0] : default;
+        }
+
+        public T FindUnique(object id, string idColumnName = "Id")
+        {
+            return FindFirst($"{SqlQuote.QuoteName(idColumnName, _dialect)} = @id",
+                new Dictionary<string, object> { { "id", id } });
+        }
+
+        public int Count(string whereClause = null, Dictionary<string, object> parameters = null)
+        {
+            var sql = $"SELECT COUNT(*) FROM {_tableName}";
+            if (!string.IsNullOrEmpty(whereClause)) sql += $" WHERE {whereClause}";
+            var rows = _adapter.QueryRaw(sql, parameters);
+            if (rows.Count > 0)
+            {
+                var val = rows[0].Values.GetEnumerator();
+                val.MoveNext();
+                return Convert.ToInt32(val.Current);
+            }
+            return 0;
+        }
+
+        public T Create(T entity)
+        {
+            var props = typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance);
+            var cols = new List<string>();
+            var vals = new List<string>();
+            var parameters = new Dictionary<string, object>();
+
+            foreach (var prop in props)
+            {
+                var val = prop.GetValue(entity);
+                if (val == null) continue;
+                cols.Add(SqlQuote.QuoteName(prop.Name, _dialect));
+                vals.Add("@" + prop.Name);
+                parameters["@" + prop.Name] = val;
+            }
+
+            var sql = $"INSERT INTO {_tableName} ({string.Join(", ", cols)}) VALUES ({string.Join(", ", vals)})";
+            _adapter.ExecuteRaw(sql, parameters);
+            return entity;
+        }
+
+        public T Update(T entity, string idColumnName = "Id")
+        {
+            var props = typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance);
+            var sets = new List<string>();
+            var parameters = new Dictionary<string, object>();
+            object idVal = null;
+
+            foreach (var prop in props)
+            {
+                var val = prop.GetValue(entity);
+                if (prop.Name.Equals(idColumnName, StringComparison.OrdinalIgnoreCase))
+                {
+                    idVal = val;
+                }
+                else if (val != null)
+                {
+                    sets.Add($"{SqlQuote.QuoteName(prop.Name, _dialect)} = @{prop.Name}");
+                    parameters["@" + prop.Name] = val;
+                }
+            }
+
+            if (idVal == null) throw new InvalidOperationException($"Cannot update entity without {idColumnName}");
+            parameters["@_id"] = idVal;
+            var quotedIdCol = SqlQuote.QuoteName(idColumnName, _dialect);
+            var sql = $"UPDATE {_tableName} SET {string.Join(", ", sets)} WHERE {quotedIdCol} = @_id";
+            _adapter.ExecuteRaw(sql, parameters);
+            return entity;
+        }
+
+        public bool Delete(object id, string idColumnName = "Id")
+        {
+            var quotedIdCol = SqlQuote.QuoteName(idColumnName, _dialect);
+            var sql = $"DELETE FROM {_tableName} WHERE {quotedIdCol} = @id";
+            var n = _adapter.ExecuteRaw(sql, new Dictionary<string, object> { { "@id", id } });
+            return n > 0;
+        }
+
+        public int DeleteMany(string whereClause = null, Dictionary<string, object> parameters = null)
+        {
+            var sql = $"DELETE FROM {_tableName}";
+            if (!string.IsNullOrEmpty(whereClause)) sql += $" WHERE {whereClause}";
+            return _adapter.ExecuteRaw(sql, parameters);
+        }
+
+        public T Upsert(T entity, string idColumnName = "Id")
+        {
+            var idProp = typeof(T).GetProperty(idColumnName, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);
+            if (idProp == null) throw new InvalidOperationException($"Property {idColumnName} not found on {typeof(T).Name}");
+            var idVal = idProp.GetValue(entity);
+            var existing = idVal != null ? FindUnique(idVal, idColumnName) : default;
+            if (existing != null) return Update(entity, idColumnName);
+            return Create(entity);
+        }
+
+        // ── Vector Search ──────────────────────────────────────────────────────
+
+        public List<(T Item, double Distance)> VectorSearch(
+            List<double> vector, int take = 10,
+            string whereClause = null, Dictionary<string, object> parameters = null,
+            string vectorField = "Embedding", string distanceMetric = "cosine")
+        {
+            var rows = FindMany(whereClause, parameters);
+            var results = new List<(T, double)>();
+            var vectorProp = typeof(T).GetProperty(vectorField, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);
+            if (vectorProp == null) return results;
+
+            foreach (var row in rows)
+            {
+                var rawVal = vectorProp.GetValue(row);
+                if (rawVal == null) continue;
+                List<double> vec = null;
+                try
+                {
+                    if (rawVal is string s) vec = JsonSerializer.Deserialize<List<double>>(s);
+                }
+                catch { continue; }
+                if (vec == null || vec.Count != vector.Count) continue;
+
+                double dot = 0, m1 = 0, m2 = 0;
+                for (int i = 0; i < vector.Count; i++)
+                {
+                    dot += vector[i] * vec[i];
+                    m1 += vector[i] * vector[i];
+                    m2 += vec[i] * vec[i];
+                }
+                double cosine = (m1 > 0 && m2 > 0) ? dot / (Math.Sqrt(m1) * Math.Sqrt(m2)) : 0;
+                double dist = distanceMetric == "cosine" ? 1.0 - cosine :
+                              distanceMetric == "dot" ? -dot : Math.Sqrt(vector.Count);
+                results.Add((row, dist));
+            }
+
+            results.Sort((a, b) => a.Item2.CompareTo(b.Item2));
+            return results.GetRange(0, Math.Min(take, results.Count));
+        }
+    }
+}

package/dotnet/Base/Core.cs

@@ -0,0 +1,82 @@
+using System;
+using System.Collections.Generic;
+using System.Data.Common;
+
+namespace An5Orm
+{
+public enum Dialect
+    {
+        Mssql,
+        Postgres
+    }
+
+    // ─── Config ────────────────────────────────────────────────────────────────
+
+    public class An5AdapterOptions
+    {
+        public string ConnectionString { get; set; }
+        public int CommandTimeout { get; set; } = 60;
+        public int ConnectRetryCount { get; set; } = 3;
+    }
+
+    // ─── Query Engine Interface ────────────────────────────────────────────────
+
+    internal interface IQueryEngine
+    {
+        Dialect Dialect { get; }
+        List<Dictionary<string, object>> QueryRaw(string sql, Dictionary<string, object> parameters);
+        List<T> QueryRaw<T>(string sql, Dictionary<string, object> parameters) where T : new();
+        int ExecuteRaw(string sql, Dictionary<string, object> parameters);
+        An5TransactionBase BeginTransaction();
+    }
+
+    // ─── Transaction base ──────────────────────────────────────────────────────
+
+    internal abstract class An5TransactionBase : IDisposable
+    {
+        public abstract void Commit();
+        public abstract void Rollback();
+        public abstract void Dispose();
+    }
+
+// ─── Dialect detection ─────────────────────────────────────────────────────
+
+    internal static class DialectDetector
+    {
+        public static Dialect Detect(string connectionString)
+        {
+            var cs = (connectionString ?? "").Trim().ToLowerInvariant();
+            if (cs.StartsWith("postgres://") || cs.StartsWith("postgresql://") || cs.Contains("host="))
+                return Dialect.Postgres;
+            return Dialect.Mssql;
+        }
+    }
+
+// ─── Quoting ───────────────────────────────────────────────────────────────
+
+    internal static class SqlQuote
+    {
+        public static string QuoteName(string name, Dialect dialect)
+        {
+            if (dialect == Dialect.Postgres)
+            {
+                if (name.StartsWith("[") && name.EndsWith("]"))
+                    return "\"" + name.Substring(1, name.Length - 2) + "\"";
+                return "\"" + name + "\"";
+            }
+            return name.StartsWith("[") ? name : "[" + name + "]";
+        }
+
+        public static string QuoteTable(string tableName, Dialect dialect)
+        {
+            if (tableName.StartsWith("[") || tableName.StartsWith("\""))
+                return tableName;
+            if (tableName.Contains("."))
+            {
+                var parts = tableName.Split('.');
+                return string.Join(".", Array.ConvertAll(parts, p => QuoteName(p, dialect)));
+            }
+            return QuoteName(tableName, dialect);
+        }
+    }
+}