# couch-pubsub

> PubSub via CouchDB

Latest version **1.3.0** (published 2015-08-02) · ISC license · 0 weekly downloads

## Install

```sh
npm install couch-pubsub
pnpm add couch-pubsub
yarn add couch-pubsub
bun add couch-pubsub
```

Provides the command `couch-pubsub`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2015-08-02 |
| First published | 2015-07-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 12 |
| Author | MattCollins84 |
| Maintainers | mattcollins84 |
| Keywords | couchdb, pubsub, feed, realtime, publish, subscribe, message bus, distributed message handler, notifications, scalable pubsub, scalable, cloudant, pouchdb, browser |

## Links

- npm: https://www.npmjs.com/package/couch-pubsub
- Repository: https://github.com/MattCollins84/couch-pubsub
- Homepage: https://github.com/MattCollins84/couch-pubsub#readme
- Issues: https://github.com/MattCollins84/couch-pubsub/issues
- npm.io page: https://npm.io/package/couch-pubsub

## Dependencies (2)

- [async](https://npm.io/package/async.md) 1.3.0
- [pouchdb](https://npm.io/package/pouchdb.md) ^3.6.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.3.0 (latest) — 2015-08-02
- 1.2.0 — 2015-07-20
- 1.1.0 — 2015-07-19
- 1.0.2 — 2015-07-17
- 1.0.1 — 2015-07-16
- 1.0.0 — 2015-07-16

## README

# couch-pubsub

A pub/sub tool that leverages the power of CouchDB clustering to provide a simple, reliable and distributed system out of the box.

Available for Node, the command line and even in the browser.

# Installation 

`couch-pubsub` can be used with Node, from the command line or directly in the browser.

## Node
```
npm install couch-pubsub
```
Then:
``` js
var CouchPubSub = require('couch-pubsub');
```

## Browser
```
npm install couch-pubsub
```
Then:
``` html
<script src="node_modules/couch-pubsub/dist/couch-pubsub.min.js"></script>
```

## via CLI
```
npm install -g couch-pubsub
```

# Usage

There are two main functions.

* **Publish** - write some data to a channel
* **Subscribe** - Get updates from a channel as they happen


There is also a utility function that allows you to fetch all events on a particular channel since a particular date.

## Javascript (Node.js or Browser)

### .publish( channel, str, [callback] )
To publish to the `test-channel`, you could do something like this:
``` js
var pubsub = new CouchPubSub({
  couch_host: "https://my-couch-db.com",
  couch_username: "username",
  couch_password: "password",
  couch_port: null // null for default
});

pubsub.publish("test-channel", "string that you want to publish", function(err, data) {
  
  // err - error writing to couchDB
  // data - the response from couchDB, contains _id and _rev of the doc
  
});
```

or if you don't want to handle the callback:

``` js
pubsub.publish("test-channel", "string that you want to publish");
```

### .subscribe( opts )

If you wanted to listen for updates to this channel you could do something like this:

``` js
var pubsub = new CouchPubSub({
  couch_host: "https://my-couch-db.com",
  couch_username: "username",
  couch_password: "password",
  couch_port: null // null for default
});

var sub = pubsub.subscribe("test-channel");
sub.on('update', function (update) {
    
  // update - the value that was published (e.g. 'string that you want to publish' from above')
    
});
```

To get all updates since a particular date and keep on listening for future updates:

``` js
var sub = pubsub.subscribe({ channel: "test-channel", since: "2015-01-03 13:26:00"});
sub.on('update', function (update) {
    
  // update - the value that was published (e.g. 'string that you want to publish' from above')
    
});
```
### .since( channel, date, callback )
To get all events since a particular date, as a one off event:

``` js
var pubsub = new CouchPubSub({
  couch_host: "https://my-couch-db.com",
  couch_username: "username",
  couch_password: "password",
  couch_port: null // null for default
});

var since = pubsub.since("test-channel", "2015-01-03 13:26:00", function(err, data) {
  
  // err - error retrieving previous events
  // data - array of previous events

});
```

## Command line

To replicate the examples above on the command line you could do:

# publish

``` js
couch-pubsub publish test-channel "string that you want to publish"
-> {"ok":true,"id":"7d6eaf1ddcd0f8f42f98d4a58ba3a527","rev":"1-9d78b84800709cf0d8446f2147c74d75"}
```

# subscribe

``` js
couch-pubsub subscribe test-channel
-> "string that you want to publish"
-> "the next string that was published"
-> "the last string to be published"
```

If you want to subscribe but also retrieve all channel events since a particular date, you can add a date to the above comand.

``` js
couch-pubsub subscribe test-channel "2015-01-03 13:26:00"
-> "previous event 1"
-> "previous event 2"
-> "previous event 3"
-> "previous event 4"
-> "string that you want to publish"
-> "the next string that was published"
-> "the last string to be published"
```

You will need to supply your CouchDB credentials via environemnt variables:

```
export COUCH_PUBSUB_HOST="http://my-couch-db.com"
export COUCH_PUBSUB_USERNAME="username"
export COUCH_PUBSUB_PASSWORD="password"
```

# TODO

I put this together pretty quickly and there are some things I want to add still, such as:

* Better error checking
* Some test coverage
* Probably more...

---
_Source: https://npm.io/package/couch-pubsub · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._