@docstack/pouchdb-adapter-googledrive 0.0.2 → 0.0.3

package/README.md

@@ -6,10 +6,8 @@ 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.
 
 ## Installation
 
@@ -19,74 +17,45 @@ npm install @docstack/pouchdb-adapter-googledrive
 
 ## Usage
 
+The adapter is initialized as a plugin with your Google Drive configuration.
+
 ```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
-);
+// 1. Setup Google Drive Client
+const oauth2Client = new google.auth.OAuth2(CLIENT_ID, SECRET, REDIRECT);
 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
+// 2. Initialize the Adapter Plugin with Config
+const adapterPlugin = GoogleDriveAdapter({
+  drive: drive,
+  folderName: 'my-app-db-folder', // Root folder
+  pollingIntervalMs: 2000
+});
+
+// 3. Register Plugin
+PouchDB.plugin(adapterPlugin);
+// Also needs replication plugin if using replicate()
+// PouchDB.plugin(require('pouchdb-replication'));
+
+// 4. Create Database
+// No need to pass 'drive' here anymore!
+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' });
 ```
 
 ## 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/pouchdb-adapter-googledrive",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "PouchDB adapter for Google Drive",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

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.