{"id":16498,"library":"pouchdb-req-http-query","title":"PouchDB HTTP Request Adapter","description":"`pouchdb-req-http-query` is a utility within the PouchDB ecosystem designed to bridge CouchDB-style request objects with PouchDB's internal HTTP request handling. It allows developers to construct a request object formatted similarly to a CouchDB request and then execute it against a given PouchDB database instance as an HTTP operation. This package is currently at version 4.2.0 and receives maintenance updates for bug fixes and dependency management, indicating an active but mature status. Its key differentiators include its role in facilitating lower-level HTTP interactions with PouchDB, particularly when integrating with systems expecting CouchDB's request structures, and its inclusion in the PouchDB monorepo.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/pouchdb/pouchdb-server","tags":["javascript","pouch","pouchdb","couch","couchdb","http","request"],"install":[{"cmd":"npm install pouchdb-req-http-query","lang":"bash","label":"npm"},{"cmd":"yarn add pouchdb-req-http-query","lang":"bash","label":"yarn"},{"cmd":"pnpm add pouchdb-req-http-query","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package operates on PouchDB database instances, requiring `pouchdb-core` for core PouchDB functionality.","package":"pouchdb-core","optional":false}],"imports":[{"note":"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.","wrong":"const httpQuery = require('pouchdb-req-http-query');","symbol":"httpQuery","correct":"import httpQuery from 'pouchdb-req-http-query';"}],"quickstart":{"code":"import PouchDB from 'pouchdb-node';\nimport httpQuery from 'pouchdb-req-http-query';\n\nasync function runHttpQueryExample() {\n  const db = new PouchDB('http-query-test-db');\n\n  try {\n    // Example 1: Fetch all documents (equivalent to GET /db/_all_docs)\n    const allDocsRequest = {\n      path: '_all_docs',\n      method: 'GET',\n      query: {\n        include_docs: true,\n      },\n      headers: {\n        'Accept': 'application/json'\n      }\n    };\n\n    console.log('Executing CouchDB-style GET _all_docs request...');\n    const allDocsResponse = await httpQuery(db, allDocsRequest);\n    console.log('GET _all_docs response:', JSON.stringify(allDocsResponse, null, 2));\n\n    // Example 2: Insert a new document (equivalent to POST /db)\n    const insertDocRequest = {\n      path: '', // Empty path for POST to create new doc at DB root\n      method: 'POST',\n      body: {\n        message: 'Hello from http-query!',\n        timestamp: new Date().toISOString()\n      },\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    };\n\n    console.log('\\nExecuting CouchDB-style POST request to insert document...');\n    const insertResponse = await httpQuery(db, insertDocRequest);\n    console.log('POST insert response:', JSON.stringify(insertResponse, null, 2));\n\n    // Example 3: Get a specific document (equivalent to GET /db/doc_id)\n    if (insertResponse.id) {\n      const getDocRequest = {\n        path: insertResponse.id,\n        method: 'GET',\n        headers: {\n          'Accept': 'application/json'\n        }\n      };\n      console.log(`\\nExecuting CouchDB-style GET request for document '${insertResponse.id}'...`);\n      const getResponse = await httpQuery(db, getDocRequest);\n      console.log(`GET document '${insertResponse.id}' response:`, JSON.stringify(getResponse, null, 2));\n    }\n\n  } catch (error) {\n    console.error('Error during http query example:', error);\n  } finally {\n    await db.destroy();\n    console.log('\\nDatabase destroyed.');\n  }\n}\n\nrunHttpQueryExample();","lang":"typescript","description":"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."},"warnings":[{"fix":"Review the official PouchDB monorepo migration guides and `express-pouchdb` changelogs for specific adjustments required when upgrading from pre-4.0.0 versions.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refer to the `express-pouchdb` v2.0.0 release page for detailed breaking changes and migration steps.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 <4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade to `pouchdb-req-http-query` version 4.0.0 or newer to incorporate the security fix.","message":"Version 4.0.0 fixed a security issue (referenced as #290 in the changelog). Running older versions may expose applications to this vulnerability.","severity":"security","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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`.","error":"TypeError: Cannot read properties of undefined (reading 'auth')"},{"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.","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.","error":"EventEmitter memory leak detected. 11 listener's added. Use emitter.setMaxListeners() to increase limit"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'body') or similar 'bulkDocs TypeError'"}],"ecosystem":"npm"}