@docstack/pouchdb-adapter-googledrive 0.0.6 → 0.0.8

package/README.md

@@ -1,72 +1,72 @@
-# PouchDB Adapter for Google Drive
-
-A persistent, serverless PouchDB adapter that uses Google Drive as a backend storage. Designed for high concurrency, large datasets (via lazy loading), and offline resilience.
-
-## Features
-
-- **🚀 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.
-- **📦 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
-
-```bash
-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';
-
-// 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'
-});
-
-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:
-- **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
-
-CC-BY-SA-4.0
+# PouchDB Adapter for Google Drive
+
+A persistent, serverless PouchDB adapter that uses Google Drive as a backend storage. Designed for high concurrency, large datasets (via lazy loading), and offline resilience.
+
+## Features
+
+- **🚀 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.
+- **📦 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
+
+```bash
+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';
+
+// 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'
+});
+
+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:
+- **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
+
+CC-BY-SA-4.0

package/jest.config.js

@@ -1,8 +1,8 @@
-module.exports = {
-    preset: 'ts-jest',
-    testEnvironment: 'node',
-    testMatch: ['**/tests/**/*.test.ts'],
-    transform: {
-        '^.+\\.ts$': 'ts-jest',
-    },
-};
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/tests/**/*.test.ts'],
+    transform: {
+        '^.+\\.ts$': 'ts-jest',
+    },
+};

package/package.json

@@ -1,41 +1,48 @@
-{
-  "name": "@docstack/pouchdb-adapter-googledrive",
-  "version": "0.0.6",
-  "description": "PouchDB adapter for Google Drive",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "jest"
-  },
-  "keywords": [
-    "pouchdb",
-    "adapter",
-    "google-drive"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/onyx-ac/docstack-pouchdb-adapter-gdrive.git"
-  },
-  "author": "Onyx <hello@onyx.ac> (https://onyx.ac)",
-  "license": "CC-BY-SA-4.0",
-  "bugs": {
-    "url": "https://github.com/onyx-ac/docstack-pouchdb-adapter-gdrive/issues"
-  },
-  "homepage": "https://onyx.ac/docstack",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "pouchdb-core": "^7.3.1"
-  },
-  "devDependencies": {
-    "@types/jest": "^30.0.0",
-    "@types/node": "^20.0.0",
-    "@types/pouchdb-core": "^7.0.15",
-    "dotenv": "^17.2.3",
-    "jest": "^30.2.0",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.0.0"
-  }
+{
+  "name": "@docstack/pouchdb-adapter-googledrive",
+  "version": "0.0.8",
+  "description": "PouchDB adapter for Google Drive",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:prod": "TEST_ENV=production jest"
+  },
+  "keywords": [
+    "pouchdb",
+    "adapter",
+    "google-drive"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onyx-ac/docstack-pouchdb-adapter-gdrive.git"
+  },
+  "author": "Onyx <hello@onyx.ac> (https://onyx.ac)",
+  "license": "CC-BY-SA-4.0",
+  "bugs": {
+    "url": "https://github.com/onyx-ac/docstack-pouchdb-adapter-gdrive/issues"
+  },
+  "homepage": "https://onyx.ac/docstack",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "pouchdb-core": "^7.3.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "@types/pouchdb-adapter-memory": "^6.1.6",
+    "@types/pouchdb-core": "^7.0.15",
+    "@types/pouchdb-replication": "^6.4.7",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "jest": "^30.2.0",
+    "pouchdb-adapter-memory": "^9.0.0",
+    "pouchdb-replication": "^9.0.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  }
 }

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/lib/adapter.d.ts

@@ -1,17 +0,0 @@
-import { GoogleDriveAdapterOptions } from './types';
-/** Combined options type for PouchDB adapter */
-interface AdapterOptions extends GoogleDriveAdapterOptions {
-    name: string;
-}
-/** Callback type for adapter initialization */
-type AdapterCallback = (err: Error | null, api?: any) => void;
-/**
- * GoogleDriveAdapter - PouchDB adapter for Google Drive storage.
- * Updated for Lazy Loading (Async Access).
- */
-export declare function GoogleDriveAdapter(PouchDB: any): {
-    (this: any, opts: AdapterOptions, callback: AdapterCallback): void;
-    valid(): boolean;
-    use_prefix: boolean;
-};
-export default GoogleDriveAdapter;