@docstack/pouchdb-adapter-googledrive 0.0.9 → 0.1.0

package/docs/DEBUG_BIDIRECTIONAL_REPLICATION.ipynb

@@ -1,481 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "60e24526",
-   "metadata": {},
-   "source": [
-    "# Debug: Replica Bidirezionale Google Drive PouchDB Adapter\n",
-    "\n",
-    "## Problema\n",
-    "La replica `localDB.replicate.to(googleDriveDB)` funziona ✅  \n",
-    "Ma `localDB.replicate.from(googleDriveDB)` non sincronizza i dati ❌\n",
-    "\n",
-    "Questo notebook diagnostica il flusso di replicazione per identificare dove il blocco si verifica."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "3796436e",
-   "metadata": {},
-   "source": [
-    "## 1️⃣ Section: Setup e Configurazione Replica\n",
-    "\n",
-    "### Aggiungi questo codice al tuo componente per diagnosticare il problema:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5a4749c9",
-   "metadata": {
-    "vscode": {
-     "languageId": "javascript"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "// Setup Google Drive Adapter con debug logging\n",
-    "const plugin = GoogleDriveAdapter({\n",
-    "    accessToken: async () => driveConfig.accessToken,\n",
-    "    folderName: 'my-db',\n",
-    "    pollingIntervalMs: 5000,\n",
-    "    debug: true  // 🔍 Abilita logging dettagliato\n",
-    "});\n",
-    "\n",
-    "PouchDB.plugin(plugin);\n",
-    "\n",
-    "const googleDriveDB = new PouchDB('paper-drive-db', {\n",
-    "    adapter: 'googledrive'\n",
-    "});\n",
-    "\n",
-    "const localDB = stack?.db;\n",
-    "\n",
-    "// 🔍 Aggiungi listener per monitorare gli eventi di replicazione\n",
-    "console.log('=== SETUP REPLICA BIDIREZIONALE ===');\n",
-    "\n",
-    "// Replica TO (localDB → googleDriveDB) - Funzionante ✅\n",
-    "const repTo = localDB.replicate.to(googleDriveDB, { live: true, retry: true });\n",
-    "repTo.on('change', (info) => {\n",
-    "    console.log('📤 TO: change event', { \n",
-    "        direction: 'local→gdrive',\n",
-    "        docs: info.docs?.length,\n",
-    "        ok: info.ok\n",
-    "    });\n",
-    "});\n",
-    "repTo.on('complete', (info) => {\n",
-    "    console.log('✅ TO: replication complete', info);\n",
-    "});\n",
-    "repTo.on('error', (err) => {\n",
-    "    console.error('❌ TO: replication error', err);\n",
-    "});\n",
-    "\n",
-    "// Replica FROM (googleDriveDB → localDB) - Problema ❌\n",
-    "const repFrom = localDB.replicate.from(googleDriveDB, { live: true, retry: true });\n",
-    "repFrom.on('change', (info) => {\n",
-    "    console.log('📥 FROM: change event', { \n",
-    "        direction: 'gdrive→local',\n",
-    "        docs: info.docs?.length,\n",
-    "        ok: info.ok\n",
-    "    });\n",
-    "});\n",
-    "repFrom.on('complete', (info) => {\n",
-    "    console.log('✅ FROM: replication complete', info);\n",
-    "});\n",
-    "repFrom.on('error', (err) => {\n",
-    "    console.error('❌ FROM: replication error', err);\n",
-    "});"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "56686c46",
-   "metadata": {},
-   "source": [
-    "## 2️⃣ Section: Diagnosi - Verifica Flusso di Replicazione\n",
-    "\n",
-    "### Controlla le sequenze e i metadati del database"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "fb620ba8",
-   "metadata": {
-    "vscode": {
-     "languageId": "javascript"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "// Confronta lo stato dei due database\n",
-    "async function compareDatabases() {\n",
-    "    const localInfo = await localDB.info();\n",
-    "    const googleDriveInfo = await googleDriveDB.info();\n",
-    "    \n",
-    "    console.log('📊 DATABASE INFO COMPARISON:');\n",
-    "    console.log('Local DB:', {\n",
-    "        doc_count: localInfo.doc_count,\n",
-    "        update_seq: localInfo.update_seq,\n",
-    "        db_name: localInfo.db_name\n",
-    "    });\n",
-    "    console.log('Google Drive DB:', {\n",
-    "        doc_count: googleDriveInfo.doc_count,\n",
-    "        update_seq: googleDriveInfo.update_seq,\n",
-    "        db_name: googleDriveInfo.db_name\n",
-    "    });\n",
-    "    \n",
-    "    return { localInfo, googleDriveInfo };\n",
-    "}\n",
-    "\n",
-    "// Esegui la diagnosi dopo 25 secondi (dopo che il polling ha avuto tempo di rilevare)\n",
-    "setTimeout(async () => {\n",
-    "    console.log('\\n=== DIAGNOSI DOPO 25 SEC ===\\n');\n",
-    "    \n",
-    "    const { localInfo, googleDriveInfo } = await compareDatabases();\n",
-    "    \n",
-    "    // 🔍 Verifica se le sequenze sono sincronizzate\n",
-    "    if (localInfo.update_seq === googleDriveInfo.update_seq) {\n",
-    "        console.log('✅ Sequenze sincronizzate');\n",
-    "    } else {\n",
-    "        console.warn('⚠️  Sequenze NON sincronizzate:', {\n",
-    "            local: localInfo.update_seq,\n",
-    "            googleDrive: googleDriveInfo.update_seq,\n",
-    "            diff: googleDriveInfo.update_seq - localInfo.update_seq\n",
-    "        });\n",
-    "    }\n",
-    "    \n",
-    "    // 🔍 Verifica il documento specifico su Google Drive\n",
-    "    try {\n",
-    "        const docOnDrive = await googleDriveDB.get('Notebook-0');\n",
-    "        console.log('✅ Notebook-0 trovato su Google Drive:', {\n",
-    "            _id: docOnDrive._id,\n",
-    "            _rev: docOnDrive._rev\n",
-    "        });\n",
-    "    } catch (err) {\n",
-    "        console.error('❌ Notebook-0 NON trovato su Google Drive:', err.message);\n",
-    "    }\n",
-    "    \n",
-    "    // 🔍 Verifica il documento su Local DB\n",
-    "    try {\n",
-    "        const docLocal = await localDB.get('Notebook-0');\n",
-    "        console.log('✅ Notebook-0 trovato su Local DB:', {\n",
-    "            _id: docLocal._id,\n",
-    "            _rev: docLocal._rev\n",
-    "        });\n",
-    "    } catch (err) {\n",
-    "        console.error('❌ Notebook-0 NON trovato su Local DB:', err.message);\n",
-    "    }\n",
-    "    \n",
-    "}, 25000);"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "5015299b",
-   "metadata": {},
-   "source": [
-    "## 3️⃣ Section: Debug - Polling e Change Detection\n",
-    "\n",
-    "### Il problema probabilmente è nel meccanismo di Polling\n",
-    "\n",
-    "Verifica se il polling sta effettivamente rilevando i cambiamenti da Google Drive:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5d57b557",
-   "metadata": {
-    "vscode": {
-     "languageId": "javascript"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "// 🔍 Monitora i cambiamenti rilevati tramite _changes API\n",
-    "async function debugChangesAPI() {\n",
-    "    console.log('\\n=== TESTING _CHANGES API ===\\n');\n",
-    "    \n",
-    "    // Ottieni gli ultimi 10 cambiamenti dal Google Drive DB\n",
-    "    try {\n",
-    "        const changes = await googleDriveDB.changes({\n",
-    "            include_docs: true,\n",
-    "            descending: true,\n",
-    "            limit: 10\n",
-    "        });\n",
-    "        \n",
-    "        console.log('Recent changes from Google Drive DB:', {\n",
-    "            results: changes.results.length,\n",
-    "            last_seq: changes.last_seq,\n",
-    "            results: changes.results.map(r => ({\n",
-    "                id: r.id,\n",
-    "                seq: r.seq,\n",
-    "                changes: r.changes,\n",
-    "                deleted: r.deleted,\n",
-    "                hasDoc: !!r.doc\n",
-    "            }))\n",
-    "        });\n",
-    "        \n",
-    "        return changes;\n",
-    "    } catch (err) {\n",
-    "        console.error('❌ Error fetching changes from Google Drive DB:', err);\n",
-    "    }\n",
-    "}\n",
-    "\n",
-    "// Testa la _changes API subito\n",
-    "await debugChangesAPI();\n",
-    "\n",
-    "// Testa di nuovo dopo 10 secondi per vedere se il polling ha rilevato nuovi cambiamenti\n",
-    "setTimeout(async () => {\n",
-    "    console.log('\\n=== TESTING _CHANGES API AFTER POLLING ===\\n');\n",
-    "    await debugChangesAPI();\n",
-    "}, 10000);"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "39d29701",
-   "metadata": {},
-   "source": [
-    "## 🚨 POSSIBILI CULPRIT IDENTIFICATI\n",
-    "\n",
-    "### Problema 1: _changes feed con `include_docs` potrebbe essere lento\n",
-    "\n",
-    "Nel tuo `adapter.ts`, quando `opts.include_docs` è vero, il metodo `_changes` deve:\n",
-    "- Scaricare il CORPO di ogni documento (lento)\n",
-    "- Questo blocca la replica\n",
-    "\n",
-    "**Diagnosi:**  \n",
-    "Controlla la console del browser. Se vedi molti `fetchFile` calls per ogni change, questo è il collo di bottiglia.\n",
-    "\n",
-    "### Problema 2: Change detection non rispetta il `since` parameter\n",
-    "\n",
-    "La replica PouchDB invia `since: lastSeq` per ricevere solo i cambiamenti NUOVI.  \n",
-    "Se `_changes` non filtra correttamente, la replica non rileva i nuovi documenti.\n",
-    "\n",
-    "### Problema 3: Live listener potrebbe non essere chiamato\n",
-    "\n",
-    "Nel `DriveHandler`, il polling rileva modifiche a `_meta.json`, ma:\n",
-    "- Il polling ha un delay di 5 secondi\n",
-    "- La replicazione potrebbe timeout prima di ricevere notifiche"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "de439ea3",
-   "metadata": {},
-   "source": [
-    "## 4️⃣ Section: Troubleshooting - Conflitti di Revisione\n",
-    "\n",
-    "### Verifica validazione revisioni"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "08da678c",
-   "metadata": {
-    "vscode": {
-     "languageId": "javascript"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "// Verifica i conflitti di revisione durante la replica\n",
-    "async function checkReplicationConflicts() {\n",
-    "    console.log('\\n=== CHECKING REPLICATION CONFLICTS ===\\n');\n",
-    "    \n",
-    "    // Leggi lo stesso documento da entrambi i database\n",
-    "    const docId = 'Notebook-0';\n",
-    "    \n",
-    "    try {\n",
-    "        const localDoc = await localDB.get(docId);\n",
-    "        console.log('Local Doc:', { _id: localDoc._id, _rev: localDoc._rev });\n",
-    "    } catch (e) {\n",
-    "        console.warn('Local doc not found');\n",
-    "    }\n",
-    "    \n",
-    "    try {\n",
-    "        const remoteDoc = await googleDriveDB.get(docId);\n",
-    "        console.log('Remote Doc:', { _id: remoteDoc._id, _rev: remoteDoc._rev });\n",
-    "    } catch (e) {\n",
-    "        console.warn('Remote doc not found');\n",
-    "    }\n",
-    "    \n",
-    "    // 🔍 Verifica _conflicts (documenti con conflitti di merge)\n",
-    "    try {\n",
-    "        const allDocs = await localDB.allDocs({ conflicts: true });\n",
-    "        const conflictedDocs = allDocs.rows.filter(r => r.value.conflicts && r.value.conflicts.length > 0);\n",
-    "        if (conflictedDocs.length > 0) {\n",
-    "            console.warn('⚠️  Found documents with conflicts:', conflictedDocs);\n",
-    "        } else {\n",
-    "            console.log('✅ No conflicts found in local DB');\n",
-    "        }\n",
-    "    } catch (e) {\n",
-    "        console.error('Error checking conflicts:', e);\n",
-    "    }\n",
-    "}\n",
-    "\n",
-    "// Esegui il check dopo 30 secondi\n",
-    "setTimeout(async () => {\n",
-    "    await checkReplicationConflicts();\n",
-    "}, 30000);"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "52a770f6",
-   "metadata": {},
-   "source": [
-    "## 5️⃣ Section: Validazione - Test della Replica Bidirezionale\n",
-    "\n",
-    "### Test Manuale: Crea un documento su Google Drive e verifica la sincronizzazione"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "0f47da2f",
-   "metadata": {
-    "vscode": {
-     "languageId": "javascript"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "// 🧪 Test Completo della Replica Bidirezionale\n",
-    "\n",
-    "async function runFullReplicationTest() {\n",
-    "    console.log('\\n=== FULL REPLICATION TEST ===\\n');\n",
-    "    \n",
-    "    // Step 1: Leggi lo stato iniziale\n",
-    "    const localInfoBefore = await localDB.info();\n",
-    "    const googleDriveInfoBefore = await googleDriveDB.info();\n",
-    "    \n",
-    "    console.log('Initial State:');\n",
-    "    console.log('  Local:', { doc_count: localInfoBefore.doc_count, seq: localInfoBefore.update_seq });\n",
-    "    console.log('  Google Drive:', { doc_count: googleDriveInfoBefore.doc_count, seq: googleDriveInfoBefore.update_seq });\n",
-    "    \n",
-    "    // Step 2: Crea un nuovo documento SU GOOGLE DRIVE\n",
-    "    const testDocId = `test-sync-${Date.now()}`;\n",
-    "    const testDoc = {\n",
-    "        _id: testDocId,\n",
-    "        title: 'Test Document for Replication',\n",
-    "        createdAt: new Date().toISOString(),\n",
-    "        source: 'google-drive-db'\n",
-    "    };\n",
-    "    \n",
-    "    try {\n",
-    "        const saveResult = await googleDriveDB.put(testDoc);\n",
-    "        console.log('\\n✅ Created document on Google Drive:', { id: saveResult.id, rev: saveResult.rev });\n",
-    "    } catch (err) {\n",
-    "        console.error('❌ Failed to create document on Google Drive:', err);\n",
-    "        return;\n",
-    "    }\n",
-    "    \n",
-    "    // Step 3: Attendi il polling + replicazione (20 secondi dovrebbe essere sufficiente)\n",
-    "    console.log('\\n⏳ Waiting for polling and replication (20 seconds)...');\n",
-    "    \n",
-    "    await new Promise(resolve => setTimeout(resolve, 20000));\n",
-    "    \n",
-    "    // Step 4: Verifica se il documento è arrivato al Local DB\n",
-    "    try {\n",
-    "        const docOnLocal = await localDB.get(testDocId);\n",
-    "        console.log('\\n✅✅✅ SUCCESS! Document replicated to local DB:', {\n",
-    "            id: docOnLocal._id,\n",
-    "            rev: docOnLocal._rev,\n",
-    "            title: docOnLocal.title\n",
-    "        });\n",
-    "    } catch (err) {\n",
-    "        console.error('\\n❌ FAILED! Document NOT found on local DB:', err.message);\n",
-    "        \n",
-    "        // Diagnosi aggiuntiva\n",
-    "        console.log('\\n🔍 DIAGNOSTIC INFO:');\n",
-    "        const localInfoAfter = await localDB.info();\n",
-    "        const googleDriveInfoAfter = await googleDriveDB.info();\n",
-    "        \n",
-    "        console.log('After Test:');\n",
-    "        console.log('  Local:', { doc_count: localInfoAfter.doc_count, seq: localInfoAfter.update_seq });\n",
-    "        console.log('  Google Drive:', { doc_count: googleDriveInfoAfter.doc_count, seq: googleDriveInfoAfter.update_seq });\n",
-    "        \n",
-    "        // Verifica che il doc sia effettivamente su Google Drive\n",
-    "        try {\n",
-    "            const verifyDoc = await googleDriveDB.get(testDocId);\n",
-    "            console.log('✅ Document IS on Google Drive:', {\n",
-    "                id: verifyDoc._id,\n",
-    "                rev: verifyDoc._rev\n",
-    "            });\n",
-    "            console.log('❌ BUT NOT replicated to local. Issue: REPLICATION FROM REMOTE NOT WORKING');\n",
-    "        } catch (e) {\n",
-    "            console.error('❌ Document not even on Google Drive. Save failed?');\n",
-    "        }\n",
-    "    }\n",
-    "}\n",
-    "\n",
-    "// Esegui il test\n",
-    "await runFullReplicationTest();"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "051a4d4b",
-   "metadata": {},
-   "source": [
-    "---\n",
-    "\n",
-    "## 🔧 SOLUZIONI CONSIGLIATE\n",
-    "\n",
-    "Basandoti sui risultati del test sopra, ecco i passaggi per risolvere il problema:\n",
-    "\n",
-    "### Se il test fallisce (documento non replica from remote):\n",
-    "\n",
-    "**Soluzione 1: Aumenta il pollingIntervalMs**\n",
-    "```javascript\n",
-    "pollingIntervalMs: 2000  // Invece di 5000 - controlla più frequentemente\n",
-    "```\n",
-    "\n",
-    "**Soluzione 2: Riduci il timeout di replicazione**\n",
-    "```javascript\n",
-    "const repFrom = localDB.replicate.from(googleDriveDB, { \n",
-    "    live: true, \n",
-    "    retry: true,\n",
-    "    timeout: 15000  // Aumenta timeout da default 30s\n",
-    "});\n",
-    "```\n",
-    "\n",
-    "**Soluzione 3: Aggiungi log nel adapter._changes in adapter.ts**\n",
-    "\n",
-    "Modifica `src/adapter.ts` linea ~428 per aggiungere debug:\n",
-    "```typescript\n",
-    "api._changes = function (opts: any): { cancel: () => void } {\n",
-    "    console.log('[_changes] Called with opts:', {\n",
-    "        since: opts.since,\n",
-    "        limit: opts.limit,\n",
-    "        live: opts.live,\n",
-    "        include_docs: !!opts.include_docs\n",
-    "    });\n",
-    "    // ...\n",
-    "```\n",
-    "\n",
-    "**Soluzione 4: Verifica che il live listener sia correttamente configurato**\n",
-    "\n",
-    "Nel `DriveHandler.load()`, assicurati che il polling chiami `notifyListeners()` ogni volta che rileva cambiamenti:\n",
-    "```typescript\n",
-    "if (metaFile.modifiedTime !== this.metaModifiedTime) {\n",
-    "    this.log('Polling detected change!', metaFile.modifiedTime);\n",
-    "    await this.load();\n",
-    "    this.notifyListeners();  // <-- DEVE ESSERE CHIAMATO\n",
-    "}\n",
-    "```"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

package/docs/DOCUMENTATION.md

@@ -1,115 +0,0 @@
-# Architecture & Design Documentation
-
-## 1. Core Principles
-The `pouchdb-adapter-googledrive` implementation is built on three core pillars to ensure data integrity and performance on a file-based remote storage system.
-
-### A. Append-Only Log (Storage)
-Instead of modifying a single database file (which is prone to conflicts), we use an **Append-Only** strategy.
-- **Changes**: Every write operation (or batch of writes) creates a **new, immutable file** (e.g., `changes-{seq}-{uuid}.ndjson`).
-- **Snapshots**: Periodically, the log is compacted into a `snapshot` file.
-- **Benefit**: Historical data is preserved until compaction, and file-write conflicts are minimized.
-
-### B. Optimistic Concurrency Control (OCC)
-To prevent race conditions (two clients writing simultaneously), we use **ETag-based locking** on a single entry point: `_meta.json`.
-- **The Lock**: `_meta.json` holds the current Sequence Number and the list of active log files.
-- **The Protocol**:
-    1. Reader fetches `_meta.json` and its `ETag`.
-    2. Writer prepares a new change file and uploads it (orphaned initially).
-    3. Writer attempts to update `_meta.json` with the new file reference, sending `If-Match: <Old-ETag>`.
-    4. **Success**: The change is now officially part of the DB.
-    5. **Failure (412/409)**: Another client updated the DB. The writer deletes its orphaned file, pulls the new state, and retries the logical operation.
-
-### C. Remote-First "Lazy" Loading (Memory Optimization)
-To support large databases without exhausting client memory, we separate **Metadata** from **Content**.
-
-#### Storage Structure
-- `_meta.json`: Root pointer. Small.
-- `snapshot-index.json`: A map of `{ docId: { rev, filePointer } }`. Medium size (~100 bytes/doc). Loaded at startup.
-- `snapshot-data.json`: The actual document bodies. Large. **Never fully loaded.**
-- `changes-*.ndjson`: Recent updates.
-
-#### Client Startup Sequence
-1.  **Fetch Meta**: Download `_meta.json` and get the `snapshotIndexId`.
-2.  **Fetch Index**: Download `snapshot-index.json`. This builds the "Revision Tree" in memory.
-3.  **Replay Logs**: Download and parse only the small `changes-*.ndjson` files created since the snapshot to update the in-memory Index.
-4.  **Ready**: The client is now ready to query keys. No document content has been downloaded yet.
-
-#### On-Demand Usage
-- **`db.get(id)`**: 
-    1. Look up `id` in the **Memory Index** to find the `filePointer`.
-    2. Check **LRU Cache**.
-    3. If missing, fetch the specific file/range from Google Drive.
-- **`db.allDocs({ keys: [...] })`**: Efficiently looks up pointers and fetches only requested docs.
-
-## 2. Technical Patterns
-
-### Atomic Compaction
-Compaction is a critical maintenance task that merges the `snapshot-data` with recent `changes` to create a new baseline.
-- **Safe**: Limits memory usage by streaming/batching.
-- **Atomic**: Uploads the new snapshot as a new file. Swaps the pointer in `_meta.json` using OCC.
-- **Zero-Downtime**: Clients can continue reading/writing to the old logs while compaction runs. Writes that happen *during* compaction are detected via the ETag check, causing the compaction to abort/retry safeley.
-
-### Conflict Handling
-- **PouchDB Level**: Standard CouchDB revision conflicts (409) are preserved. A "winner" is chosen deterministically, but conflicting revisions are kept in the tree (requires `snapshot-index` to store the full revision tree, not just the winner).
-- **Adapter Level**: Drive API 409s handling (retry logic) ensures the transport layer is reliable.
-
-## 3. Testing with Local Express Server
-
-The adapter includes a built-in test mode that emulates the Google Drive API using a local Express server. This allows for full integration testing without needing real Google Cloud credentials or network calls.
-
-### Configuration
-To enable the test emulator:
-
-```typescript
-const db = new PouchDB('testdb', {
-  adapter: 'googledrive',
-  testMode: true,
-  // testServerUrl: 'http://localhost:3000' // Optional, defaults to localhost:3000
-});
-```
-
-### Test Server
-The `TestServer` class (exported in `test-src/server.ts`) provides:
-- In-memory metadata storage
-- Local file system storage for content (defaults to `.test-drive-root` directory)
-- Emulation of `files.list`, `files.get`, `files.create` (multipart), `files.update`, and `files.delete`.
-
-### Example Usage
-```typescript
-import { TestServer } from './tests-src/server';
-
-const server = new TestServer(3000);
-await server.start();
-
-// Run PouchDB operations...
-
-
-## 4. Production Testing (Real Google Drive API)
-
-To verify the adapter against the actual Google Drive service, you can run the production test suite. This requires a valid Google OAuth2 Access Token.
-
-### A. Environment Setup
-Create a `.env` file in the project root (see `.env.example`):
-```env
-GOOGLE_ACCESS_TOKEN=your_temporary_access_token_here
-```
-
-### B. Obtaining a Token via OAuth1/2 Playground
-The easiest way to get a temporary token for manual testing:
-1.  Go to the [Google OAuth2 Playground](https://developers.google.com/oauthplayground/).
-2.  **Step 1 (Select & authorize APIs)**: 
-    *   Find "Drive API v3" in the list.
-    *   Select the scope: `https://www.googleapis.com/auth/drive.file` (this is the recommended scope as it only allows the app to see files it creates).
-    *   Click **Authorize APIs** and sign in with your Google account.
-3.  **Step 2 (Exchange authorization code for tokens)**:
-    *   Click **Exchange authorization code for tokens**.
-4.  **Step 3 (Configure request to API)**:
-    *   Copy the **Access Token** string.
-    *   Paste it into your `.env` file as `GOOGLE_ACCESS_TOKEN`.
-
-### C. Running the Tests
-Execute the following command to run the tests in production mode:
-```bash
-npm run test:prod
-```
-This command sets `TEST_ENV=production`, which tells the test runner to skip the local Express emulator and use the real Google Drive endpoints with your provided token.

package/docs/PROMISE_SUPPORT.md

@@ -1,75 +0,0 @@
-# Promise Support Documentation
-
-The adapter now fully supports all three PouchDB call patterns:
-
-## 1. Callback Pattern
-```javascript
-db.get('mydoc', function(err, doc) {
-  if (err) { return console.log(err); }
-  // handle doc
-});
-```
-
-## 2. Promise Pattern
-```javascript
-db.get('mydoc').then(function (doc) {
-  // handle doc
-}).catch(function (err) {
-  console.log(err);
-});
-```
-
-## 3. Async/Await Pattern
-```javascript
-try {
-  const doc = await db.get('mydoc');
-  // handle doc
-} catch (err) {
-  console.log(err);
-}
-```
-
-## Methods Updated
-
-The following adapter methods now support all three patterns:
-
-### Query Methods
-- `_get()` / `get()` - Get a single document
-- `_allDocs()` / `allDocs()` - Get all documents
-- `_getLocal()` - Get a local document
-- `_getRevisionTree()` - Get revision tree (internal)
-
-### Mutation Methods
-- `_bulkDocs()` / `bulkDocs()` - Bulk document operations
-- `_bulkGet()` / `bulkGet()` - Bulk get operation
-- `_putLocal()` - Put a local document
-- `_removeLocal()` - Remove a local document
-
-### Maintenance Methods
-- `_compact()` - Compact the database
-
-## Implementation Details
-
-Each method now:
-1. **Always returns a Promise** (even when a callback is provided)
-2. **Calls the callback if provided** for backward compatibility
-3. **Properly propagates errors** through both callbacks and rejections
-4. **Handles callback overloading** (when `opts` is actually the callback)
-
-This allows PouchDB and its replication engine to use the adapter with promises and async/await, fixing the error:
-```
-TypeError: can't access property "then", db.get(...) is undefined
-```
-
-## Migration Path
-
-Your existing callback-based code continues to work:
-```javascript
-// Old callback pattern - still works!
-db.get('doc1', (err, doc) => {
-  if (err) console.error(err);
-  else console.log(doc);
-});
-```
-
-You can gradually migrate to promises/async-await as needed.