# @darkhogg/pubsub

> [![npm (scoped)](https://img.shields.io/npm/v/@darkhogg/pubsub.svg)](https://www.npmjs.com/package/@darkhogg/pubsub)

Latest version **0.3.0** (published 2019-07-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @darkhogg/pubsub
pnpm add @darkhogg/pubsub
yarn add @darkhogg/pubsub
bun add @darkhogg/pubsub
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2019-07-05 |
| First published | 2019-05-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 9.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Daniel Escoz |
| Maintainers | darkhogg |

## Links

- npm: https://www.npmjs.com/package/@darkhogg/pubsub
- npm.io page: https://npm.io/package/@darkhogg/pubsub

## Dependencies (2)

- [mongodb](https://npm.io/package/mongodb.md) ^3.2.7
- [polyethylene](https://npm.io/package/polyethylene.md) ^1.4.0

## Recent versions

- 0.3.0 (latest) — 2019-07-05
- 0.2.0 — 2019-07-05
- 0.1.0 — 2019-05-28

## README

# `@darkhogg/pubsub`

[![npm (scoped)](https://img.shields.io/npm/v/@darkhogg/pubsub.svg)](https://www.npmjs.com/package/@darkhogg/pubsub)

A simple Publish/Subscribe system with persistent messages that uses MongoDB as
a backend.

This is a toy project, created mostly to prove a point.  It is usable and might
solve somebody's problem, but its feature set is unlikely to grow.
You are still welcome to report bugs or suggest improvements, and I will try to
find time to look at them.


## Usage

The API is really simple, most of it can be understood just by looking at the
`examples` directory.

You should import this library as follows:

```
const {createPubSub} = require('@darkhogg/pubsub');
```


### `createPubSub(mongoUri, {bucket, clientName, startDate})`

Returns a promise to a `PubSub` client that connects to the given `mongoUri`.
The client will respect the database given by the URI.

  - `bucket` is used as the prefix of all collections.
    Defaults to `'pubsub'`.
  - `clientName` is a string is used to identify this client and is used to
    determine which events were already consumed by it.  No more that one
    client with the same name will ever consume the same message.
    Defaults to `'default'`.
  - `startDate` is a `Date` determining the first date at which this client is
    interested in events.  This is useful to prevent processing a huge number
    of past events for new clients that are only interested in future events.
    Defaults to `new Date(0)` (that is, `1970-01-01T00:00:00.000Z`)

Note that this is the only exported symbol by the library itself.


### `PubSub.channel(channelName)`

Returns a promise to a `Channel` with the given `channelName`.
Channels are cached, so multiple calls to this method will resolve to the same
object.  Each channel comes with its own collection in the database.


### `PubSub.disconnect()`

Disconnects the client and returns a promise to the successful disconnection.
this will stop all channels and close the MongoDB connection.  The client or
any channels created by it are unusable after this call.


### `Channel.publish(name, body)`

Publishes a message with the given `name` and `body` in this channel.
Returns a promise that resolves after the message was published.

### `Channel.subscribe(name, callback)`

Registers the `callback` to be called whenever a message with the given `name`
is published.  the callback is called with the message `body` as its argument.
Returns a `Subscription`.

### `Channel.unsubscribeAll()`

Cancels all subscription to this channel.
No more messages will arrive to any subscriptors of this channel object.

New subscriptions can still be created normally after this call.


### `Subscription.unsubscribe`

Cancel the subscription.
No more messages will arrive to this particular subscriptor, but others
will still receive messages.

New subscriptions can still be created normally after this call.

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