hide-a-bed 5.2.8 → 6.0.0-beta.0

package/README.md

@@ -1,43 +1,51 @@
 ### API Quick Reference
 
-🍭 denotes a *Sugar* api - helps makes some tasks sweet and easy, but may hide some complexities you might want to deal with. 
+🍭 denotes a _Sugar_ API - helps make some tasks sweet and easy, but may hide some complexities you might want to deal with.
 
-| Document Operations | Bulk Operations | View Operations | Changes Feed |
-|-------------------|-----------------|-----------------|-----------------|
-| [`get()`](#get) | [`bulkGet()`](#bulkget) | [`query()`](#query) | [`changes()`](#changes) |
-| [`put()`](#put) | [`bulkSave()`](#bulksave) | [`queryStream()`](#querystream) | [`watchDocs()`](#watchDocs) 🍭 |
-| [`patch()`](#patch) 🍭 | [`bulkRemove()`](#bulkremove) |  | |
-| [`patchDangerously()`](#patchdangerously) 🍭 | [`bulkGetDictionary()`](#bulkgetdictionary) 🍭 | | |
-| [`getAtRev()`](#getatrev) 🍭 | [`bulkSaveTransaction()`](#bulksavetransaction) 🍭 | | |
-| [`createLock()`](#createLock) 🍭 | | | |
-| [`removeLock()`](#removeLock) 🍭 | | | |
+| Document Operations                          | Bulk Operations                                    | View Operations                 | Change Utilities                                   |
+| -------------------------------------------- | -------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| [`get()`](#get)                              | [`bulkGet()`](#bulkget)                            | [`query()`](#query)             | [`watchDocs()`](#watchdocs) 🍭                     |
+| [`put()`](#put)                              | [`bulkSave()`](#bulksave)                          | [`queryStream()`](#querystream) | [Standalone changes feed](#changes-feed-companion) |
+| [`patch()`](#patch) 🍭                       | [`bulkRemove()`](#bulkremove)                      | [`remove()`](#remove)           |                                                    |
+| [`patchDangerously()`](#patchdangerously) 🍭 | [`bulkRemoveMap()`](#bulkremovemap)                |                                 |                                                    |
+| [`getAtRev()`](#getatrev) 🍭                 | [`bulkGetDictionary()`](#bulkgetdictionary) 🍭     |                                 |                                                    |
+| [`createLock()`](#createlock) 🍭             | [`bulkSaveTransaction()`](#bulksavetransaction) 🍭 |                                 |                                                    |
+| [`removeLock()`](#removelock) 🍭             |                                                    |                                 |                                                    |
 
-And some utility apis
+And some utility APIs
 
- - [`getDBInfo()`](#getDBInfo)
- - [`createQuery()`](#createquery) 🍭
- - [`withRetry()`](#withretry)
- 
+- [`getDBInfo()`](#getdbinfo)
+- [`createQuery()`](#createquery) 🍭
+- [`withRetry()`](#withretry)
 
 ### Setup
 
 Depending on your environment, use import or require
-```import { get, put, query } from 'hide-a-bed'```
+
+```
+import { get, put, query } from 'hide-a-bed'
+```
+
 or
-```const { get, put, query } = require('hide-a-bed')```
+
+```
+const { get, put, query } = require('hide-a-bed')
+```
 
 ### Config
 
 Anywhere you see a config, it is an object with the following setup
-```{ couch: 'https://username:pass@the.couch.url.com:5984' }```
+`{ couch: 'https://username:pass@the.couch.url.com:5984' }`
 And it is passed in as the first argument of all the functions
-```const doc = await get(config, 'doc-123')```
+`const doc = await get(config, 'doc-123')`
 
 See [Advanced Config Options](#advanced-config-options) for more advanced settings.
 
-#### bindConfig 
+#### bindConfig
+
+bindConfig function is a convenience method to bind the config, so you don't need to pass it in every call.
+Usually, you label the variable returned db so method calls appear to operate on the bound db.
 
-A convience method to bind the config, so you dont need to pass it in.
 ```
 import { bindConfig } from 'hide-a-bed'
 const db = bindConfig(process.env)
@@ -45,33 +53,19 @@ const services = { db } // see example below
 const doc = await db.get('doc-123')
 ```
 
-If you need to force autocompletion/type-checking, you can add the following jsdoc to help your editor
-
-```
-function doSomething (services)
-  /**  @type { import('hide-a-bed').DB} db */
-  const db = services.db;
-```
-
-Here is an example of compiler warnings:
-
-![jsdoc type def](docs/compiler.png)
-
-
 ##### Config Overrides
 
-You also can quickly change one (or more) config settings for a particular call with the db.options(optionOverrides)
+You also can quickly override (or more) config settings for a particular call using db.options(optionOverrides)
 
-eg
+e.g.
 
 ```
 const db = bindConfig({ couch: 'http://localhost:5984/db', throwOnGetNotFound: false  })
-const doc = await db.options({ throwOnGetNotFound: true }).get('doc-id') 
+const doc = await db.options({ throwOnGetNotFound: true }).get('doc-id')
 ```
 
 You can pass any of [Config Options](#advanced-config-options) to db.options to override the original config bindings.
 
-
 ### Document Operations
 
 #### get
@@ -79,11 +73,10 @@ You can pass any of [Config Options](#advanced-config-options) to db.options to
 Get a single document by ID.
 
 **Parameters:**
-- `config`: Object with couch URL string and optional throwOnGetNotFound flag
-- `id`: Document ID string
-- `config`: Object with 
-   * `couch` URL string
-   * `throwOnGetNotFound` default false. If true, 404 docs throw
+
+- `config`: Object with
+  - `couch` URL string
+  - `throwOnGetNotFound` default false. If true, 404 docs throw
 - `id`: Document ID string
 - Returns: Promise resolving to document object or null if not found
 
@@ -92,16 +85,18 @@ const config = { couch: 'http://localhost:5984/mydb' }
 const doc = await get(config, 'doc-123')
 console.log(doc._id, doc._rev)
 
-const notThereIsNull = await get(config, 'does-not-exist')
-console.log(notThereIsNull) // null 
+const notFound = await get(config, 'notFound')
+console.log(notFound) // null
 
 try {
-  const config = { couch: '', throwOnGetNotFound: true }
-  await get(config, 'does-not-exist')
+  const config = {
+    couch: 'http://localhost:5984/mydb',
+    throwOnGetNotFound: true
+  }
+  await get(config, 'notFound')
 } catch (err) {
   if (err.name === 'NotFoundError') console.log('Document not found')
 }
-
 ```
 
 #### put
@@ -109,13 +104,14 @@ try {
 Save a document.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `doc`: Document object with `_id` property
-- Returns: Promise resolving to response with `ok`, `id`, `rev` properties
+- Returns: Promise resolving to response with `ok`, `id`, `rev` properties, eg: { ok: boolean, id: string, rev: string }
 
 ```javascript
 const config = { couch: 'http://localhost:5984/mydb' }
-const doc = { 
+const doc = {
   _id: 'doc-123',
   type: 'user',
   name: 'Alice'
@@ -124,28 +120,28 @@ const result = await put(config, doc)
 // result: { ok: true, id: 'doc-123', rev: '1-abc123' }
 
 // imaginary rev returns a conflict
-const doc = { _id: 'notThereDoc', _rev: '32-does-not-compute'}
+const doc = { _id: 'notThereDoc', _rev: '32-does-not-compute' }
 const result2 = await db.put(doc)
 console.log(result2) // { ok: false, error: 'conflict', statusCode: 409 }
 ```
 
 #### patch
 
-Update specific properties of a document, you must know the _rev, and passed in with properties.
+The patch function lets you update specific properties of a document. The \_rev value must be set, and passed in with properties.
 
 **Parameters:**
+
 - `config`: Object with couch URL string
 - `id`: Document ID string
-- `properties`: Object with properties to update, one _must_ be the current _rev
+- `properties`: Object with properties to update, must include \_rev property
 - Returns: Promise resolving to response with `ok`, `id`, `rev` properties
 
 ```javascript
-const config = { 
+const config = {
   couch: 'http://localhost:5984/mydb',
-  retries: 3,
-  delay: 500
+  retries: 3
 }
-const properties = { 
+const properties = {
   _rev: '3-fdskjhfsdkjhfsd',
   name: 'Alice Smith',
   updated: true
@@ -153,28 +149,29 @@ const properties = {
 const result = await patch(config, 'doc-123', properties)
 // result: { ok: true, id: 'doc-123', rev: '2-xyz789' }
 ```
+
 #### patchDangerously
 
-Update specific properties of a document, no _rev is needed.
+Update specific properties of a document, no \_rev is needed.
 
 **Parameters:**
+
 - `config`: Object with couch URL string
 - `id`: Document ID string
 - `properties`: Object with properties to update
 
-*warning* - this can clobber data. It will retry even if a conflict happens. There are some use cases for this, but you have been warned, hence the name.
+_Warning_: patchDangerously can clobber data. It will retry even if a conflict happens. There are some use cases for this, but you have been warned, hence the name.
 
 - `id`: Document ID string
 - `properties`: Object with properties to update
 - Returns: Promise resolving to response with `ok`, `id`, `rev` properties
 
 ```javascript
-const config = { 
+const config = {
   couch: 'http://localhost:5984/mydb',
-  retries: 3,
-  delay: 500
+  retries: 3
 }
-const properties = { 
+const properties = {
   name: 'Alice Smith',
   updated: true
 }
@@ -187,11 +184,12 @@ const result = await patchDangerously(config, 'doc-123', properties)
 Return a document at the rev specified.
 
 **Parameters:**
+
 - `config`: Object with couch URL string
 - `id`: Document ID string
 - `rev`: Revision string to retrieve
 
-*CouchDB* is not a version control db. This is a special function for unique situations. The _rev might not be around as couch cleans up old revs.
+_CouchDB_ is not a version control db. This is a special function for unique situations. The \_rev might not be around as couch cleans up old revs.
 
 ```javascript
 const config = { couch: 'http://localhost:5984/mydb' }
@@ -203,11 +201,12 @@ console.log(doc._id, doc._rev)
 
 Create a lock document to try and prevent concurrent modifications.
 
-Note this does not internally lock the document that is referenced by the id. People can still mutate it with 
-all the other document mutation functions. This should just be used at an app level to coordinate access 
+Note this does not internally lock the document that is referenced by the id. People can still mutate it with
+all the other document mutation functions. This should just be used at an app level to coordinate access
 on long running document editing.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `docId`: Document ID string to lock
 - `options`: Lock options object:
@@ -221,6 +220,7 @@ Returns a Promise resolving to boolean indicating if lock was created successful
 Remove a lock from a document.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `docId`: Document ID string to unlock
 - `options`: Lock options object:
@@ -252,6 +252,7 @@ if (locked) {
 Save multiple documents in one request.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `docs`: Array of document objects, each with `_id`
 - Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each doc
@@ -274,20 +275,31 @@ const results = await bulkSave(config, docs)
 Get multiple documents by ID.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `ids`: Array of document ID strings
-- Returns: Promise resolving to array of documents
+- `options` _(optional)_:
+  - `validate.docSchema`: zod v4 schema applied to each found document before returning.
+- Returns: Promise resolving to the optionally validated bulk response
 
-Not found documents will still have a row in the results, but the doc will be null, and the error property will be set
+Warning: documents that are not found will still have a row in the results. The doc property will be null, and the error property will be set.
 
 ```javascript
+import z from 'zod'
+
 const config = { couch: 'http://localhost:5984/mydb' }
 const ids = ['doc1', 'doc2', 'doesNotExist']
-const docs = await bulkGet(config, ids)
+const docs = await bulkGet(config, ids, {
+  docSchema: z.looseObject({
+    _id: z.string(),
+    type: z.string(),
+    name: z.string()
+  })
+})
 // rows: [
-//   { _id: 'doc1', _rev: '1-abc123', type: 'user', name: 'Alice' },
-//   { _id: 'doc2', _rev: '1-def456', type: 'user', name: 'Bob' },
-//   { key: 'notThereDoc', error: 'not_found' }
+//   { id: 'doc1', doc: { _id: 'doc1', type: 'user', name: 'Alice' } },
+//   { id: 'doc2', doc: { _id: 'doc2', type: 'user', name: 'Bob' } },
+//   { key: 'doesNotExist', error: 'not_found' }
 // ]
 ```
 
@@ -296,6 +308,7 @@ const docs = await bulkGet(config, ids)
 Delete multiple documents in one request.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `ids`: Array of document ID strings to delete
 - Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each deletion
@@ -310,41 +323,95 @@ const results = await bulkRemove(config, ids)
 // ]
 ```
 
-#### bulkGetDictionary
+#### remove
+
+Delete document from DB with id and rev.
+
+Allows more efficient deletion of document by providing only id and rev. This is useful for deleting documents that are large, or have a lot of data.
+
+**Parameters:**
+
+- `config`: Object with `couch` URL string
+- `id`: document ID to delete
+- `rev`: rev of the document to delete
+- Returns: Promise resolving to array of results with `ok`, `id`, `rev` for the deletion
 
-Adds some convenience to bulkGet. Organizes found and notFound documents into properties that are {id:result}. This makes it easy to deal with the results.
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const id = 'doc1'
+const rev = '2-ghi789'
+const results = await remove(config, id, rev)
+// result:
+//   { ok: true, id: 'doc1', rev: '2-ghi789' }
+```
+
+#### bulkRemoveMap
+
+Delete multiple documents in one request. Same inputs and outputs as [bulkRemove](#bulkremove), but internally the logic will handle one document at a time instead of using couch bulk operations. Useful for working with documents that have large data requirements (1MB or more).
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `ids`: Array of document ID strings to delete
+- Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each deletion
+
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const ids = ['doc1', 'doc2']
+const results = await bulkRemoveMap(config, ids)
+// results: [
+//   { ok: true, id: 'doc1', rev: '2-ghi789' },
+//   { ok: true, id: 'doc2', rev: '2-jkl012' }
+// ]
+```
+
+#### bulkGetDictionary
+
+Adds convenience to bulkGet. Organizes found and notFound documents into properties that are {id:result}. This makes it easy to deal with the results.
+
+**Parameters:**
+
+- `config`: Object with `couch` URL string
+- `ids`: Array of document ID strings to get
+- `options` _(optional)_:
+  - `validate.docSchema`: zod v4 schema applied to each found document before returning.
 - Returns: Promise resolving to an object with found and notFound properties.
 
-*found* looks like 
+_found_ looks like
+
 ```
-{ 
-  id1: { _id: 'id1', _rev: '1-221', data: {} },
-  id2: { _id: 'id2', _rev: '4-421', data: {} },
+{
+  doc1: { _id: 'doc1', _rev: '1-221', data: {} },
+  doc2: { _id: 'doc2', _rev: '4-421', data: {} },
 }
 ```
 
-*notFound* looks like 
+_notFound_ looks like
+
 ```
 {
-  id3: { key: 'id1', error: 'not_found' }
+  doesNotExist: { key: 'doesNotExist', error: 'not_found' }
 }
 ```
 
 ```javascript
+import z from 'zod'
+
 const config = { couch: 'http://localhost:5984/mydb' }
-const ids = ['doc1', 'doc2']
-const results = await bulkGetDictionary(config, ids)
+const ids = ['doc1', 'doc2', 'doesNotExist']
+const results = await bulkGetDictionary(config, ids, {
+  docSchema: z.looseObject({
+    _id: z.string(),
+    data: z.record(z.any())
+  })
+})
 // results: {
 //   found: {
-//     id1: { _id: 'id1', _rev: '1-221', data: {} },
-//     id2: { _id: 'id2', _rev: '4-421', data: {} },
+//     doc1: { _id: 'doc2', _rev: '1-221', data: {} },
+//     doc2: { _id: 'doc2', _rev: '4-421', data: {} },
 //   },
 //   notFound: {
-//      id3: { key: 'id1', error: 'not_found' }
+//      doesNotExist: { key: 'doesNotExist', error: 'not_found' }
 //   }
 // }
 ```
@@ -354,6 +421,7 @@ const results = await bulkGetDictionary(config, ids)
 Perform a bulk save operation with all-or-nothing semantics.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
 - `transactionId`: Unique identifier for the transaction
 - `docs`: Array of document objects to save
@@ -364,6 +432,7 @@ This operation ensures that either all documents are saved successfully, or none
 Note: The transactionId has to be unique for the lifetime of the app. It is used to prevent two processes from executing the same transaction. It is up to you to craft a transactionId that uniquely represents this transaction, and that also is the same if another process tries to generate it.
 
 Exceptions to handle:
+
 - `TransactionSetupError`: Thrown if the transaction document cannot be created. Usually because it already exists
 - `TransactionVersionConflictError`: Thrown if there are version conflicts with existing documents.
 - `TransactionBulkOperationError`: Thrown if the bulk save operation fails for some documents.
@@ -403,10 +472,9 @@ Get basic info about a db in couch
 ```
 const config = { couch: 'http://localhost:5984/mydb' }
 const result = await getDBInfo(config)
-// result: { db_name: 'test', doc_count: 3232 } 
+// result: { db_name: 'test', doc_count: 3232 }
 ```
 
-
 ### View Queries
 
 #### query
@@ -414,8 +482,9 @@ const result = await getDBInfo(config)
 Query a view with options.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
-- `view`: View path string (e.g. '_design/doc/_view/name')
+- `view`: View path string (e.g. '\_design/doc/\_view/name')
 - `options`: Optional object with query parameters:
   - `startkey`: Start key for range
   - `endkey`: End key for range
@@ -441,7 +510,7 @@ const options = {
 const result = await query(config, view, options)
 // result: {
 //   rows: [
-//     { 
+//     {
 //       id: 'doc1',
 //       key: 'Alice',
 //       value: 1,
@@ -452,16 +521,15 @@ const result = await query(config, view, options)
 // }
 ```
 
-Some notes on the keys. Use native js things for arrays keys, rather then strings. Eg
-
- - ```{ startkey: ['ryan'], endkey: ['ryan', {}] }```
- - ```{ startkey: [47, null], endkey: [48, null] }```
- - ```{ startkey: [customerIdVar], endkey: [customerIdVar, {}] }```
- - ```{ startkey: [teamId, userId, startTimestamp], endkey: [teamId, userId, endTimestamp] }```
-
+Some notes on the keys. Use native js types for arrays keys, rather then strings. Eg
 
+- `{ startkey: ['ryan'], endkey: ['ryan', {}] }`
+- `{ startkey: [47, null], endkey: [48, null] }`
+- `{ startkey: [customerIdVar], endkey: [customerIdVar, {}] }`
+- `{ startkey: [teamId, userId, startTimestamp], endkey: [teamId, userId, endTimestamp] }`
 
 #### createQuery()
+
 Create a query builder to help construct view queries with a fluent interface. Note we have stuck to couch naming conventions and not camel case.
 
 - Returns: QueryBuilder instance with methods:
@@ -478,26 +546,22 @@ Create a query builder to help construct view queries with a fluent interface. N
   - `build()`: Return the constructed query options object
 
 ```javascript
-const options = createQuery()
-  .startkey('A')
-  .endkey('B')
-  .include_docs(true)
-  .limit(10)
-  .build()
+const options = createQuery().startkey('A').endkey('B').include_docs(true).limit(10).build()
 
 const result = await query(config, view, options)
 ```
 
 Again, use js types for array keys
 
-  - ```.startkey([teamId, userId]).endkey([teamId, userId, {}])```
-  - ```.startkey([teamId, userId, startTimestamp]).endkey([teamId, userId, endTimestamp])```
+- `.startkey([teamId, userId]).endkey([teamId, userId, {}])`
+- `.startkey([teamId, userId, startTimestamp]).endkey([teamId, userId, endTimestamp])`
 
 #### queryStream
 
-Use Cases *Streaming Data*
+Use Cases _Streaming Data_
 
 **Parameters:**
+
 - `config`: Object with couch URL string
 - `view`: View path string
 - `options`: Query options object
@@ -505,7 +569,7 @@ Use Cases *Streaming Data*
 
 Want to stream data from couch? You can with queryStream. It looks identical to query, except you add an extra 'onRow' function
 
-Here is a small hapi example of streaming data from couch to the client as ndjson. 
+Here is a small hapi example of streaming data from couch to the client as ndjson.
 We do a small transform by only streaming the doc. you can do a lot of things in the onrow function.
 
 ```
@@ -535,131 +599,120 @@ const init = async () => {
 init()
 ```
 
-Want to consume this in the browser? I'd recomment https://www.npmjs.com/package/ndjson-readablestream 
-here is a react component that consumes it https://github.com/Azure-Samples/azure-search-openai-demo/pull/532/files#diff-506debba46b93087dc46a916384e56392808bcc02a99d9291557f3e674d4ad6c
+Want to consume this in the browser? I'd recommend [ndjson-readablestream](https://www.npmjs.com/package/ndjson-readablestream)
+An [example react component](https://github.com/Azure-Samples/azure-search-openai-demo/pull/532/files#diff-506debba46b93087dc46a916384e56392808bcc02a99d9291557f3e674d4ad6c)
+that consumes the readable stream.
+
+#### Changes feed companion
 
-#### changes()
+The main client no longer bundles the legacy `changes-stream` dependency. Install `hide-a-bed-changes` when you need a CouchDB `_changes` feed helper:
+
+```
+npm install hide-a-bed-changes
+```
 
-Subscribe to the CouchDB changes feed to receive real-time updates.
+Usage mirrors the original API:
+
+```javascript
+import { changes } from 'hide-a-bed-changes'
+
+const config = { couch: 'http://localhost:5984/mydb' }
+
+const feed = await changes(
+  config,
+  change => {
+    console.log('Document changed:', change.id)
+  },
+  { since: 'now', include_docs: true }
+)
+
+feed.on('error', console.error)
+
+// later
+feed.stop()
+```
+
+`hide-a-bed-changes` reuses the same config structure, merges `config.needleOpts`, and resolves `since: 'now'` to the current `update_seq` before starting the feed.
+
+#### watchDocs ()
+
+Watch specific documents for changes in real-time.
 
 **Parameters:**
+
 - `config`: Object with `couch` URL string
-- 'onChange': function called for each change
+- `docIds`: String or array of document IDs to watch (max 100)
+- `onChange`: Function called for each change
 - `options`: Optional object with parameters:
-  - `since`: String or number indicating where to start from ('now' or update sequence number)
-  - `include_docs`: Boolean to include full documents
-  - `filter`: String name of design document filter function
-  - Other standard CouchDB changes feed parameters
+  - `include_docs`: Boolean - include full documents (default false)
+  - `maxRetries`: Number - maximum reconnection attempts (default: 10)
+  - `initialDelay`: Number - initial reconnection delay in ms (default 1000)
+  - `maxDelay`: Number - maximum reconnection delay in ms (default: 30000)
 
-Returns an EventEmitter that emits 'change' events with change objects.
+Returns an EventEmitter that emits:
+
+- 'change' events with change objects.
+- 'error' events when max retries reached.
+- 'end' events with last sequence number.
 
 ```javascript
 const config = { couch: 'http://localhost:5984/mydb' }
-const options = { 
-  since: 'now',
-  include_docs: true
-}
 
-const onChange = change => {
+// Watch a single document
+const feed = await watchDocs(config, 'doc123', change => {
   console.log('Document changed:', change.id)
   console.log('New revision:', change.changes[0].rev)
-  if (change.doc) {
-    console.log('Document contents:', change.doc)
-  }
-}
-const feed = await changes(config, onChange, options)
+})
+
+// Watch multiple documents with full doc content
+const feed = await watchDocs(
+  config,
+  ['doc1', 'doc2', 'doc3'],
+  change => {
+    if (change.doc) {
+      console.log('Updated document:', change.doc)
+    }
+  },
+  { include_docs: true }
+)
+
+// Handle errors
+feed.on('error', error => {
+  console.error('Watch error:', error)
+})
 
+// Handle end of feed
+feed.on('end', ({ lastSeq }) => {
+  console.log('Feed ended at sequence:', lastSeq)
+})
 
-// Stop listening to changes
+// Stop watching
 feed.stop()
 ```
 
-The changes feed is useful for:
-- Building real-time applications
-- Keeping local data in sync with CouchDB
-- Triggering actions when documents change
-- Implementing replication
+The watchDocs feed is useful for:
 
+1.  Building real-time applications focused on specific documents
+2.  Triggering actions when particular documents change
+3.  Maintaining cached copies of frequently-accessed documents
 
-#### watchDocs()
-
-Watch specific documents for changes in real-time.
-
- **Parameters:**
- - `config`: Object with `couch` URL string
- - `docIds`: String or array of document IDs to watch (max 100
- - `onChange`: Function called for each change
- - `options`: Optional object with parameters:
-   - `include_docs`: Boolean to include full documents (defaul
- false)
-   - `maxRetries`: Maximum reconnection attempts (default: 10)
-   - `initialDelay`: Initial reconnection delay in ms (default
- 1000)
-   - `maxDelay`: Maximum reconnection delay in ms (default:
- 30000)
-
- Returns an EventEmitter that emits:
- - 'change' events with change objects
- - 'error' events when max retries reached
- - 'end' events with last sequence number
-
- ```javascript
- const config = { couch: 'http://localhost:5984/mydb' }
-
- // Watch a single document
- const feed = await watchDocs(config, 'doc123', change => {
-   console.log('Document changed:', change.id)
-   console.log('New revision:', change.changes[0].rev)
- })
-
- // Watch multiple documents with full doc content
- const feed = await watchDocs(
-   config,
-   ['doc1', 'doc2', 'doc3'],
-   change => {
-     if (change.doc) {
-       console.log('Updated document:', change.doc)
-     }
-   },
-   { include_docs: true }
- )
-
- // Handle errors
- feed.on('error', error => {
-   console.error('Watch error:', error)
- })
-
- // Handle end of feed
- feed.on('end', ({ lastSeq }) => {
-   console.log('Feed ended at sequence:', lastSeq)
- })
-
- // Stop watching
- feed.stop()
- ```
-
- The watchDocs feed is useful for:
- - Building real-time applications focused on specific documents
- - Triggering actions when particular documents change
- - Maintaining cached copies of frequently accessed documents
-
-Advanced Config Options
-=======================
+### Advanced Config Options
 
 The config object supports the following properties:
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| couch | string | required | The URL of the CouchDB database |
-| throwOnGetNotFound | boolean | false | If true, throws an error when get() returns 404. If false, returns undefined |
-| bindWithRetry | boolean | true | When using bindConfig(), adds retry logic to bound methods |
-| maxRetries | number | 3 | Maximum number of retry attempts for retryable operations |
-| initialDelay | number | 1000 | Initial delay in milliseconds before first retry |
-| backoffFactor | number | 2 | Multiplier for exponential backoff between retries |
-| useConsoleLogger | boolean | false | If true, enables console logging when no logger is provided |
-| logger | object/function | undefined | Custom logging interface (winston-style object or function) |
+| Property           | Type            | Default   | Description                                                             |
+| ------------------ | --------------- | --------- | ----------------------------------------------------------------------- |
+| couch              | string          | required  | The URL of the CouchDB database                                         |
+| throwOnGetNotFound | boolean         | false     | If true, throws an error when get() returns 404. If false, returns null |
+| bindWithRetry      | boolean         | true      | When using bindConfig(), adds retry logic to bound methods              |
+| maxRetries         | number          | 3         | Maximum number of retry attempts for retryable operations               |
+| initialDelay       | number          | 1000      | Initial delay in milliseconds before first retry                        |
+| backoffFactor      | number          | 2         | Multiplier for exponential backoff between retries                      |
+| useConsoleLogger   | boolean         | false     | If true, enables console logging when no logger is provided             |
+| logger             | object/function | undefined | Custom logging interface (winston-style object or function)             |
 
 Example configuration with all options:
+
 ```javascript
 const config = {
   couch: 'http://localhost:5984/mydb',
@@ -673,15 +726,13 @@ const config = {
 }
 ```
 
-
-Logging Support
-==============
+### Logging Support
 
 The library supports flexible logging options that can be configured through the config object:
 
 ```javascript
 // Enable console logging (error, warn, info, debug)
-const config = { 
+const config = {
   couch: 'http://localhost:5984/mydb',
   useConsoleLogger: true
 }
@@ -690,10 +741,10 @@ const config = {
 const config = {
   couch: 'http://localhost:5984/mydb',
   logger: {
-    error: (msg) => console.error(msg),
-    warn: (msg) => console.warn(msg),
-    info: (msg) => console.info(msg),
-    debug: (msg) => console.debug(msg)
+    error: msg => console.error(msg),
+    warn: msg => console.warn(msg),
+    info: msg => console.info(msg),
+    debug: msg => console.debug(msg)
   }
 }
 
@@ -705,6 +756,7 @@ const config = {
 ```
 
 The logger will track operations including:
+
 - Document operations (get, put, patch)
 - Bulk operations
 - View queries
@@ -712,8 +764,8 @@ The logger will track operations including:
 - Retries and error handling
 
 Each operation logs appropriate information at these levels:
-- error: Fatal/unrecoverable errors
-- warn: Retryable errors, conflicts
-- info: Operation start/completion
-- debug: Detailed operation information
 
+- error: Fatal/unrecoverable errors.
+- warn: Retryable errors, conflicts.
+- info: Operation start/completion.
+- debug: Detailed operation information.