@an5/adapters 0.2.2 → 0.2.4

package/{typescript → dist}/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 → dist}/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 → dist}/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 → dist}/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 → dist}/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/dist/googlesheets/retry.d.ts

@@ -0,0 +1,25 @@
+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/dist/googlesheets/retry.js

@@ -0,0 +1,115 @@
+"use strict";
+// ─── 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.ConcurrencyLimiter = exports.TokenBucket = exports.RATE_LIMIT_RPS = exports.MAX_CONCURRENCY = exports.MAX_DELAY = exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
+exports.withRetry = withRetry;
+// ─── 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 || code === 502)
+        return true;
+    if (code === 403) {
+        const reason = err?.errors?.[0]?.reason || '';
+        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, 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 (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 → dist}/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 → dist}/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() {