PouchDB HTTP Request Adapter

Common errors

• TypeError: Cannot read properties of undefined (reading 'auth')

  cause This error was fixed in version 4.1.0 and was related to how authentication options (`opts.auth`) were handled internally, particularly with XHR in `http-pouchdb`.
  fix Upgrade to `pouchdb-req-http-query` version 4.1.0 or newer. Ensure `opts.auth` is correctly structured with `username` and `password` properties if provided.

• EventEmitter memory leak detected. 11 listener's added. Use emitter.setMaxListeners() to increase limit

  cause An EventEmitter memory leak was reported and fixed in version 4.1.0, indicating that too many listeners were being attached without being properly cleaned up in previous versions.
  fix Upgrade to `pouchdb-req-http-query` version 4.1.0 or newer. If using older versions, manually ensure event listeners are removed or consider increasing `setMaxListeners` as a temporary workaround, though upgrading is strongly recommended.

• TypeError: Cannot read properties of undefined (reading 'body') or similar 'bulkDocs TypeError'

  cause A `bulkDocs TypeError` was addressed in version 4.1.0. This likely occurred when the internal `bulkDocs` operation received an unexpected or malformed request body.
  fix Upgrade to `pouchdb-req-http-query` version 4.1.0 or newer. Verify that the `body` property of your CouchDB request object (especially for `POST` or `PUT` methods) is a valid JSON serializable object, as PouchDB documents must be pure JSON.

Warnings

• breaking Version 4.0.0 introduced significant breaking changes due to its release as part of a complete monorepo restructure. While not detailed for this specific package, it implies potential API shifts and altered dependency management within the PouchDB ecosystem.
  Fix: Review the official PouchDB monorepo migration guides and `express-pouchdb` changelogs for specific adjustments required when upgrading from pre-4.0.0 versions.
• breaking Version 2.0.0 introduced breaking changes that corresponded to changes in `express-pouchdb` v2.0.0. Users upgrading from pre-2.0.0 versions should consult the `express-pouchdb` release notes for necessary adaptations.
  Fix: Refer to the `express-pouchdb` v2.0.0 release page for detailed breaking changes and migration steps.
• gotcha When interacting with remote CouchDB instances, `pouchdb-req-http-query` (and PouchDB in general) is subject to Cross-Origin Resource Sharing (CORS) policies. Without proper CORS configuration on the CouchDB server, requests will fail with 'No Access-Control-Allow-Origin header' errors.
  Fix: Enable CORS on your CouchDB/Cloudant server. Tools like `add-cors-to-couchdb` can simplify this, or configure it manually via `curl` or Futon.
• security Version 4.0.0 fixed a security issue (referenced as #290 in the changelog). Running older versions may expose applications to this vulnerability.
  Fix: Upgrade to `pouchdb-req-http-query` version 4.0.0 or newer to incorporate the security fix.

Install

• npm install pouchdb-req-http-query npm
• yarn add pouchdb-req-http-query yarn
• pnpm add pouchdb-req-http-query pnpm

Imports

• httpQuery
  wrong:

  const httpQuery = require('pouchdb-req-http-query');

  correct:

  import httpQuery from 'pouchdb-req-http-query';

  The package primarily exports a single function, likely as a default export, to perform the HTTP query. For ES Modules, use the default import syntax.

Quickstart

This quickstart demonstrates how to use `pouchdb-req-http-query` to perform CouchDB-style GET and POST requests against a local PouchDB instance, including fetching all documents and inserting a new one.

import PouchDB from 'pouchdb-node';
import httpQuery from 'pouchdb-req-http-query';

async function runHttpQueryExample() {
  const db = new PouchDB('http-query-test-db');

  try {
    // Example 1: Fetch all documents (equivalent to GET /db/_all_docs)
    const allDocsRequest = {
      path: '_all_docs',
      method: 'GET',
      query: {
        include_docs: true,
      },
      headers: {
        'Accept': 'application/json'
      }
    };

    console.log('Executing CouchDB-style GET _all_docs request...');
    const allDocsResponse = await httpQuery(db, allDocsRequest);
    console.log('GET _all_docs response:', JSON.stringify(allDocsResponse, null, 2));

    // Example 2: Insert a new document (equivalent to POST /db)
    const insertDocRequest = {
      path: '', // Empty path for POST to create new doc at DB root
      method: 'POST',
      body: {
        message: 'Hello from http-query!',
        timestamp: new Date().toISOString()
      },
      headers: {
        'Content-Type': 'application/json'
      }
    };

    console.log('\nExecuting CouchDB-style POST request to insert document...');
    const insertResponse = await httpQuery(db, insertDocRequest);
    console.log('POST insert response:', JSON.stringify(insertResponse, null, 2));

    // Example 3: Get a specific document (equivalent to GET /db/doc_id)
    if (insertResponse.id) {
      const getDocRequest = {
        path: insertResponse.id,
        method: 'GET',
        headers: {
          'Accept': 'application/json'
        }
      };
      console.log(`\nExecuting CouchDB-style GET request for document '${insertResponse.id}'...`);
      const getResponse = await httpQuery(db, getDocRequest);
      console.log(`GET document '${insertResponse.id}' response:`, JSON.stringify(getResponse, null, 2));
    }

  } catch (error) {
    console.error('Error during http query example:', error);
  } finally {
    await db.destroy();
    console.log('\nDatabase destroyed.');
  }
}

runHttpQueryExample();