@an5/adapters 0.2.2 → 0.2.3

package/README.md

@@ -19,7 +19,7 @@ Adapters are runtime packages only. They do not import generated `an5Client` art
 ### TypeScript
 
 ```bash
-npm install an5-adapters
+npm install @an5/adapters
 ```
 
 ### Python
@@ -39,7 +39,7 @@ dotnet add package An5Adapters
 ### TypeScript
 
 ```typescript
-import { createAn5Adapter, setAdapterMetadata } from 'an5-adapters';
+import { createAn5Adapter, setAdapterMetadata } from '@an5/adapters';
 
 setAdapterMetadata({
   modelToTable: { User: 'dbo.users' },
@@ -120,7 +120,7 @@ db.Transaction(tx => {
 ### Google Sheets
 
 ```typescript
-import { createAn5SheetsAdapter } from 'an5-adapters';
+import { createAn5SheetsAdapter } from '@an5/adapters';
 
 const db = createAn5SheetsAdapter({
   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
@@ -157,10 +157,30 @@ 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, createAdapter, An5Adapter } from 'an5-adapters';
+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' });
@@ -197,7 +217,7 @@ const sheetsDb3 = new An5Adapter({
 Use the package root for normal applications:
 
 ```typescript
-import { createAn5Adapter, createAn5SheetsAdapter } 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@an5/adapters",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Standalone language adapters for AN5 ORM - TypeScript, Python, .NET query execution.",
   "license": "MIT",
   "main": "typescript/index.js",
@@ -14,6 +14,8 @@
     "./dotnet": "./dotnet/An5Adapter.cs",
     "./config": "./typescript/config.js"
   },
+  "author": "an5ORM",
+  "homepage": "https://github.com/an5ORM/an5",
   "repository": {
     "type": "git",
     "url": "https://github.com/an5ORM/an5Adapters.git"

package/typescript/an5Adapter.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAdapter = exports.AdapterTableClient = exports.An5AdapterTx = exports.An5Adapter = exports.setAdapterMetadata = void 0;
 exports.createAn5Adapter = createAn5Adapter;
-const crypto_1 = require("crypto");
+const uuid_1 = require("./base/uuid");
 const googlesheets_1 = require("./googlesheets");
 const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
 const sql_1 = require("./base/sql");
@@ -304,7 +304,7 @@ class AdapterTableClient {
             const normalizedType = String(rawType).toLowerCase();
             const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(normalizedType);
             if (isStringType && !data[idFieldName])
-                data[idFieldName] = (0, crypto_1.randomUUID)();
+                data[idFieldName] = (0, uuid_1.generateUUID)();
         }
         const cols = Object.keys(data).filter(k => data[k] !== undefined);
         const params = {};

package/typescript/base/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cross-platform UUID generator safe for both Browser and Node.js environments.
+ * Uses crypto.randomUUID() when available, with a standard RFC4122 v4 fallback.
+ */
+export declare function generateUUID(): string;

package/typescript/base/uuid.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+/**
+ * Cross-platform UUID generator safe for both Browser and Node.js environments.
+ * Uses crypto.randomUUID() when available, with a standard RFC4122 v4 fallback.
+ */
+function generateUUID() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}

package/typescript/googlesheets/adapter.d.ts

@@ -7,7 +7,7 @@ export declare class An5SheetsAdapter {
     config: ReturnType<typeof resolveConfig>;
     private sheetsCache;
     constructor(config: An5SheetsAdapterConfig);
-    private get isOAuth();
+    private get isFetchMode();
     getSheets(): Promise<any>;
     private getApi;
     invalidateCache(): void;

package/typescript/googlesheets/adapter.js

@@ -6,12 +6,19 @@ const config_1 = require("./config");
 const sqlExecutor_1 = require("./sqlExecutor");
 const tableClient_1 = require("./tableClient");
 const retry_1 = require("./retry");
-// ─── Fetch-based API proxy for OAuth Access Token (browser-compatible) ────────
-function createFetchApi(spreadsheetId, accessToken) {
+// ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
+function createFetchApi(spreadsheetId, accessToken, apiKey) {
     const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
-    const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' };
+    const headers = { 'Content-Type': 'application/json' };
+    if (accessToken) {
+        headers['Authorization'] = `Bearer ${accessToken}`;
+    }
     async function request(method, path, body) {
-        const url = path.startsWith('http') ? path : `${base}${path}`;
+        let url = path.startsWith('http') ? path : `${base}${path}`;
+        if (apiKey) {
+            const sep = url.includes('?') ? '&' : '?';
+            url += `${sep}key=${encodeURIComponent(apiKey)}`;
+        }
         const opts = { method, headers };
         if (body)
             opts.body = JSON.stringify(body);
@@ -73,16 +80,20 @@ class An5SheetsAdapter {
         this.sheetsCache = null;
         this.config = (0, config_1.resolveConfig)(config);
     }
-    get isOAuth() {
-        return !!this.config.accessToken;
+    get isFetchMode() {
+        return !!this.config.accessToken || !!this.config.apiKey;
     }
     async getSheets() {
-        if (this.isOAuth) {
+        if (this.isFetchMode) {
             if (!this.fetchApi) {
-                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken);
+                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey);
             }
             return this.fetchApi;
         }
+        const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+        if (isBrowser) {
+            throw new Error('Google Sheets adapter in browser mode requires "accessToken" or "apiKey" configuration.');
+        }
         if (!this.sheets) {
             const { google } = await import('googleapis');
             const auth = new google.auth.JWT({

package/typescript/googlesheets/config.d.ts

@@ -11,11 +11,14 @@ export interface An5SheetsAdapterConfig {
      * When provided, the adapter uses raw fetch() instead of googleapis JWT, making it compatible
      * with browser environments. Mutually exclusive with clientEmail/privateKey/credentials. */
     accessToken?: string;
+    /** Google API key for browser-based API access. */
+    apiKey?: string;
 }
 export declare function normalizeKey(key: string): string;
 export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     spreadsheetId: string;
-    accessToken: string;
+    accessToken: string | undefined;
+    apiKey: string | undefined;
     sheetMapping: Record<string, string> | undefined;
     clientEmail?: undefined;
     privateKey?: undefined;
@@ -25,4 +28,5 @@ export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     privateKey: string;
     sheetMapping: Record<string, string> | undefined;
     accessToken?: undefined;
+    apiKey?: undefined;
 };

package/typescript/googlesheets/config.js

@@ -12,10 +12,11 @@ function normalizeKey(key) {
     return `-----BEGIN PRIVATE KEY-----\n${lines}\n-----END PRIVATE KEY-----`;
 }
 function resolveConfig(config) {
-    if (config.accessToken) {
+    if (config.accessToken || config.apiKey) {
         return {
             spreadsheetId: config.spreadsheetId,
             accessToken: config.accessToken,
+            apiKey: config.apiKey,
             sheetMapping: config.sheetMapping,
         };
     }

package/typescript/googlesheets/helpers.js

@@ -45,6 +45,12 @@ function matchWhere(row, where) {
                 return false;
             continue;
         }
+        if (key === 'NOT') {
+            const notClauses = Array.isArray(value) ? value : [value];
+            if (notClauses.some((v) => matchWhere(row, v)))
+                return false;
+            continue;
+        }
         const cellVal = row[key];
         if (value === null) {
             if (cellVal !== null && cellVal !== undefined)
@@ -52,22 +58,30 @@ function matchWhere(row, where) {
         }
         else if (typeof value === 'object' && !(value instanceof Date)) {
             const v = value;
+            const caseInsensitive = v.mode === 'insensitive';
+            const normalize = (s) => caseInsensitive ? String(s ?? '').toLowerCase() : s;
             if (v.not !== undefined) {
                 if (v.not === null) {
                     if (cellVal === null || cellVal === undefined)
                         return false;
                 }
-                else if (cellVal == v.not)
+                else if (normalize(cellVal) == normalize(v.not))
                     return false;
             }
-            if (v.equals !== undefined && cellVal != v.equals)
-                return false;
-            if (v.contains !== undefined && (!cellVal || !String(cellVal).includes(v.contains)))
-                return false;
-            if (v.startsWith !== undefined && (!cellVal || !String(cellVal).startsWith(v.startsWith)))
-                return false;
-            if (v.endsWith !== undefined && (!cellVal || !String(cellVal).endsWith(v.endsWith)))
+            if (v.equals !== undefined && normalize(cellVal) != normalize(v.equals))
                 return false;
+            if (v.contains !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).includes(normalize(v.contains)))
+                    return false;
+            }
+            if (v.startsWith !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith)))
+                    return false;
+            }
+            if (v.endsWith !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith)))
+                    return false;
+            }
             if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte)))
                 return false;
             if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte)))
@@ -77,11 +91,16 @@ function matchWhere(row, where) {
             if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt)))
                 return false;
             if (v.in !== undefined) {
-                if (!Array.isArray(v.in) || !v.in.includes(cellVal))
+                if (!Array.isArray(v.in) || !v.in.some((item) => item == cellVal))
+                    return false;
+            }
+            if (v.notIn !== undefined) {
+                if (Array.isArray(v.notIn) && v.notIn.some((item) => item == cellVal))
                     return false;
             }
         }
         else {
+            // loose equality to handle string/number coercion from sheet cells
             if (cellVal != value)
                 return false;
         }

package/typescript/googlesheets/parseConnectionString.js

@@ -31,6 +31,10 @@ function parseSheetsConnectionString(url) {
         result.clientEmail = config.clientemail;
     if (config.privatekey)
         result.privateKey = config.privatekey;
+    if (config.accesstoken)
+        result.accessToken = config.accesstoken;
+    if (config.apikey)
+        result.apiKey = config.apikey;
     if (config.sheetmapping) {
         const mapping = {};
         for (const pair of config.sheetmapping.split(',')) {

package/typescript/googlesheets/retry.d.ts

@@ -1,3 +1,25 @@
-export declare const MAX_RETRIES = 3;
+export declare const MAX_RETRIES = 5;
 export declare const BASE_DELAY = 1000;
+export declare const MAX_DELAY = 32000;
+export declare const MAX_CONCURRENCY = 4;
+export declare const RATE_LIMIT_RPS = 0.9;
+declare class TokenBucket {
+    private tokens;
+    private lastRefill;
+    private readonly ratePerMs;
+    private readonly capacity;
+    constructor(ratePerSecond: number, capacity: number);
+    /** Wait until a token is available, then consume one. */
+    acquire(): Promise<void>;
+}
+declare class ConcurrencyLimiter {
+    private readonly max;
+    private running;
+    private queue;
+    constructor(max: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
 export declare function withRetry<T>(fn: () => Promise<T>, attempt?: number): Promise<T>;
+/** Expose for testing / custom configurations */
+export { TokenBucket, ConcurrencyLimiter };

package/typescript/googlesheets/retry.js

@@ -1,19 +1,83 @@
 "use strict";
-// ─── Retry helper ─────────────────────────────────────────────────────────────
+// ─── Rate Limit & Retry helper ─────────────────────────────────────────────────
+//
+// Google Sheets API quota (default): 100 requests per 100 seconds per project.
+// Strategy:
+//   1. Token-bucket rate limiter  — proactively throttles before hitting quota
+//   2. Concurrency limiter         — max N parallel requests to avoid burst
+//   3. Exponential backoff + jitter — reactive recovery when 429/403/5xx hit
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
+exports.ConcurrencyLimiter = exports.TokenBucket = exports.RATE_LIMIT_RPS = exports.MAX_CONCURRENCY = exports.MAX_DELAY = exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
 exports.withRetry = withRetry;
-exports.MAX_RETRIES = 3;
-exports.BASE_DELAY = 1000;
-function isRateLimitError(err) {
+// ─── Config ────────────────────────────────────────────────────────────────────
+exports.MAX_RETRIES = 5;
+exports.BASE_DELAY = 1000; // ms
+exports.MAX_DELAY = 32000; // ms cap for backoff
+exports.MAX_CONCURRENCY = 4; // parallel in-flight requests
+exports.RATE_LIMIT_RPS = 0.9; // tokens/second (stay under 1 req/s safely)
+// ─── Token Bucket ──────────────────────────────────────────────────────────────
+class TokenBucket {
+    constructor(ratePerSecond, capacity) {
+        this.ratePerMs = ratePerSecond / 1000;
+        this.capacity = capacity;
+        this.tokens = capacity;
+        this.lastRefill = Date.now();
+    }
+    /** Wait until a token is available, then consume one. */
+    async acquire() {
+        while (true) {
+            const now = Date.now();
+            const elapsed = now - this.lastRefill;
+            this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.ratePerMs);
+            this.lastRefill = now;
+            if (this.tokens >= 1) {
+                this.tokens -= 1;
+                return;
+            }
+            // Wait for enough time to refill one token
+            const waitMs = Math.ceil((1 - this.tokens) / this.ratePerMs);
+            await new Promise(r => setTimeout(r, waitMs));
+        }
+    }
+}
+exports.TokenBucket = TokenBucket;
+// ─── Concurrency Limiter ───────────────────────────────────────────────────────
+class ConcurrencyLimiter {
+    constructor(max) {
+        this.max = max;
+        this.running = 0;
+        this.queue = [];
+    }
+    async acquire() {
+        if (this.running < this.max) {
+            this.running++;
+            return;
+        }
+        await new Promise(resolve => this.queue.push(resolve));
+        this.running++;
+    }
+    release() {
+        this.running--;
+        if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            next();
+        }
+    }
+}
+exports.ConcurrencyLimiter = ConcurrencyLimiter;
+// ─── Singleton shared across all adapter instances ─────────────────────────────
+const _bucket = new TokenBucket(exports.RATE_LIMIT_RPS, 10);
+const _concurrency = new ConcurrencyLimiter(exports.MAX_CONCURRENCY);
+// ─── Error classification ──────────────────────────────────────────────────────
+function isRetryableError(err) {
     const code = err?.code || err?.status || err?.response?.status;
     if (code === 429)
         return true;
-    if (code === 500 || code === 503)
+    if (code === 500 || code === 503 || code === 502)
         return true;
     if (code === 403) {
         const reason = err?.errors?.[0]?.reason || '';
-        if (reason === 'rateLimitExceeded')
+        if (reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded')
             return true;
         if (typeof err?.body === 'string' && err.body.includes('rateLimitExceeded'))
             return true;
@@ -22,18 +86,30 @@ function isRateLimitError(err) {
     }
     return false;
 }
+function getRetryDelay(err, attempt) {
+    // Honour server-provided Retry-After
+    if (err?.retryAfter)
+        return err.retryAfter * 1000;
+    // Full jitter exponential backoff: random in [0, min(cap, base * 2^attempt)]
+    const cap = Math.min(exports.MAX_DELAY, exports.BASE_DELAY * Math.pow(2, attempt));
+    return Math.random() * cap;
+}
+// ─── Public API ────────────────────────────────────────────────────────────────
 async function withRetry(fn, attempt = 1) {
+    await _bucket.acquire();
+    await _concurrency.acquire();
     try {
         return await fn();
     }
     catch (err) {
-        if (isRateLimitError(err) && attempt <= exports.MAX_RETRIES) {
-            const delay = err.retryAfter
-                ? err.retryAfter * 1000
-                : exports.BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+        if (isRetryableError(err) && attempt <= exports.MAX_RETRIES) {
+            const delay = getRetryDelay(err, attempt);
             await new Promise(r => setTimeout(r, delay));
             return withRetry(fn, attempt + 1);
         }
         throw err;
     }
+    finally {
+        _concurrency.release();
+    }
 }

package/typescript/googlesheets/tableClient.d.ts

@@ -30,6 +30,7 @@ export declare class SheetsTableClient<T = any> {
     count(args?: {
         where?: any;
     }): Promise<number>;
+    private assignId;
     create(args: {
         data: Partial<T>;
     }): Promise<T>;

package/typescript/googlesheets/tableClient.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SheetsTableClient = void 0;
-const crypto_1 = require("crypto");
+const uuid_1 = require("../base/uuid");
 const metadata_1 = require("../base/metadata");
 const helpers_1 = require("./helpers");
 const retry_1 = require("./retry");
+// ─── Utility ──────────────────────────────────────────────────────────────────
+function resolveIdField(fields) {
+    if (Object.prototype.hasOwnProperty.call(fields, 'id'))
+        return 'id';
+    return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+}
 // ─── Table Client ─────────────────────────────────────────────────────────────
 class SheetsTableClient {
     constructor(adapter, modelName, sheetMapping) {
@@ -146,20 +152,20 @@ class SheetsTableClient {
         const rows = await this.findMany({ where: args?.where });
         return rows.length;
     }
+    assignId(data, fields) {
+        const idFieldName = resolveIdField(fields);
+        if (!idFieldName)
+            return;
+        const fieldDef = fields[idFieldName];
+        const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
+        const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
+        if (isStringType && !data[idFieldName]) {
+            data[idFieldName] = (0, uuid_1.generateUUID)();
+        }
+    }
     async create(args) {
-        const fields = this.fields;
-        const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-            ? 'id'
-            : Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
         const data = { ...args.data };
-        if (idFieldName) {
-            const fieldDef = fields[idFieldName];
-            const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
-            const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
-            if (isStringType && !data[idFieldName]) {
-                data[idFieldName] = (0, crypto_1.randomUUID)();
-            }
-        }
+        this.assignId(data, this.fields);
         const cols = Object.keys(data).filter(k => data[k] !== undefined);
         const headers = await this.getOrCreateHeaders(cols);
         for (const h of headers) {
@@ -174,28 +180,16 @@ class SheetsTableClient {
     async createMany(args) {
         if (args.data.length === 0)
             return { count: 0 };
+        const fields = this.fields;
         const allKeys = new Set();
-        for (const row of args.data) {
+        for (const row of args.data)
             Object.keys(row).forEach(k => allKeys.add(k));
-        }
         const cols = [...allKeys];
-        const fields = this.fields;
-        const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-            ? 'id'
-            : Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
-        const prepared = [];
-        for (const item of args.data) {
+        const prepared = args.data.map(item => {
             const data = { ...item };
-            if (idFieldName) {
-                const fieldDef = fields[idFieldName];
-                const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
-                const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
-                if (isStringType && !data[idFieldName]) {
-                    data[idFieldName] = (0, crypto_1.randomUUID)();
-                }
-            }
-            prepared.push(data);
-        }
+            this.assignId(data, fields);
+            return data;
+        });
         const headers = await this.getOrCreateHeaders(cols);
         const batchValues = prepared.map(data => {
             for (const h of headers) {
@@ -238,16 +232,26 @@ class SheetsTableClient {
     async updateMany(args) {
         const { headers, rows } = await this.readAllRows();
         const matching = rows.filter(r => (0, helpers_1.matchWhere)(r, args.where));
-        for (const target of matching) {
-            const updated = { ...target, ...args.data, __row: target.__row };
-            await this.adapter.writeRange(`${this.escSheetName}!A${target.__row}`, [
-                this.rowToValues(updated, headers),
-            ]);
-        }
+        if (matching.length === 0)
+            return { count: 0 };
+        // Batch all writes into a single batchUpdate call
+        const api = await this.adapter.getSheets();
+        const spreadsheetId = this.adapter.config.spreadsheetId;
+        const valueRanges = matching.map(target => {
+            const updated = { ...target, ...args.data };
+            return {
+                range: `${this.escSheetName}!A${target.__row}`,
+                values: [this.rowToValues(updated, headers)],
+            };
+        });
+        await (0, retry_1.withRetry)(() => api.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: { valueInputOption: 'RAW', data: valueRanges },
+        }));
         return { count: matching.length };
     }
     async delete(args) {
-        const { headers, rows } = await this.readAllRows();
+        const { rows } = await this.readAllRows();
         const matching = rows.filter(r => (0, helpers_1.matchWhere)(r, args.where));
         if (matching.length === 0)
             throw new Error('No record found matching where clause');
@@ -260,17 +264,30 @@ class SheetsTableClient {
         return rest;
     }
     async deleteMany(args) {
-        const { headers, rows } = await this.readAllRows();
+        const { rows } = await this.readAllRows();
         const matching = rows.filter(r => (0, helpers_1.matchWhere)(r, args?.where));
         if (matching.length === 0)
             return { count: 0 };
         const meta = await this.adapter.getSheetMeta(this.sheetName);
         if (!meta)
             throw new Error(`Sheet "${this.sheetName}" not found`);
+        // Batch all deletes into a single batchUpdate (sorted DESC to keep row indices stable)
+        const api = await this.adapter.getSheets();
         const sorted = [...matching].sort((a, b) => b.__row - a.__row);
-        for (const target of sorted) {
-            await this.deleteRowByIndex(target.__row, meta.sheetId);
-        }
+        const requests = sorted.map(target => ({
+            deleteDimension: {
+                range: {
+                    sheetId: meta.sheetId,
+                    dimension: 'ROWS',
+                    startIndex: target.__row - 1,
+                    endIndex: target.__row,
+                },
+            },
+        }));
+        await (0, retry_1.withRetry)(() => api.spreadsheets.batchUpdate({
+            spreadsheetId: this.adapter.config.spreadsheetId,
+            requestBody: { requests },
+        }));
         return { count: matching.length };
     }
     async deleteAll() {

package/typescript/src/an5Adapter.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from 'crypto';
+import { generateUUID } from './base/uuid';
 
 import {
   An5SheetsAdapter,
@@ -317,7 +317,7 @@ export class AdapterTableClient<T = any> {
       const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || fieldDef?.type || '');
       const normalizedType = String(rawType).toLowerCase();
       const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(normalizedType);
-      if (isStringType && !data[idFieldName]) data[idFieldName] = randomUUID();
+      if (isStringType && !data[idFieldName]) data[idFieldName] = generateUUID();
     }
 
     const cols = Object.keys(data).filter(k => data[k] !== undefined);

package/typescript/src/base/uuid.ts

@@ -0,0 +1,14 @@
+/**
+ * Cross-platform UUID generator safe for both Browser and Node.js environments.
+ * Uses crypto.randomUUID() when available, with a standard RFC4122 v4 fallback.
+ */
+export function generateUUID(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}

package/typescript/src/googlesheets/adapter.ts

@@ -5,14 +5,21 @@ import { SheetsTableClient } from './tableClient';
 import { SheetMeta } from './types';
 import { withRetry } from './retry';
 
-// ─── Fetch-based API proxy for OAuth Access Token (browser-compatible) ────────
+// ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
 
-function createFetchApi(spreadsheetId: string, accessToken: string) {
+function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: string) {
   const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
-  const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' };
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (accessToken) {
+    headers['Authorization'] = `Bearer ${accessToken}`;
+  }
 
   async function request<T>(method: string, path: string, body?: any): Promise<T> {
-    const url = path.startsWith('http') ? path : `${base}${path}`;
+    let url = path.startsWith('http') ? path : `${base}${path}`;
+    if (apiKey) {
+      const sep = url.includes('?') ? '&' : '?';
+      url += `${sep}key=${encodeURIComponent(apiKey)}`;
+    }
     const opts: RequestInit = { method, headers };
     if (body) opts.body = JSON.stringify(body);
     const res = await fetch(url, opts);
@@ -79,17 +86,27 @@ export class An5SheetsAdapter {
     this.config = resolveConfig(config);
   }
 
-  private get isOAuth(): boolean {
-    return !!(this.config as any).accessToken;
+  private get isFetchMode(): boolean {
+    return !!(this.config as any).accessToken || !!(this.config as any).apiKey;
   }
 
   async getSheets(): Promise<any> {
-    if (this.isOAuth) {
+    if (this.isFetchMode) {
       if (!this.fetchApi) {
-        this.fetchApi = createFetchApi(this.config.spreadsheetId, (this.config as any).accessToken);
+        this.fetchApi = createFetchApi(
+          this.config.spreadsheetId,
+          (this.config as any).accessToken,
+          (this.config as any).apiKey
+        );
       }
       return this.fetchApi;
     }
+    const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+    if (isBrowser) {
+      throw new Error(
+        'Google Sheets adapter in browser mode requires "accessToken" or "apiKey" configuration.'
+      );
+    }
     if (!this.sheets) {
       const { google } = await import('googleapis');
       const auth = new google.auth.JWT({

package/typescript/src/googlesheets/config.ts

@@ -10,6 +10,8 @@ export interface An5SheetsAdapterConfig {
    * When provided, the adapter uses raw fetch() instead of googleapis JWT, making it compatible
    * with browser environments. Mutually exclusive with clientEmail/privateKey/credentials. */
   accessToken?: string;
+  /** Google API key for browser-based API access. */
+  apiKey?: string;
 }
 
 export function normalizeKey(key: string): string {
@@ -20,10 +22,11 @@ export function normalizeKey(key: string): string {
 }
 
 export function resolveConfig(config: An5SheetsAdapterConfig) {
-  if (config.accessToken) {
+  if (config.accessToken || config.apiKey) {
     return {
       spreadsheetId: config.spreadsheetId,
       accessToken: config.accessToken,
+      apiKey: config.apiKey,
       sheetMapping: config.sheetMapping,
     };
   }

package/typescript/src/googlesheets/helpers.ts

@@ -40,6 +40,11 @@ export function matchWhere(row: Record<string, any>, where: any): boolean {
       if (!value.every((v: any) => matchWhere(row, v))) return false;
       continue;
     }
+    if (key === 'NOT') {
+      const notClauses = Array.isArray(value) ? value : [value];
+      if (notClauses.some((v: any) => matchWhere(row, v))) return false;
+      continue;
+    }
 
     const cellVal = row[key];
 
@@ -47,28 +52,42 @@ export function matchWhere(row: Record<string, any>, where: any): boolean {
       if (cellVal !== null && cellVal !== undefined) return false;
     } else if (typeof value === 'object' && !(value instanceof Date)) {
       const v = value as any;
+      const caseInsensitive = v.mode === 'insensitive';
+      const normalize = (s: any) => caseInsensitive ? String(s ?? '').toLowerCase() : s;
+
       if (v.not !== undefined) {
         if (v.not === null) { if (cellVal === null || cellVal === undefined) return false; }
-        else if (cellVal == v.not) return false;
+        else if (normalize(cellVal) == normalize(v.not)) return false;
+      }
+      if (v.equals !== undefined && normalize(cellVal) != normalize(v.equals)) return false;
+      if (v.contains !== undefined) {
+        if (!cellVal || !normalize(String(cellVal)).includes(normalize(v.contains))) return false;
+      }
+      if (v.startsWith !== undefined) {
+        if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith))) return false;
+      }
+      if (v.endsWith !== undefined) {
+        if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith))) return false;
       }
-      if (v.equals !== undefined && cellVal != v.equals) return false;
-      if (v.contains !== undefined && (!cellVal || !String(cellVal).includes(v.contains))) return false;
-      if (v.startsWith !== undefined && (!cellVal || !String(cellVal).startsWith(v.startsWith))) return false;
-      if (v.endsWith !== undefined && (!cellVal || !String(cellVal).endsWith(v.endsWith))) return false;
       if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte))) return false;
       if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte))) return false;
       if (v.gt !== undefined && !(Number(cellVal) > Number(v.gt))) return false;
       if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt))) return false;
       if (v.in !== undefined) {
-        if (!Array.isArray(v.in) || !v.in.includes(cellVal)) return false;
+        if (!Array.isArray(v.in) || !v.in.some((item: any) => item == cellVal)) return false;
+      }
+      if (v.notIn !== undefined) {
+        if (Array.isArray(v.notIn) && v.notIn.some((item: any) => item == cellVal)) return false;
       }
     } else {
+      // loose equality to handle string/number coercion from sheet cells
       if (cellVal != value) return false;
     }
   }
   return true;
 }
 
+
 export function buildOrderBy(orderBy: any): string {
   if (!orderBy) return '';
   const entries = Array.isArray(orderBy) ? orderBy : [orderBy];

package/typescript/src/googlesheets/parseConnectionString.ts

@@ -30,6 +30,8 @@ export function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig
 
   if (config.clientemail) result.clientEmail = config.clientemail;
   if (config.privatekey) result.privateKey = config.privatekey;
+  if (config.accesstoken) result.accessToken = config.accesstoken;
+  if (config.apikey) result.apiKey = config.apikey;
 
   if (config.sheetmapping) {
     const mapping: Record<string, string> = {};

package/typescript/src/googlesheets/retry.ts

@@ -1,32 +1,126 @@
-// ─── Retry helper ─────────────────────────────────────────────────────────────
+// ─── Rate Limit & Retry helper ─────────────────────────────────────────────────
+//
+// Google Sheets API quota (default): 100 requests per 100 seconds per project.
+// Strategy:
+//   1. Token-bucket rate limiter  — proactively throttles before hitting quota
+//   2. Concurrency limiter         — max N parallel requests to avoid burst
+//   3. Exponential backoff + jitter — reactive recovery when 429/403/5xx hit
 
-export const MAX_RETRIES = 3;
-export const BASE_DELAY = 1000;
+// ─── Config ────────────────────────────────────────────────────────────────────
 
-function isRateLimitError(err: any): boolean {
+export const MAX_RETRIES = 5;
+export const BASE_DELAY = 1000;      // ms
+export const MAX_DELAY = 32_000;     // ms cap for backoff
+export const MAX_CONCURRENCY = 4;    // parallel in-flight requests
+export const RATE_LIMIT_RPS = 0.9;   // tokens/second (stay under 1 req/s safely)
+
+// ─── Token Bucket ──────────────────────────────────────────────────────────────
+
+class TokenBucket {
+  private tokens: number;
+  private lastRefill: number;
+  private readonly ratePerMs: number;
+  private readonly capacity: number;
+
+  constructor(ratePerSecond: number, capacity: number) {
+    this.ratePerMs = ratePerSecond / 1000;
+    this.capacity = capacity;
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+  }
+
+  /** Wait until a token is available, then consume one. */
+  async acquire(): Promise<void> {
+    while (true) {
+      const now = Date.now();
+      const elapsed = now - this.lastRefill;
+      this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.ratePerMs);
+      this.lastRefill = now;
+
+      if (this.tokens >= 1) {
+        this.tokens -= 1;
+        return;
+      }
+
+      // Wait for enough time to refill one token
+      const waitMs = Math.ceil((1 - this.tokens) / this.ratePerMs);
+      await new Promise(r => setTimeout(r, waitMs));
+    }
+  }
+}
+
+// ─── Concurrency Limiter ───────────────────────────────────────────────────────
+
+class ConcurrencyLimiter {
+  private running = 0;
+  private queue: Array<() => void> = [];
+
+  constructor(private readonly max: number) {}
+
+  async acquire(): Promise<void> {
+    if (this.running < this.max) {
+      this.running++;
+      return;
+    }
+    await new Promise<void>(resolve => this.queue.push(resolve));
+    this.running++;
+  }
+
+  release(): void {
+    this.running--;
+    if (this.queue.length > 0) {
+      const next = this.queue.shift()!;
+      next();
+    }
+  }
+}
+
+// ─── Singleton shared across all adapter instances ─────────────────────────────
+
+const _bucket = new TokenBucket(RATE_LIMIT_RPS, 10);
+const _concurrency = new ConcurrencyLimiter(MAX_CONCURRENCY);
+
+// ─── Error classification ──────────────────────────────────────────────────────
+
+function isRetryableError(err: any): boolean {
   const code = err?.code || err?.status || err?.response?.status;
   if (code === 429) return true;
-  if (code === 500 || code === 503) return true;
+  if (code === 500 || code === 503 || code === 502) return true;
   if (code === 403) {
     const reason = err?.errors?.[0]?.reason || '';
-    if (reason === 'rateLimitExceeded') return true;
+    if (reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded') return true;
     if (typeof err?.body === 'string' && err.body.includes('rateLimitExceeded')) return true;
     if (typeof err?.message === 'string' && err.message.includes('rateLimitExceeded')) return true;
   }
   return false;
 }
 
+function getRetryDelay(err: any, attempt: number): number {
+  // Honour server-provided Retry-After
+  if (err?.retryAfter) return err.retryAfter * 1000;
+  // Full jitter exponential backoff: random in [0, min(cap, base * 2^attempt)]
+  const cap = Math.min(MAX_DELAY, BASE_DELAY * Math.pow(2, attempt));
+  return Math.random() * cap;
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
 export async function withRetry<T>(fn: () => Promise<T>, attempt = 1): Promise<T> {
+  await _bucket.acquire();
+  await _concurrency.acquire();
   try {
     return await fn();
   } catch (err: any) {
-    if (isRateLimitError(err) && attempt <= MAX_RETRIES) {
-      const delay = err.retryAfter
-        ? err.retryAfter * 1000
-        : BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+    if (isRetryableError(err) && attempt <= MAX_RETRIES) {
+      const delay = getRetryDelay(err, attempt);
       await new Promise(r => setTimeout(r, delay));
       return withRetry(fn, attempt + 1);
     }
     throw err;
+  } finally {
+    _concurrency.release();
   }
 }
+
+/** Expose for testing / custom configurations */
+export { TokenBucket, ConcurrencyLimiter };

package/typescript/src/googlesheets/tableClient.ts

@@ -1,9 +1,18 @@
-import { randomUUID } from 'crypto';
+import { generateUUID } from '../base/uuid';
 import { getFieldsForModel } from '../base/metadata';
 import type { An5SheetsAdapter } from './adapter';
 import { buildOrderBy, coerceCell, esc, matchWhere, resolveSheetName, sortRows } from './helpers';
 import { withRetry } from './retry';
 
+// ─── Utility ──────────────────────────────────────────────────────────────────
+
+function resolveIdField(fields: Record<string, any>): string | undefined {
+  if (Object.prototype.hasOwnProperty.call(fields, 'id')) return 'id';
+  return Object.keys(fields).find(
+    name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id'
+  );
+}
+
 // ─── Table Client ─────────────────────────────────────────────────────────────
 
 export class SheetsTableClient<T = any> {
@@ -167,21 +176,20 @@ export class SheetsTableClient<T = any> {
     return rows.length;
   }
 
-  async create(args: { data: Partial<T> }): Promise<T> {
-    const fields = this.fields;
-    const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-      ? 'id'
-      : Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+  private assignId(data: any, fields: Record<string, any>): void {
+    const idFieldName = resolveIdField(fields);
+    if (!idFieldName) return;
+    const fieldDef = fields[idFieldName];
+    const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
+    const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
+    if (isStringType && !data[idFieldName]) {
+      data[idFieldName] = generateUUID();
+    }
+  }
 
+  async create(args: { data: Partial<T> }): Promise<T> {
     const data: any = { ...args.data } as any;
-    if (idFieldName) {
-      const fieldDef = fields[idFieldName];
-      const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
-      const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
-      if (isStringType && !data[idFieldName]) {
-        data[idFieldName] = randomUUID();
-      }
-    }
+    this.assignId(data, this.fields);
 
     const cols = Object.keys(data).filter(k => data[k] !== undefined);
     const headers = await this.getOrCreateHeaders(cols);
@@ -200,36 +208,20 @@ export class SheetsTableClient<T = any> {
   async createMany(args: { data: Partial<T>[]; skipDuplicates?: boolean }): Promise<{ count: number }> {
     if (args.data.length === 0) return { count: 0 };
 
+    const fields = this.fields;
     const allKeys = new Set<string>();
-    for (const row of args.data) {
-      Object.keys(row as any).forEach(k => allKeys.add(k));
-    }
+    for (const row of args.data) Object.keys(row as any).forEach(k => allKeys.add(k));
     const cols = [...allKeys];
-    const fields = this.fields;
-    const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-      ? 'id'
-      : Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
 
-    const prepared: Record<string, any>[] = [];
-    for (const item of args.data) {
+    const prepared: Record<string, any>[] = args.data.map(item => {
       const data: any = { ...item } as any;
-      if (idFieldName) {
-        const fieldDef = fields[idFieldName];
-        const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || '');
-        const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(rawType.toLowerCase());
-        if (isStringType && !data[idFieldName]) {
-          data[idFieldName] = randomUUID();
-        }
-      }
-      prepared.push(data);
-    }
+      this.assignId(data, fields);
+      return data;
+    });
 
     const headers = await this.getOrCreateHeaders(cols);
-
     const batchValues = prepared.map(data => {
-      for (const h of headers) {
-        if (data[h] === undefined) data[h] = null;
-      }
+      for (const h of headers) { if (data[h] === undefined) data[h] = null; }
       return this.rowToValues(data, headers);
     });
 
@@ -264,18 +256,30 @@ export class SheetsTableClient<T = any> {
   async updateMany(args: { where?: any; data: Partial<T> }): Promise<{ count: number }> {
     const { headers, rows } = await this.readAllRows();
     const matching = rows.filter(r => matchWhere(r, args.where));
+    if (matching.length === 0) return { count: 0 };
 
-    for (const target of matching) {
-      const updated = { ...target, ...args.data as any, __row: target.__row };
-      await this.adapter.writeRange(`${this.escSheetName}!A${target.__row}`, [
-        this.rowToValues(updated, headers),
-      ]);
-    }
+    // Batch all writes into a single batchUpdate call
+    const api = await this.adapter.getSheets();
+    const spreadsheetId = this.adapter.config.spreadsheetId;
+    const valueRanges = matching.map(target => {
+      const updated = { ...target, ...args.data as any };
+      return {
+        range: `${this.escSheetName}!A${target.__row}`,
+        values: [this.rowToValues(updated, headers)],
+      };
+    });
+
+    await withRetry(() =>
+      (api as any).spreadsheets.values.batchUpdate({
+        spreadsheetId,
+        requestBody: { valueInputOption: 'RAW', data: valueRanges },
+      })
+    );
     return { count: matching.length };
   }
 
   async delete(args: { where: any }): Promise<T> {
-    const { headers, rows } = await this.readAllRows();
+    const { rows } = await this.readAllRows();
     const matching = rows.filter(r => matchWhere(r, args.where));
     if (matching.length === 0) throw new Error('No record found matching where clause');
 
@@ -289,17 +293,33 @@ export class SheetsTableClient<T = any> {
   }
 
   async deleteMany(args?: { where?: any }): Promise<{ count: number }> {
-    const { headers, rows } = await this.readAllRows();
+    const { rows } = await this.readAllRows();
     const matching = rows.filter(r => matchWhere(r, args?.where));
     if (matching.length === 0) return { count: 0 };
 
     const meta = await this.adapter.getSheetMeta(this.sheetName);
     if (!meta) throw new Error(`Sheet "${this.sheetName}" not found`);
 
+    // Batch all deletes into a single batchUpdate (sorted DESC to keep row indices stable)
+    const api = await this.adapter.getSheets();
     const sorted = [...matching].sort((a, b) => b.__row - a.__row);
-    for (const target of sorted) {
-      await this.deleteRowByIndex(target.__row, meta.sheetId);
-    }
+    const requests = sorted.map(target => ({
+      deleteDimension: {
+        range: {
+          sheetId: meta.sheetId,
+          dimension: 'ROWS',
+          startIndex: target.__row - 1,
+          endIndex: target.__row,
+        },
+      },
+    }));
+
+    await withRetry(() =>
+      api.spreadsheets.batchUpdate({
+        spreadsheetId: this.adapter.config.spreadsheetId,
+        requestBody: { requests },
+      })
+    );
     return { count: matching.length };
   }