PouchDB Users Database Plugin

Common errors

• TypeError: PouchDB.plugin is not a function

  cause PouchDB was not loaded or aliased correctly, or the plugin was attempted to be installed on a database instance instead of the PouchDB constructor.
  fix Ensure `const PouchDB = require('pouchdb')` is called before attempting to install the plugin, and that `PouchDB.plugin()` is used, not `db.plugin()`.

• TypeError: db.installUsersBehavior is not a function

  cause The `pouchdb-users` plugin was not successfully installed on the PouchDB constructor before initializing the database instance.
  fix Verify that `PouchDB.plugin(require('pouchdb-users'))` is called prior to `new PouchDB()` or `db = new PouchDB()`.

• Error: Document update conflict

  cause Attempted to `put` a user document with an `_id` that already exists without specifying the `_rev` property of the existing document, or without handling the conflict programmatically.
  fix When updating an existing user, retrieve the document first to get its `_rev`, then include `_rev` in the updated document. Alternatively, handle the conflict in your `catch` block.

Warnings

• gotcha pouchdb-users explicitly does NOT implement any access restrictions or user context. It solely handles password hashing and document formatting for CouchDB's `_users` database. You will need to implement your own authorization logic on top of this plugin.
  Fix: Always build your own access control layer or use a separate authentication/authorization system alongside `pouchdb-users`.
• deprecated This package is no longer actively maintained; the last release was in June 2017. This may lead to compatibility issues with newer Node.js versions, updated PouchDB APIs, or potential security vulnerabilities due to unaddressed bugs or outdated dependencies (e.g., in `pbkdf2`).
  Fix: Consider migrating to more actively maintained PouchDB authentication solutions or developing custom logic for user management if long-term support is critical. Evaluate the risks of using unmaintained software carefully.
• gotcha The plugin is designed for PouchDB environments that primarily use CommonJS `require()`. While PouchDB itself has evolved, this plugin might not be directly compatible with pure ESM environments without transpilation or specific build configurations.
  Fix: Ensure your project's module resolution for PouchDB and its plugins is configured for CommonJS, or use older Node.js versions if encountering module loading issues. Consider using a bundler like Webpack or Rollup to handle compatibility.

Install

• npm install pouchdb-users npm
• yarn add pouchdb-users yarn
• pnpm add pouchdb-users pnpm

Imports

• PouchDB
  wrong:

  import PouchDB from 'pouchdb'

  correct:

  const PouchDB = require('pouchdb')

  This package primarily supports CommonJS `require()` patterns. Modern PouchDB versions might have ESM support, but this plugin is designed for older CommonJS PouchDB environments.
• pouchdb-users
  wrong:

  import PouchDBUsers from 'pouchdb-users'

  correct:

  const PouchDBUsers = require('pouchdb-users')

  Import the plugin module using CommonJS `require()` for compatibility.
• plugin installation
  wrong:

  db.plugin(require('pouchdb-users'))

  correct:

  PouchDB.plugin(require('pouchdb-users'))

  PouchDB plugins are installed on the `PouchDB` constructor itself, not on an individual database instance.

Quickstart

Demonstrates how to install the pouchdb-users plugin and create a new user document, showing how the password gets hashed and stored in a CouchDB-compatible format within a local PouchDB instance.

const PouchDB = require('pouchdb')
PouchDB.plugin(require('pouchdb-users'))
const memdown = require('memdown') // For an in-memory database example

async function setupUsersDatabase() {
  const db = new PouchDB('my-users', { db: memdown })

  console.log('Installing users behavior...')
  await db.installUsersBehavior()
  console.log('Users behavior installed.')

  console.log('Creating a new user...')
  const newUserDoc = {
    _id: 'org.couchdb.user:testuser',
    type: 'user',
    name: 'testuser',
    password: 'supersecretpassword123'
  }
  const response = await db.put(newUserDoc)
  console.log('User created/updated:', response)

  console.log('Fetching the user document to see hashed password...')
  const userDoc = await db.get('org.couchdb.user:testuser')
  console.log('Retrieved user document:', userDoc)

  // Example against a remote CouchDB _users database (requires admin credentials)
  // const remoteDb = new PouchDB('http://localhost:5984/_users', {
  //   auth: {
  //     username: process.env.COUCHDB_ADMIN_USERNAME ?? 'admin',
  //     password: process.env.COUCHDB_ADMIN_PASSWORD ?? 'adminpassword'
  //   }
  // })
  // await remoteDb.installUsersBehavior()
  // console.log('Remote users behavior installed.')
  // const remoteResponse = await remoteDb.put({
  //   _id: 'org.couchdb.user:remoteuser',
  //   type: 'user',
  //   name: 'remoteuser',
  //   password: 'anothersecretpassword'
  // })
  // console.log('Remote user created:', remoteResponse)
}

setupUsersDatabase().catch(console.error)