couchdb-changes-stream v1.1.0

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 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

Fields in CouchDBChangesOptions

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! 🚀