@docstack/pouchdb-adapter-googledrive 0.0.2 → 0.0.4

package/README.md

@@ -6,10 +6,13 @@ A persistent, serverless PouchDB adapter that uses Google Drive as a backend sto
 
 - **🚀 Append-Only Log**: Uses an efficient append-only log pattern for fast, conflict-free writes.
 - **⚡ Lazy Loading**: Optimizes memory and bandwidth by loading only the **Index** into memory. Document bodies are fetched on-demand.
-- **🛡️ Optimistic Concurrency Control**: Uses ETag-based locking on metadata to prevent race conditions and data loss during simultaneous updates.
-- **🔄 Replication Ready**: Fully automated support for PouchDB's `sync` and `replicate` protocols (bilateral sync).
-- **📦 Auto-Compaction**: Automatically merges logs into snapshots to keep performance high.
-- **💾 Offline/Resilient**: Retry logic with exponential backoff handles network instability and "thundering herd" scenarios.
+- **🛡️ Optimistic Concurrency Control**: Uses ETag-based locking on metadata to prevent race conditions.
+- **📦 Auto-Compaction**: Automatically merges logs for performance.
+- **🌍 Universal**: Works natively in Node.js 18+, Browsers, and Edge environments (no `googleapis` dependency).
+
+## Requirements
+
+- **Node.js 18+** (for global `fetch` support) or a modern browser.
 
 ## Installation
 
@@ -19,74 +22,50 @@ npm install @docstack/pouchdb-adapter-googledrive
 
 ## Usage
 
+The adapter is initialized as a plugin with your Google Drive access token.
+
 ```typescript
 import PouchDB from 'pouchdb-core';
 import GoogleDriveAdapter from '@docstack/pouchdb-adapter-googledrive';
-import { google } from 'googleapis';
-
-// Register the adapter
-PouchDB.plugin(GoogleDriveAdapter);
-
-// Setup Google Drive Client (Authenticated)
-const oauth2Client = new google.auth.OAuth2(
-  YOUR_CLIENT_ID,
-  YOUR_CLIENT_SECRET,
-  YOUR_REDIRECT_URL
-);
-oauth2Client.setCredentials({ access_token: '...' });
-
-const drive = google.drive({ version: 'v3', auth: oauth2Client });
-
-// Create Database
-const db = new PouchDB('my-drive-db', {
-  adapter: 'googledrive',
-  drive: drive,              // valid googleapis Drive instance
-  folderId: '...',           // Optional: Storage Folder ID (recommended)
-  folderName: 'my-db',       // Optional: Folder name (created if not exists)
-  pollingIntervalMs: 2000,   // Optional: Check for remote changes
-  compactionThreshold: 50,   // Optional: Entries before auto-compaction
-  cacheSize: 1000            // Optional: Number of document bodies to keep in LRU cache
+
+// 1. Initialize the Adapter Plugin Factory
+const adapterPlugin = GoogleDriveAdapter({
+  accessToken: 'YOUR_GOOGLE_ACCESS_TOKEN',
+  folderName: 'my-app-db-folder', // Root folder in Drive
+  pollingIntervalMs: 2000         // Optional: check for remote changes
+});
+
+// 2. Register Plugin
+PouchDB.plugin(adapterPlugin);
+
+// 3. Create Database
+const db = new PouchDB('user_db', {
+  adapter: 'googledrive'
 });
 
-// Use standard PouchDB API
-await db.put({ _id: 'doc1', title: 'Hello Drive!' });
-const doc = await db.get('doc1');
+await db.post({ title: 'Hello World' });
+```
+
+### Dynamic Tokens
+
+If your token expires, you can provide an async function that returns a valid token:
+
+```typescript
+const adapterPlugin = GoogleDriveAdapter({
+  accessToken: async () => {
+    const session = await getMySession();
+    return session.accessToken;
+  },
+  folderName: 'my-app-db'
+});
 ```
 
 ## Architecture
 
-The adapter implements a **"Remote-First"** architecture designed for scale:
-
-### 1. Storage Structure
-Inside your Google Drive folder, you will see:
-- `_meta.json`: The "Lock File". Tracks the sequence number and active log pointers.
-- `snapshot-index.json`: A lightweight map of `DocID -> { Revision, FilePointer }`. Loaded at startup.
-- `snapshot-data.json`: Large payload files containing document bodies. **Not loaded** until requested.
-- `changes-{seq}-{uuid}.ndjson`: Immutable append-only logs for recent updates.
-
-### 2. Lazy Loading & Caching
-- **Startup**: The client downloads only `_meta.json` and `snapshot-index.json` (~MBs even for large DBs).
-- **Access**: `db.get(id)` checks a local **LRU Cache**. If missing, it fetches the specific file containing that document from Drive.
-- **Sync**: `db.changes()` iterates the local index, ensuring fast replication without downloading full content.
-
-### 3. Concurrency
-- **Writes**: Every write creates a new unique `changes-*.ndjson` file.
-- **Commit**: The adapter attempts to update `_meta.json` with an ETag check (`If-Match`).
-- **Conflict**: If `_meta.json` was changed by another client, the write retries automatically after re-syncing the index.
-
-## Testing
-
-To run the tests, you need to provide Google Drive API credentials.
-
-1. Copy `.env.example` to `.env`:
-   ```bash
-   cp .env.example .env
-   ```
-2. Fill in your Google Cloud credentials in `.env`.
-3. Run the tests:
-   ```bash
-   npm test
-   ```
+The adapter implements a **"Remote-First"** architecture:
+- **Lazy Loading**: `db.get(id)` fetches data on-demand from Drive.
+- **Caching**: Changes are indexed locally but bodies are cached in an LRU cache.
+- **Resilience**: Writes use optimistic locking to handle multi-client concurrency safer.
 
 ## License
 

package/lib/client.d.ts

@@ -0,0 +1,29 @@
+export interface DriveFile {
+    id: string;
+    name: string;
+    mimeType: string;
+    parents?: string[];
+    etag?: string;
+}
+export interface DriveClientOptions {
+    accessToken: string | (() => Promise<string>);
+}
+export declare class GoogleDriveClient {
+    private options;
+    constructor(options: DriveClientOptions);
+    private getToken;
+    private fetch;
+    listFiles(q: string): Promise<DriveFile[]>;
+    getFile(fileId: string): Promise<any>;
+    getFileMetadata(fileId: string): Promise<DriveFile>;
+    createFile(name: string, parents: string[] | undefined, mimeType: string, content: string): Promise<{
+        id: string;
+        etag: string;
+    }>;
+    updateFile(fileId: string, content: string, expectedEtag?: string): Promise<{
+        id: string;
+        etag: string;
+    }>;
+    deleteFile(fileId: string): Promise<void>;
+    private buildMultipart;
+}

package/lib/client.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleDriveClient = void 0;
+const BASE_URL = 'https://www.googleapis.com/drive/v3/files';
+const UPLOAD_URL = 'https://www.googleapis.com/upload/drive/v3/files';
+class GoogleDriveClient {
+    constructor(options) {
+        this.options = options;
+    }
+    async getToken() {
+        if (typeof this.options.accessToken === 'function') {
+            return await this.options.accessToken();
+        }
+        return this.options.accessToken;
+    }
+    async fetch(url, init) {
+        const token = await this.getToken();
+        const headers = new Headers(init.headers);
+        headers.set('Authorization', `Bearer ${token}`);
+        const res = await fetch(url, { ...init, headers });
+        if (!res.ok) {
+            // Basic error handling
+            const text = await res.text();
+            let errorMsg = `Drive API Error: ${res.status} ${res.statusText}`;
+            try {
+                const json = JSON.parse(text);
+                if (json.error && json.error.message) {
+                    errorMsg += ` - ${json.error.message}`;
+                }
+            }
+            catch { }
+            const err = new Error(errorMsg);
+            err.status = res.status;
+            throw err;
+        }
+        return res;
+    }
+    async listFiles(q) {
+        const params = new URLSearchParams({
+            q,
+            fields: 'files(id, name, mimeType, parents, etag)',
+            spaces: 'drive',
+            pageSize: '1000' // Ensure we get enough
+        });
+        const res = await this.fetch(`${BASE_URL}?${params.toString()}`, { method: 'GET' });
+        const data = await res.json();
+        return data.files || [];
+    }
+    async getFile(fileId) {
+        // Try getting media
+        try {
+            const params = new URLSearchParams({ alt: 'media' });
+            const res = await this.fetch(`${BASE_URL}/${fileId}?${params.toString()}`, { method: 'GET' });
+            // Standard fetch handles JSON/Text transparency? 
+            // We expect JSON mostly, but sometimes we might want text.
+            // PouchDB adapter flow: downloadJson, downloadNdjson
+            // Let's rely on content-type or caller expectation?
+            // The usage in `drive.ts` expects parsed JSON/NDJSON lines.
+            // Let's return the raw Text or JSON based on Content-Type?
+            const contentType = res.headers.get('content-type');
+            if (contentType && contentType.includes('application/json')) {
+                return await res.json();
+            }
+            return await res.text();
+        }
+        catch (e) {
+            throw e;
+        }
+    }
+    // Single metadata get (for etag check)
+    async getFileMetadata(fileId) {
+        const params = new URLSearchParams({ fields: 'id, name, mimeType, parents, etag' });
+        const res = await this.fetch(`${BASE_URL}/${fileId}?${params.toString()}`, { method: 'GET' });
+        return await res.json();
+    }
+    async createFile(name, parents, mimeType, content) {
+        const metadata = {
+            name,
+            mimeType,
+            parents
+        };
+        const multipartBody = this.buildMultipart(metadata, content, mimeType);
+        const res = await this.fetch(`${UPLOAD_URL}?uploadType=multipart&fields=id,etag`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': `multipart/related; boundary=${multipartBody.boundary}`
+            },
+            body: multipartBody.body
+        });
+        return await res.json();
+    }
+    async updateFile(fileId, content, expectedEtag) {
+        // Update content (media) usually, but sometimes meta?
+        // In our usage (saveMeta), we update body.
+        const res = await this.fetch(`${UPLOAD_URL}/${fileId}?uploadType=media&fields=id,etag`, {
+            method: 'PATCH',
+            headers: expectedEtag ? { 'If-Match': expectedEtag, 'Content-Type': 'application/json' } : { 'Content-Type': 'application/json' },
+            body: content
+        });
+        return await res.json();
+    }
+    async deleteFile(fileId) {
+        await this.fetch(`${BASE_URL}/${fileId}`, { method: 'DELETE' });
+    }
+    buildMultipart(metadata, content, contentType) {
+        const boundary = '-------' + Math.random().toString(36).substring(2);
+        const delimiter = `\r\n--${boundary}\r\n`;
+        const closeDelimiter = `\r\n--${boundary}--`;
+        const body = delimiter +
+            'Content-Type: application/json\r\n\r\n' +
+            JSON.stringify(metadata) +
+            delimiter +
+            `Content-Type: ${contentType}\r\n\r\n` +
+            content +
+            closeDelimiter;
+        return { body, boundary };
+    }
+}
+exports.GoogleDriveClient = GoogleDriveClient;

package/lib/drive.d.ts

@@ -10,7 +10,7 @@ import { GoogleDriveAdapterOptions, ChangeEntry, IndexEntry } from './types';
  *   └── changes-*.ndjson     # Append logs
  */
 export declare class DriveHandler {
-    private drive;
+    private client;
     private folderId;
     private folderName;
     private parents;

package/lib/drive.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DriveHandler = void 0;
 const cache_1 = require("./cache");
+const client_1 = require("./client");
 const DEFAULT_COMPACTION_THRESHOLD = 100; // entries
 const DEFAULT_SIZE_THRESHOLD = 1024 * 1024; // 1MB
 const DEFAULT_CACHE_SIZE = 1000; // Number of docs
@@ -32,7 +33,7 @@ class DriveHandler {
         this.currentLogSizeEstimate = 0;
         this.listeners = [];
         this.pollingInterval = null;
-        this.drive = options.drive;
+        this.client = new client_1.GoogleDriveClient(options);
         this.folderId = options.folderId || null;
         this.folderName = options.folderName || dbName;
         this.parents = options.parents || [];
@@ -267,7 +268,7 @@ class DriveHandler {
                 return await this.tryAppendChanges(changes);
             }
             catch (err) {
-                if (err.code === 412 || err.code === 409) {
+                if (err.status === 412 || err.status === 409) {
                     // Reload and RETRY
                     await this.load();
                     // Check conflicts against Index (Metadata sufficient)
@@ -359,16 +360,8 @@ class DriveHandler {
         });
         // 2. Upload Data File
         const dataContent = JSON.stringify(snapshotData);
-        const dataRes = await this.drive.files.create({
-            requestBody: {
-                name: `snapshot-data-${Date.now()}.json`,
-                parents: [this.folderId],
-                mimeType: 'application/json'
-            },
-            media: { mimeType: 'application/json', body: dataContent },
-            fields: 'id'
-        });
-        const dataFileId = dataRes.data.id;
+        const dataRes = await this.client.createFile(`snapshot-data-${Date.now()}.json`, [this.folderId], 'application/json', dataContent);
+        const dataFileId = dataRes.id;
         // 3. Create Index pointing to this Data File
         const newIndexEntries = {};
         for (const id of Object.keys(snapshotData.docs)) {
@@ -384,16 +377,8 @@ class DriveHandler {
             createdAt: Date.now()
         };
         const indexContent = JSON.stringify(snapshotIndex);
-        const indexRes = await this.drive.files.create({
-            requestBody: {
-                name: `snapshot-index-${Date.now()}.json`,
-                parents: [this.folderId],
-                mimeType: 'application/json'
-            },
-            media: { mimeType: 'application/json', body: indexContent },
-            fields: 'id'
-        });
-        const newIndexId = indexRes.data.id;
+        const indexRes = await this.client.createFile(`snapshot-index-${Date.now()}.json`, [this.folderId], 'application/json', indexContent);
+        const newIndexId = indexRes.id;
         // 4. Update Meta
         await this.atomicUpdateMeta((latest) => {
             const remainingLogs = latest.changeLogIds.filter(id => !oldLogIds.includes(id));
@@ -424,7 +409,7 @@ class DriveHandler {
                 return;
             }
             catch (err) {
-                if (err.code === 412 || err.code === 409) {
+                if (err.status === 412 || err.status === 409) {
                     attempt++;
                     await new Promise(r => setTimeout(r, Math.random() * 500 + 100));
                     continue;
@@ -436,44 +421,33 @@ class DriveHandler {
     // Reused helpers
     async findOrCreateFolder() {
         const q = `name = '${this.folderName}' and mimeType = 'application/vnd.google-apps.folder' and trashed = false`;
-        const res = await this.drive.files.list({ q, spaces: 'drive', fields: 'files(id)' });
-        if (res.data.files && res.data.files.length > 0)
-            return res.data.files[0].id;
-        const createRes = await this.drive.files.create({
-            requestBody: { name: this.folderName, mimeType: 'application/vnd.google-apps.folder', parents: this.parents.length ? this.parents : undefined },
-            fields: 'id'
-        });
-        return createRes.data.id;
+        const files = await this.client.listFiles(q);
+        if (files.length > 0)
+            return files[0].id;
+        const createRes = await this.client.createFile(this.folderName, this.parents.length ? this.parents : undefined, 'application/vnd.google-apps.folder', '');
+        return createRes.id;
     }
     async findFile(name) {
         const q = `name = '${name}' and '${this.folderId}' in parents and trashed = false`;
-        const res = await this.drive.files.list({ q, spaces: 'drive', fields: 'files(id, etag)' });
-        if (res.data.files && res.data.files.length > 0)
-            return { id: res.data.files[0].id, etag: res.data.files[0].etag };
+        const files = await this.client.listFiles(q);
+        if (files.length > 0)
+            return { id: files[0].id, etag: files[0].etag || '' };
         return null;
     }
     async downloadJson(fileId) {
-        const res = await this.drive.files.get({ fileId, alt: 'media' });
-        return res.data;
+        return await this.client.getFile(fileId);
     }
     async downloadFileAny(fileId) {
-        const res = await this.drive.files.get({ fileId, alt: 'media' });
-        if (typeof res.data === 'string') {
-            // NDJSON or JSON string
-            try {
-                return JSON.parse(res.data);
-            }
-            catch {
-                // NDJSON?
-                const lines = res.data.trim().split('\n').filter((l) => l);
-                return lines.map((line) => JSON.parse(line));
-            }
-        }
-        return res.data;
+        return await this.client.getFile(fileId);
     }
     async downloadNdjson(fileId) {
-        const res = await this.drive.files.get({ fileId, alt: 'media' });
-        const content = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
+        const data = await this.client.getFile(fileId);
+        // data will likely be a string if NDJSON is returned and getFile sees weird content-type
+        // Or if getFile auto-parsed standard "application/json" but NDJSON is just text.
+        // Google Drive might return application/json for everything if we aren't careful?
+        // Actually .ndjson is separate.
+        // Safest: Handle string or object.
+        const content = typeof data === 'string' ? data : JSON.stringify(data);
         const lines = content.trim().split('\n').filter((l) => l);
         return lines.map((line) => JSON.parse(line));
     }
@@ -481,33 +455,20 @@ class DriveHandler {
         const lines = changes.map(c => JSON.stringify(c)).join('\n') + '\n';
         const startSeq = changes[0].seq;
         const name = `changes-${startSeq}-${Math.random().toString(36).substring(7)}.ndjson`;
-        const res = await this.drive.files.create({
-            requestBody: { name, parents: [this.folderId], mimeType: 'application/x-ndjson' },
-            media: { mimeType: 'application/x-ndjson', body: lines },
-            fields: 'id'
-        });
+        const res = await this.client.createFile(name, [this.folderId], 'application/x-ndjson', lines);
         this.currentLogSizeEstimate += new Blob([lines]).size;
-        return res.data.id;
+        return res.id;
     }
     async saveMeta(meta, expectedEtag = null) {
         const content = JSON.stringify(meta);
         const metaFile = await this.findFile('_meta.json');
         if (metaFile) {
-            const res = await this.drive.files.update({
-                fileId: metaFile.id,
-                headers: expectedEtag ? { 'If-Match': expectedEtag } : undefined,
-                media: { mimeType: 'application/json', body: content },
-                fields: 'id, etag'
-            });
-            this.metaEtag = res.data.etag;
+            const res = await this.client.updateFile(metaFile.id, content, expectedEtag || undefined);
+            this.metaEtag = res.etag;
         }
         else {
-            const res = await this.drive.files.create({
-                requestBody: { name: '_meta.json', parents: [this.folderId], mimeType: 'application/json' },
-                media: { mimeType: 'application/json', body: content },
-                fields: 'id, etag'
-            });
-            this.metaEtag = res.data.etag;
+            const res = await this.client.createFile('_meta.json', [this.folderId], 'application/json', content);
+            this.metaEtag = res.etag;
         }
     }
     async countTotalChanges() {
@@ -521,12 +482,12 @@ class DriveHandler {
     async cleanupOldFiles(oldIndexId, oldLogIds) {
         if (oldIndexId)
             try {
-                await this.drive.files.delete({ fileId: oldIndexId });
+                await this.client.deleteFile(oldIndexId);
             }
             catch { }
         for (const id of oldLogIds)
             try {
-                await this.drive.files.delete({ fileId: id });
+                await this.client.deleteFile(id);
             }
             catch { }
     }
@@ -538,6 +499,7 @@ class DriveHandler {
                 const metaFile = await this.findFile('_meta.json');
                 if (!metaFile)
                     return;
+                // Etag check
                 if (metaFile.etag !== this.metaEtag) {
                     await this.load();
                     this.notifyListeners();
@@ -567,7 +529,7 @@ class DriveHandler {
     stopPolling() { if (this.pollingInterval)
         clearInterval(this.pollingInterval); }
     async deleteFolder() { if (this.folderId)
-        await this.drive.files.delete({ fileId: this.folderId }); }
+        await this.client.deleteFile(this.folderId); }
     getNextSeq() { return this.meta.seq + 1; }
 }
 exports.DriveHandler = DriveHandler;

package/lib/index.d.ts

@@ -1 +1,10 @@
-export default function (PouchDB: any): void;
+import { GoogleDriveAdapterOptions } from './types';
+export * from './types';
+/**
+ * Google Drive Adapter Plugin Factory
+ *
+ * Usage:
+ * const plugin = GoogleDriveAdapter({ drive: myDriveClient, ... });
+ * PouchDB.plugin(plugin);
+ */
+export default function GoogleDriveAdapter(config: GoogleDriveAdapterOptions): (PouchDB: any) => void;

package/lib/index.js

@@ -1,7 +1,55 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = default_1;
+exports.default = GoogleDriveAdapter;
 const adapter_1 = require("./adapter");
-function default_1(PouchDB) {
-    PouchDB.adapter('googledrive', (0, adapter_1.GoogleDriveAdapter)(PouchDB), true);
+// Export types
+__exportStar(require("./types"), exports);
+/**
+ * Google Drive Adapter Plugin Factory
+ *
+ * Usage:
+ * const plugin = GoogleDriveAdapter({ drive: myDriveClient, ... });
+ * PouchDB.plugin(plugin);
+ */
+function GoogleDriveAdapter(config) {
+    return function (PouchDB) {
+        // Get the base adapter constructor (scoped to this PouchDB instance)
+        const BaseAdapter = (0, adapter_1.GoogleDriveAdapter)(PouchDB);
+        // Create a wrapper constructor that injects the config
+        function ConfiguredAdapter(opts, callback) {
+            // Merge factory config with constructor options
+            // Constructor options take precedence (overrides)
+            const mergedOpts = Object.assign({}, config, opts);
+            // Call the base adapter
+            BaseAdapter.call(this, mergedOpts, callback);
+        }
+        // Copy static properties required by PouchDB
+        // @ts-ignore
+        ConfiguredAdapter.valid = BaseAdapter.valid;
+        // @ts-ignore
+        ConfiguredAdapter.use_prefix = BaseAdapter.use_prefix;
+        // Register the adapter manually
+        // We use PouchDB.adapters object directly to avoid using the .adapter() method
+        if (PouchDB.adapters) {
+            PouchDB.adapters['googledrive'] = ConfiguredAdapter;
+        }
+        else {
+            // Fallback/Warning if adapters object is somehow missing (should not happen in core)
+            console.warn('PouchDB.adapters not found, unable to register googledrive adapter');
+        }
+    };
 }

package/lib/types.d.ts

@@ -1,9 +1,6 @@
-/** Google Drive API client type */
-export type DriveClient = any;
+import { DriveClientOptions } from './client';
 /** Options for configuring the Google Drive adapter */
-export interface GoogleDriveAdapterOptions {
-    /** Configured Google Drive client (googleapis) */
-    drive: DriveClient;
+export interface GoogleDriveAdapterOptions extends DriveClientOptions {
     /** Specific folder ID to use as the DB root */
     folderId?: string;
     /** Folder name to search/create if no ID provided */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/pouchdb-adapter-googledrive",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "PouchDB adapter for Google Drive",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -23,8 +23,10 @@
     "url": "https://github.com/onyx-ac/docstack-pouchdb-adapter-gdrive/issues"
   },
   "homepage": "https://onyx.ac/docstack",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
-    "googleapis": "^126.0.0",
     "pouchdb-core": "^7.3.1"
   },
   "devDependencies": {

package/DOCUMENTATION.md

@@ -1,54 +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.

package/error.log

@@ -1,21 +0,0 @@
-FAIL tests/adapter.test.ts
-  ΓùÅ Test suite failed to run
-
-    tests/adapter.test.ts:51:13 - error TS2353: Object literal may only specify known properties, and 'drive' does not exist in type 'DatabaseConfiguration'.
-
-    51             drive: drive,
-                   ~~~~~
-    tests/adapter.test.ts:57:21 - error TS2339: Property 'backend_adapter' does not exist on type 'DatabaseInfo'.
-
-    57         expect(info.backend_adapter).toBe('googledrive');
-                           ~~~~~~~~~~~~~~~
-    tests/adapter.test.ts:65:24 - error TS2339: Property 'title' does not exist on type 'IdMeta & GetMeta'.
-
-    65         expect(fetched.title).toBe('Start Wars');
-                              ~~~~~
-
-Test Suites: 1 failed, 1 total
-Tests:       0 total
-Snapshots:   0 total
-Time:        14.401 s
-Ran all test suites matching tests/adapter.test.ts.