@an5/adapters 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/README.md +305 -283
  2. package/{typescript → dist}/browser.d.ts +1 -1
  3. package/{typescript → dist}/browser.js +2 -1
  4. package/{typescript → dist}/index.d.ts +2 -0
  5. package/{typescript → dist}/index.js +6 -1
  6. package/dotnet/An5Adapter.cs +275 -275
  7. package/dotnet/Base/Core.cs +82 -82
  8. package/dotnet/Mssql/MssqlEngine.cs +144 -144
  9. package/dotnet/Postgres/PostgresEngine.cs +121 -121
  10. package/package.json +21 -11
  11. package/python/an5_adapter.py +97 -97
  12. package/python/base/__init__.py +3 -3
  13. package/python/base/dialects.py +8 -8
  14. package/python/base/metadata.py +10 -10
  15. package/python/base/sql.py +121 -121
  16. package/python/mssql/__init__.py +1 -1
  17. package/python/mssql/provider.py +62 -62
  18. package/python/postgres/__init__.py +1 -1
  19. package/python/postgres/provider.py +15 -15
  20. package/python/table_client.py +216 -216
  21. package/typescript/src/an5Adapter.ts +505 -505
  22. package/typescript/src/base/index.ts +3 -3
  23. package/typescript/src/base/metadata.ts +28 -28
  24. package/typescript/src/base/sql.ts +98 -98
  25. package/typescript/src/base/types.ts +24 -24
  26. package/typescript/src/browser.ts +6 -6
  27. package/typescript/src/config.ts +95 -95
  28. package/typescript/src/googlesheets/adapter.ts +259 -259
  29. package/typescript/src/googlesheets/an5SheetsAdapter.ts +3 -3
  30. package/typescript/src/googlesheets/config.ts +47 -47
  31. package/typescript/src/googlesheets/helpers.ts +143 -143
  32. package/typescript/src/googlesheets/index.ts +3 -3
  33. package/typescript/src/googlesheets/parseConnectionString.ts +46 -46
  34. package/typescript/src/googlesheets/retry.ts +126 -126
  35. package/typescript/src/googlesheets/sqlExecutor.ts +301 -301
  36. package/typescript/src/googlesheets/tableClient.ts +455 -455
  37. package/typescript/src/googlesheets/types.ts +6 -6
  38. package/typescript/src/index.ts +28 -19
  39. package/typescript/src/mssql/engine.ts +132 -132
  40. package/typescript/src/mssql/index.ts +1 -1
  41. package/typescript/src/mysql/engine.ts +80 -80
  42. package/typescript/src/mysql/index.ts +1 -1
  43. package/typescript/src/postgres/engine.ts +87 -87
  44. package/typescript/src/postgres/index.ts +1 -1
  45. package/typescript/src/sqlite/engine.ts +55 -55
  46. package/typescript/src/sqlite/index.ts +1 -1
  47. /package/{typescript → dist}/an5Adapter.d.ts +0 -0
  48. /package/{typescript → dist}/an5Adapter.js +0 -0
  49. /package/{typescript → dist}/base/index.d.ts +0 -0
  50. /package/{typescript → dist}/base/index.js +0 -0
  51. /package/{typescript → dist}/base/metadata.d.ts +0 -0
  52. /package/{typescript → dist}/base/metadata.js +0 -0
  53. /package/{typescript → dist}/base/sql.d.ts +0 -0
  54. /package/{typescript → dist}/base/sql.js +0 -0
  55. /package/{typescript → dist}/base/types.d.ts +0 -0
  56. /package/{typescript → dist}/base/types.js +0 -0
  57. /package/{typescript → dist}/base/uuid.d.ts +0 -0
  58. /package/{typescript → dist}/base/uuid.js +0 -0
  59. /package/{typescript → dist}/config.d.ts +0 -0
  60. /package/{typescript → dist}/config.js +0 -0
  61. /package/{typescript → dist}/googlesheets/adapter.d.ts +0 -0
  62. /package/{typescript → dist}/googlesheets/adapter.js +0 -0
  63. /package/{typescript → dist}/googlesheets/an5SheetsAdapter.d.ts +0 -0
  64. /package/{typescript → dist}/googlesheets/an5SheetsAdapter.js +0 -0
  65. /package/{typescript → dist}/googlesheets/config.d.ts +0 -0
  66. /package/{typescript → dist}/googlesheets/config.js +0 -0
  67. /package/{typescript → dist}/googlesheets/helpers.d.ts +0 -0
  68. /package/{typescript → dist}/googlesheets/helpers.js +0 -0
  69. /package/{typescript → dist}/googlesheets/index.d.ts +0 -0
  70. /package/{typescript → dist}/googlesheets/index.js +0 -0
  71. /package/{typescript → dist}/googlesheets/parseConnectionString.d.ts +0 -0
  72. /package/{typescript → dist}/googlesheets/parseConnectionString.js +0 -0
  73. /package/{typescript → dist}/googlesheets/retry.d.ts +0 -0
  74. /package/{typescript → dist}/googlesheets/retry.js +0 -0
  75. /package/{typescript → dist}/googlesheets/sqlExecutor.d.ts +0 -0
  76. /package/{typescript → dist}/googlesheets/sqlExecutor.js +0 -0
  77. /package/{typescript → dist}/googlesheets/tableClient.d.ts +0 -0
  78. /package/{typescript → dist}/googlesheets/tableClient.js +0 -0
  79. /package/{typescript → dist}/googlesheets/types.d.ts +0 -0
  80. /package/{typescript → dist}/googlesheets/types.js +0 -0
  81. /package/{typescript → dist}/mssql/engine.d.ts +0 -0
  82. /package/{typescript → dist}/mssql/engine.js +0 -0
  83. /package/{typescript → dist}/mssql/index.d.ts +0 -0
  84. /package/{typescript → dist}/mssql/index.js +0 -0
  85. /package/{typescript → dist}/mysql/engine.d.ts +0 -0
  86. /package/{typescript → dist}/mysql/engine.js +0 -0
  87. /package/{typescript → dist}/mysql/index.d.ts +0 -0
  88. /package/{typescript → dist}/mysql/index.js +0 -0
  89. /package/{typescript → dist}/postgres/engine.d.ts +0 -0
  90. /package/{typescript → dist}/postgres/engine.js +0 -0
  91. /package/{typescript → dist}/postgres/index.d.ts +0 -0
  92. /package/{typescript → dist}/postgres/index.js +0 -0
  93. /package/{typescript → dist}/sqlite/engine.d.ts +0 -0
  94. /package/{typescript → dist}/sqlite/engine.js +0 -0
  95. /package/{typescript → dist}/sqlite/index.d.ts +0 -0
  96. /package/{typescript → dist}/sqlite/index.js +0 -0
package/README.md CHANGED
@@ -1,283 +1,305 @@
1
- # an5Adapters
2
-
3
- Standalone runtime adapters for AN5 ORM. Provides connection pooling, query execution, typed table clients in TypeScript, Python, .NET, and Google Sheets API.
4
-
5
- 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.
6
-
7
- ## Features
8
-
9
- - **Connection pooling** — Managed connection pools with configurable limits
10
- - **Type-safe table clients** — Generic CRUD operations with type inference
11
- - **Full query support** — WHERE, ORDER BY, pagination, aggregates
12
- - **Vector search** — Cosine, euclidean, and dot product similarity
13
- - **Transactions** — Begin/commit/rollback with automatic cleanup
14
- - **Cross-language** — Same API in TypeScript, Python, and .NET
15
- - **Google Sheets** — Use spreadsheets as a database with the same CRUD API
16
-
17
- ## Installation
18
-
19
- ### TypeScript
20
-
21
- ```bash
22
- npm install @an5/adapters
23
- ```
24
-
25
- ### Python
26
-
27
- ```bash
28
- pip install an5-adapters
29
- ```
30
-
31
- ### .NET
32
-
33
- ```bash
34
- dotnet add package An5Adapters
35
- ```
36
-
37
- ## Usage
38
-
39
- ### TypeScript
40
-
41
- ```typescript
42
- import { createAn5Adapter, setAdapterMetadata } from '@an5/adapters';
43
-
44
- setAdapterMetadata({
45
- modelToTable: { User: 'dbo.users' },
46
- modelFields: {
47
- User: {
48
- id: { ts: 'string', sql: 'uniqueidentifier', isId: true },
49
- active: { ts: 'boolean', sql: 'bit' },
50
- },
51
- },
52
- });
53
-
54
- const db = createAn5Adapter({
55
- connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass',
56
- });
57
-
58
- // Table client
59
- const users = db.table<User>('users');
60
- await users.findMany({ where: { active: true }, take: 10 });
61
-
62
- // Raw queries
63
- const rows = await db.exec('SELECT * FROM users WHERE id = @id', { id: '123' });
64
-
65
- // Transactions
66
- await db.$transaction(async (tx) => {
67
- await tx.table('users').create({ data: { name: 'John' } });
68
- });
69
- ```
70
-
71
- ### Python
72
-
73
- ```python
74
- from an5_adapter import create_an5_adapter
75
- from base.metadata import set_adapter_metadata
76
-
77
- set_adapter_metadata({
78
- "modelToTable": {"User": "dbo.users"},
79
- "modelFields": {
80
- "User": {
81
- "id": {"py": "str", "sql": "uniqueidentifier", "isId": True},
82
- "active": {"py": "bool", "sql": "bit"},
83
- }
84
- },
85
- })
86
-
87
- db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
88
-
89
- # Table client
90
- users = db.table("User")
91
- users.find_many(where={"active": True}, take=10)
92
-
93
- # Raw queries
94
- rows = db.exec("SELECT * FROM users WHERE id = ?", params=["123"])
95
-
96
- # Transactions
97
- db.transaction(lambda tx: tx.table("User").create({"name": "John"}))
98
- ```
99
-
100
- ### .NET
101
-
102
- ```csharp
103
- using An5Orm;
104
-
105
- var db = new An5Adapter(connectionString);
106
-
107
- // Table client
108
- var users = db.Table<User>("dbo.users");
109
- var activeUsers = users.FindMany("IsActive = @p", new { p = true });
110
-
111
- // Raw queries
112
- var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id", new { id = "123" });
113
-
114
- // Transactions
115
- db.Transaction(tx => {
116
- tx.Table<User>("dbo.users").Create(new User { Name = "John" });
117
- });
118
- ```
119
-
120
- ### Google Sheets
121
-
122
- ```typescript
123
- import { createAn5SheetsAdapter } from '@an5/adapters';
124
-
125
- const db = createAn5SheetsAdapter({
126
- spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
127
- // Option 1: client email + private key
128
- clientEmail: 'sa@project.iam.gserviceaccount.com',
129
- privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
130
- // Option 2: full service account JSON
131
- // credentials: { client_email: '...', private_key: '...' },
132
- // Optional: map model names to sheet names
133
- sheetMapping: { users: 'UsersData', orders: 'OrdersData' },
134
- });
135
-
136
- // Table client (same API as SQL adapters)
137
- const users = db.table<User>('users');
138
- await users.findMany({ where: { active: true }, take: 10 });
139
- await users.create({ data: { name: 'John', email: 'john@example.com' } });
140
- await users.update({ where: { email: 'john@example.com' }, data: { name: 'Johnny' } });
141
- await users.delete({ where: { email: 'john@example.com' } });
142
-
143
- // Raw range access (Google Sheets specific)
144
- const rawData = await db.readRange('Sheet1!A1:C10');
145
- await db.writeRange('Sheet1!A1:B2', [['Name', 'Age'], ['Alice', '30']]);
146
- await db.appendRange('Sheet1!A:A', [['Bob', '25']]);
147
-
148
- // Auto-creates sheet + header row on first create()
149
- await db.table('orders').create({ data: { id: '1', total: 100 } });
150
-
151
- // List, delete sheets
152
- const sheets = await db.listSheets();
153
- await db.deleteSheet('OldSheet');
154
-
155
- // Clear data (keeps headers) or delete all rows
156
- await db.table('users').clear();
157
- await db.table('users').deleteAll();
158
- ```
159
-
160
- ### Browser Mode (Google Sheets)
161
-
162
- 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`).
163
-
164
- ```typescript
165
- import { createAn5SheetsAdapter } from '@an5/adapters/browser';
166
-
167
- // Option 1: OAuth2 Access Token (e.g. from Firebase Auth or Google Sign-In)
168
- const db = createAn5SheetsAdapter({
169
- spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
170
- accessToken: userOAuthAccessToken,
171
- });
172
-
173
- // Option 2: Google API Key
174
- const db2 = createAn5SheetsAdapter({
175
- spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
176
- apiKey: 'AIzaSy...',
177
- });
178
- ```
179
-
180
- ### Integrated factory (auto-detect adapter)
181
-
182
- ```typescript
183
- import { createAn5Adapter, createAdapter, An5Adapter } from '@an5/adapters';
184
-
185
- // Auto-detects from connection string
186
- const sqlDb = createAn5Adapter({ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass' });
187
-
188
- const sheetsDb = createAn5Adapter({
189
- connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
190
- });
191
-
192
- // Or use the Sheets config object directly (also auto-detected)
193
- const sheetsDb2 = createAdapter({
194
- spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
195
- clientEmail: 'sa@project.iam.gserviceaccount.com',
196
- privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
197
- });
198
-
199
- // Constructor form also delegates googlesheets:// to the Sheets adapter
200
- const sheetsDb3 = new An5Adapter({
201
- connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
202
- });
203
- ```
204
-
205
- **Notes:**
206
- - Each model/table maps to a **sheet tab** (first row = headers)
207
- - Sheets without header rows get auto-created on first `create()`
208
- - Type coercion can use optional adapter metadata (`setAdapterMetadata`) for field types and model-to-table mapping
209
- - Numeric strings (without leading zeros) are auto-coerced; `"00123"` stays string
210
- - Boolean strings `"true"` / `"false"` are auto-coerced
211
- - Sheet names with spaces are automatically escaped (A1 notation)
212
- - Supports service account JSON or individual `clientEmail`+`privateKey`
213
- - Automatic retry with exponential backoff for rate limits (429/500/503)
214
-
215
- ### Provider Imports
216
-
217
- Use the package root for normal applications:
218
-
219
- ```typescript
220
- import { createAn5Adapter, createAn5SheetsAdapter } from '@an5/adapters';
221
- ```
222
-
223
- 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`.
224
-
225
- ## API Reference
226
-
227
- ### An5Adapter / An5SheetsAdapter
228
-
229
- | Method | Description |
230
- |--------|-------------|
231
- | `exec(query, params)` | Execute query, return rows (SQL only) |
232
- | `table<T>(name)` | Get typed table client |
233
- | `$transaction(fn)` | Execute in transaction |
234
- | `$connect()` | Open connection / authenticate |
235
- | `$disconnect()` | Close connection / clear auth |
236
- | `readRange(range)` | Read raw sheet range (Sheets only) |
237
- | `writeRange(range, values)` | Write raw sheet range (Sheets only) |
238
- | `appendRange(range, values)` | Append rows to sheet (Sheets only) |
239
- | `listSheets()` | List all sheet tab names (Sheets only) |
240
- | `deleteSheet(name)` | Delete a sheet tab (Sheets only) |
241
-
242
- ### AdapterTableClient / SheetsTableClient
243
-
244
- | Method | Description |
245
- |--------|-------------|
246
- | `findMany(args)` | Query multiple rows |
247
- | `findFirst(args)` | Query single row |
248
- | `findUnique(where)` | Find by unique key |
249
- | `count(where)` | Count rows |
250
- | `create(data)` | Insert row |
251
- | `createMany(data)` | Bulk insert |
252
- | `update(where, data)` | Update row |
253
- | `updateMany(where, data)` | Update multiple rows |
254
- | `delete(where)` | Delete row |
255
- | `deleteMany(where)` | Delete multiple rows |
256
- | `upsert(where, create, update)` | Insert or update |
257
- | `aggregate(args)` | SUM, AVG, MIN, MAX, COUNT |
258
- | `groupBy(args)` | Group by fields |
259
- | `vectorSearch(args)` | Semantic similarity search |
260
- | `clear()` | Clear all data rows, keep headers (Sheets only) |
261
- | `deleteAll()` | Delete all data rows including headers (Sheets only) |
262
-
263
- ## Provider Layout
264
-
265
- - TypeScript providers live under `typescript/{base,mssql,postgres,mysql,sqlite,googlesheets}`.
266
- - Python providers live under `python/{base,mssql,postgres}`, with `python/an5_adapter.py` kept as the public facade.
267
- - .NET providers live under `dotnet/{Base,Mssql,Postgres}`, with `dotnet/an5Adapter.cs` kept as the public facade.
268
- - Adapters do not depend on generated `an5-client` artifacts; generated clients may pass metadata in explicitly when they need model/table mapping.
269
-
270
- ## Testing
271
-
272
- ```bash
273
- # TypeScript/Node
274
- node test/unit.test.js
275
-
276
- # Python
277
- python -m compileall python
278
- python test/smoke.py
279
- ```
280
-
281
- ## License
282
-
283
- MIT
1
+ # an5Adapters
2
+
3
+ Standalone runtime adapters for AN5 ORM. Provides connection pooling, query execution, typed table clients in TypeScript, Python, .NET, and Google Sheets API.
4
+
5
+ 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.
6
+
7
+ ## Features
8
+
9
+ - **Connection pooling** — Managed connection pools with configurable limits
10
+ - **Type-safe table clients** — Generic CRUD operations with type inference
11
+ - **Full query support** — WHERE, ORDER BY, pagination, aggregates
12
+ - **Vector search** — Cosine, euclidean, and dot product similarity
13
+ - **Transactions** — Begin/commit/rollback with automatic cleanup
14
+ - **Cross-language** — Same API in TypeScript, Python, and .NET
15
+ - **Google Sheets** — Use spreadsheets as a database with the same CRUD API
16
+
17
+ ## Installation
18
+
19
+ ### TypeScript
20
+
21
+ ```bash
22
+ npm install @an5/adapters
23
+ ```
24
+
25
+ ### Python
26
+
27
+ ```bash
28
+ pip install an5-adapters
29
+ ```
30
+
31
+ ### .NET
32
+
33
+ ```bash
34
+ dotnet add package An5Adapters
35
+ ```
36
+
37
+ ## Usage
38
+
39
+ ### TypeScript
40
+
41
+ ```typescript
42
+ import { createAn5Adapter, setAdapterMetadata } from '@an5/adapters';
43
+
44
+ setAdapterMetadata({
45
+ modelToTable: { User: 'dbo.users' },
46
+ modelFields: {
47
+ User: {
48
+ id: { ts: 'string', sql: 'uniqueidentifier', isId: true },
49
+ active: { ts: 'boolean', sql: 'bit' },
50
+ },
51
+ },
52
+ });
53
+
54
+ const db = createAn5Adapter({
55
+ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass',
56
+ });
57
+
58
+ // Table client
59
+ const users = db.table<User>('users');
60
+ await users.findMany({ where: { active: true }, take: 10 });
61
+
62
+ // Raw queries
63
+ const rows = await db.exec('SELECT * FROM users WHERE id = @id', { id: '123' });
64
+
65
+ // Transactions
66
+ await db.$transaction(async (tx) => {
67
+ await tx.table('users').create({ data: { name: 'John' } });
68
+ });
69
+ ```
70
+
71
+ ### Python
72
+
73
+ ```python
74
+ from an5_adapter import create_an5_adapter
75
+ from base.metadata import set_adapter_metadata
76
+
77
+ set_adapter_metadata({
78
+ "modelToTable": {"User": "dbo.users"},
79
+ "modelFields": {
80
+ "User": {
81
+ "id": {"py": "str", "sql": "uniqueidentifier", "isId": True},
82
+ "active": {"py": "bool", "sql": "bit"},
83
+ }
84
+ },
85
+ })
86
+
87
+ db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
88
+
89
+ # Table client
90
+ users = db.table("User")
91
+ users.find_many(where={"active": True}, take=10)
92
+
93
+ # Raw queries
94
+ rows = db.exec("SELECT * FROM users WHERE id = ?", params=["123"])
95
+
96
+ # Transactions
97
+ db.transaction(lambda tx: tx.table("User").create({"name": "John"}))
98
+ ```
99
+
100
+ ### .NET
101
+
102
+ ```csharp
103
+ using System.Collections.Generic;
104
+ using An5Orm;
105
+
106
+ var db = new An5Adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass");
107
+
108
+ // Table client
109
+ var users = db.Table<User>("dbo.users");
110
+ var activeUsers = users.FindMany(
111
+ "IsActive = @p",
112
+ new Dictionary<string, object> { ["p"] = true });
113
+
114
+ // Raw queries
115
+ var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id",
116
+ new Dictionary<string, object> { ["id"] = "123" });
117
+
118
+ // Create / Update / Delete
119
+ users.Create(new User { Name = "John", IsActive = true });
120
+ users.Update(existingUser); // uses the Id property as the key
121
+ users.Delete("123");
122
+
123
+ // Transactions (must return a value; use db.Transaction<int> for void-style)
124
+ db.Transaction(tx =>
125
+ {
126
+ tx.Table<User>("dbo.users").Create(new User { Name = "John" });
127
+ return 0;
128
+ });
129
+ ```
130
+
131
+ Note: `QueryRaw`/`FindMany` take parameters as a `Dictionary<string, object>`,
132
+ not anonymous objects. See `dotnet/An5Adapter.cs` for the full API.
133
+
134
+ ### Google Sheets
135
+
136
+ ```typescript
137
+ import { createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
138
+
139
+ const db = createAn5SheetsAdapter({
140
+ spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
141
+ // Option 1: client email + private key
142
+ clientEmail: 'sa@project.iam.gserviceaccount.com',
143
+ privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
144
+ // Option 2: full service account JSON
145
+ // credentials: { client_email: '...', private_key: '...' },
146
+ // Optional: map model names to sheet names
147
+ sheetMapping: { users: 'UsersData', orders: 'OrdersData' },
148
+ });
149
+
150
+ // Table client (same API as SQL adapters)
151
+ const users = db.table<User>('users');
152
+ await users.findMany({ where: { active: true }, take: 10 });
153
+ await users.create({ data: { name: 'John', email: 'john@example.com' } });
154
+ await users.update({ where: { email: 'john@example.com' }, data: { name: 'Johnny' } });
155
+ await users.delete({ where: { email: 'john@example.com' } });
156
+
157
+ // Raw range access (Google Sheets specific)
158
+ const rawData = await db.readRange('Sheet1!A1:C10');
159
+ await db.writeRange('Sheet1!A1:B2', [['Name', 'Age'], ['Alice', '30']]);
160
+ await db.appendRange('Sheet1!A:A', [['Bob', '25']]);
161
+
162
+ // Auto-creates sheet + header row on first create()
163
+ await db.table('orders').create({ data: { id: '1', total: 100 } });
164
+
165
+ // List, delete sheets
166
+ const sheets = await db.listSheets();
167
+ await db.deleteSheet('OldSheet');
168
+
169
+ // Clear data (keeps headers) or delete all rows
170
+ await db.table('users').clear();
171
+ await db.table('users').deleteAll();
172
+ ```
173
+
174
+ ### Browser Mode (Google Sheets)
175
+
176
+ 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`).
177
+
178
+ ```typescript
179
+ import { createAn5SheetsAdapter } from '@an5/adapters/browser';
180
+
181
+ // Option 1: OAuth2 Access Token (e.g. from Firebase Auth or Google Sign-In)
182
+ const db = createAn5SheetsAdapter({
183
+ spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
184
+ accessToken: userOAuthAccessToken,
185
+ });
186
+
187
+ // Option 2: Google API Key
188
+ const db2 = createAn5SheetsAdapter({
189
+ spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
190
+ apiKey: 'AIzaSy...',
191
+ });
192
+ ```
193
+
194
+ ### Integrated factory (auto-detect adapter)
195
+
196
+ ```typescript
197
+ import { createAn5Adapter, An5Adapter } from '@an5/adapters';
198
+
199
+ // Auto-detects from connection string
200
+ const sqlDb = createAn5Adapter({ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass' });
201
+
202
+ const sheetsDb = createAn5Adapter({
203
+ connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
204
+ });
205
+
206
+ // Or use the Sheets config object directly (also auto-detected)
207
+ const sheetsDb2 = createAn5Adapter({
208
+ spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
209
+ clientEmail: 'sa@project.iam.gserviceaccount.com',
210
+ privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
211
+ });
212
+
213
+ // Constructor form also delegates googlesheets:// to the Sheets adapter
214
+ const sheetsDb3 = new An5Adapter({
215
+ connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
216
+ });
217
+ ```
218
+
219
+ **Notes:**
220
+ - Each model/table maps to a **sheet tab** (first row = headers)
221
+ - Sheets without header rows get auto-created on first `create()`
222
+ - Type coercion can use optional adapter metadata (`setAdapterMetadata`) for field types and model-to-table mapping
223
+ - Numeric strings (without leading zeros) are auto-coerced; `"00123"` stays string
224
+ - Boolean strings `"true"` / `"false"` are auto-coerced
225
+ - Sheet names with spaces are automatically escaped (A1 notation)
226
+ - Supports service account JSON or individual `clientEmail`+`privateKey`
227
+ - Automatic retry with exponential backoff for rate limits (429/500/503)
228
+
229
+ ### Provider Imports
230
+
231
+ Use the package root for normal SQL applications:
232
+
233
+ ```typescript
234
+ import { createAn5Adapter, An5Adapter } from '@an5/adapters';
235
+ ```
236
+
237
+ The Sheets adapter is exposed from the package root and through its own subpath:
238
+
239
+ ```typescript
240
+ import { createAn5SheetsAdapter, An5SheetsAdapter, SheetsTableClient, parseSheetsConnectionString } from '@an5/adapters';
241
+ import { An5SheetsAdapter, createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
242
+ import { parseSheetsConnectionString } from '@an5/adapters/googlesheets';
243
+ ```
244
+
245
+ 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.
246
+
247
+ ## API Reference
248
+
249
+ ### An5Adapter / An5SheetsAdapter
250
+
251
+ | Method | Description |
252
+ |--------|-------------|
253
+ | `exec(query, params)` | Execute query, return rows (SQL only) |
254
+ | `table<T>(name)` | Get typed table client |
255
+ | `$transaction(fn)` | Execute in transaction |
256
+ | `$connect()` | Open connection / authenticate |
257
+ | `$disconnect()` | Close connection / clear auth |
258
+ | `readRange(range)` | Read raw sheet range (Sheets only) |
259
+ | `writeRange(range, values)` | Write raw sheet range (Sheets only) |
260
+ | `appendRange(range, values)` | Append rows to sheet (Sheets only) |
261
+ | `listSheets()` | List all sheet tab names (Sheets only) |
262
+ | `deleteSheet(name)` | Delete a sheet tab (Sheets only) |
263
+
264
+ ### AdapterTableClient / SheetsTableClient
265
+
266
+ | Method | Description |
267
+ |--------|-------------|
268
+ | `findMany(args)` | Query multiple rows |
269
+ | `findFirst(args)` | Query single row |
270
+ | `findUnique(where)` | Find by unique key |
271
+ | `count(where)` | Count rows |
272
+ | `create(data)` | Insert row |
273
+ | `createMany(data)` | Bulk insert |
274
+ | `update(where, data)` | Update row |
275
+ | `updateMany(where, data)` | Update multiple rows |
276
+ | `delete(where)` | Delete row |
277
+ | `deleteMany(where)` | Delete multiple rows |
278
+ | `upsert(where, create, update)` | Insert or update |
279
+ | `aggregate(args)` | SUM, AVG, MIN, MAX, COUNT |
280
+ | `groupBy(args)` | Group by fields |
281
+ | `vectorSearch(args)` | Semantic similarity search |
282
+ | `clear()` | Clear all data rows, keep headers (Sheets only) |
283
+ | `deleteAll()` | Delete all data rows including headers (Sheets only) |
284
+
285
+ ## Provider Layout
286
+
287
+ - 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).
288
+ - 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/`.
289
+ - .NET providers live under `dotnet/{Base,Mssql,Postgres}`, with `dotnet/an5Adapter.cs` kept as the public facade.
290
+ - Adapters do not depend on generated `an5-client` artifacts; generated clients may pass metadata in explicitly when they need model/table mapping.
291
+
292
+ ## Testing
293
+
294
+ ```bash
295
+ # TypeScript/Node
296
+ node test/unit.test.js
297
+
298
+ # Python
299
+ python -m compileall python
300
+ python test/smoke.py
301
+ ```
302
+
303
+ ## License
304
+
305
+ MIT
@@ -1,4 +1,4 @@
1
- export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter } from './googlesheets';
1
+ export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter, parseSheetsConnectionString } from './googlesheets';
2
2
  export type { An5SheetsAdapterConfig } from './googlesheets';
3
3
  export type { An5AdapterConfig, Dialect } from './base/types';
4
4
  export { getFieldsForModel, getModelToTable, setAdapterMetadata } from './base/metadata';
@@ -1,11 +1,12 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.setAdapterMetadata = exports.getModelToTable = exports.getFieldsForModel = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = void 0;
3
+ exports.setAdapterMetadata = exports.getModelToTable = exports.getFieldsForModel = exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = void 0;
4
4
  // Browser-safe entry — no SQL engine imports
5
5
  var googlesheets_1 = require("./googlesheets");
6
6
  Object.defineProperty(exports, "An5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.An5SheetsAdapter; } });
7
7
  Object.defineProperty(exports, "SheetsTableClient", { enumerable: true, get: function () { return googlesheets_1.SheetsTableClient; } });
8
8
  Object.defineProperty(exports, "createAn5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.createAn5SheetsAdapter; } });
9
+ Object.defineProperty(exports, "parseSheetsConnectionString", { enumerable: true, get: function () { return googlesheets_1.parseSheetsConnectionString; } });
9
10
  var metadata_1 = require("./base/metadata");
10
11
  Object.defineProperty(exports, "getFieldsForModel", { enumerable: true, get: function () { return metadata_1.getFieldsForModel; } });
11
12
  Object.defineProperty(exports, "getModelToTable", { enumerable: true, get: function () { return metadata_1.getModelToTable; } });
@@ -2,3 +2,5 @@ export { An5Adapter, AdapterTableClient, createAn5Adapter, setAdapterMetadata, }
2
2
  export type { An5AdapterConfig, AdapterMetadata, Dialect, } from './an5Adapter';
3
3
  export { getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig, resetAdapter, } from './config';
4
4
  export type { LlmConfigData, EmbeddingConfigData, } from './config';
5
+ export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter, parseSheetsConnectionString, } from './googlesheets';
6
+ export type { An5SheetsAdapterConfig, } from './googlesheets';
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.setAdapterMetadata = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
3
+ exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.setAdapterMetadata = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
4
4
  var an5Adapter_1 = require("./an5Adapter");
5
5
  Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return an5Adapter_1.An5Adapter; } });
6
6
  Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return an5Adapter_1.AdapterTableClient; } });
@@ -12,3 +12,8 @@ Object.defineProperty(exports, "setLlmConfig", { enumerable: true, get: function
12
12
  Object.defineProperty(exports, "getEmbeddingConfig", { enumerable: true, get: function () { return config_1.getEmbeddingConfig; } });
13
13
  Object.defineProperty(exports, "setEmbeddingConfig", { enumerable: true, get: function () { return config_1.setEmbeddingConfig; } });
14
14
  Object.defineProperty(exports, "resetAdapter", { enumerable: true, get: function () { return config_1.resetAdapter; } });
15
+ var googlesheets_1 = require("./googlesheets");
16
+ Object.defineProperty(exports, "An5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.An5SheetsAdapter; } });
17
+ Object.defineProperty(exports, "SheetsTableClient", { enumerable: true, get: function () { return googlesheets_1.SheetsTableClient; } });
18
+ Object.defineProperty(exports, "createAn5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.createAn5SheetsAdapter; } });
19
+ Object.defineProperty(exports, "parseSheetsConnectionString", { enumerable: true, get: function () { return googlesheets_1.parseSheetsConnectionString; } });