hereconnect/packages/couchdb-changes-stream

CouchDBChangesStream Documentation

---

Description

CouchDBChangesStream is a TypeScript class for handling real-time changes in a CouchDB database through the _changes API. It supports normal, longpoll, continuous, and eventsource modes, with filtering via selector and automatic reconnection in live mode.

---

Installation

Install the package via npm:

npm install @hereconnect/couchdb-changes-stream

---

Usage

Example

import { CouchDBChangesStream } from "couchdb-changes-stream";

const changesStream = new CouchDBChangesStream(
  "http://localhost:5984/mydb",
  {
    feed: "continuous",
    include_docs: true,
    since: "now",
    heartbeat: 10000,
    selector: {
      type: "message",
    },
  },
);

(async () => {
  try {
    for await (const change of changesStream) {
      console.log("Change:", change);

      // Process data
      if (change.doc) {
        console.log("Document:", change.doc);
      }
    }
  } catch (error) {
    console.error("Error in changes stream:", error);
  }
})();

---

Parameters

Constructor

new CouchDBChangesStream<T>(
  dbUrl: string,
  options: CouchDBChangesOptions | Readonly<CouchDBChangesOptions>,
)

Constructor Parameters

Parameter	Type	Description
dbUrl	string	The CouchDB database URL (e.g., http://localhost:5984/mydb).
options	CouchDBChangesOptions	The query options. Supports the same parameters as CouchDB _changes API.

Fields in CouchDBChangesOptions

Field	Type	Description
since	string | number	The sequence to start from (now or a number).
filter	string	Name of the filter (e.g., _selector).
doc_ids	string[] | readonly string[]	List of document IDs to filter.
selector	Record<string, unknown>	A JSON object for selecting documents (works only with POST).
feed	"normal" | "longpoll" | "continuous" | "eventsource"	Feed mode.
include_docs	boolean	Include document body in changes.
heartbeat	boolean | number	Frequency of keep-alive messages in milliseconds.
live	boolean	Enable live mode with automatic reconnection.
timeout	number	Timeout for waiting for changes in milliseconds.

---

Features

• Support for all modes: normal, longpoll, continuous, eventsource.
• Filtering via selector: Uses the POST method when selector is present.
• Automatic reconnection: Enabled in live mode.
• Heartbeat support: Keeps connections alive.
• Scalable: Asynchronous stream for handling large data volumes.

---

Methods

stop

public stop(): void

Stops the current changes stream.

Example:

changesStream.stop();

---

Errors

• HTTP error: 400: Invalid request parameters (e.g., incorrect selector).
• HTTP error: 401: Authentication error.
• Error parsing change: Failed to parse data from the stream.

---

Usage Tips

1. Use heartbeat to keep connections alive.
2. Add exception handling to properly manage network errors.
3. Prefer selector over filter for more flexible document selection.
4. Call stop when done to terminate the stream gracefully.

---

License

This project is distributed under the MIT License.

---

For questions or issues, feel free to reach out! 🚀