# cluster-events

> Node's event emitter for cluster workers.

Latest version **1.1.5** (published 2019-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install cluster-events
pnpm add cluster-events
yarn add cluster-events
bun add cluster-events
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.5 |
| Published | 2019-09-15 |
| First published | 2018-11-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 8.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ayon Lee |
| Maintainers | hyurl |
| Keywords | events, event-emitter, event-dispatcher, listeners, cluster, child-process, workers, pub/sub, publisher/subscriber |

## Links

- npm: https://www.npmjs.com/package/cluster-events
- Repository: https://github.com/hyurl/cluster-events
- Homepage: https://github.com/hyurl/cluster-events#readme
- Issues: https://github.com/hyurl/cluster-events/issues
- npm.io page: https://npm.io/package/cluster-events

## Dependencies (1)

- [ipchannel](https://npm.io/package/ipchannel.md) ^0.2.8

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.1.5 (latest) — 2019-09-15
- 1.1.4 — 2019-09-11
- 1.1.3 — 2019-04-07
- 1.1.2 — 2019-02-20
- 1.1.1 — 2019-02-20
- 1.1.0 — 2019-01-29
- 1.0.1 — 2018-12-08
- 1.0.0 — 2018-11-29

## README

# Cluster Events

**Node's event emitter for cluster workers.**

Unlike traditional NodeJS EventEmitter, this module broadcasts the event to 
all worker processes forked by **cluster** or **child_process** (When forking 
via *child_process*, you must provide the same entry path for all the workers).

*This module doesn't rely on cluster and the master process, so it's perfect*
*using it while your program runs under PM2 supervision.*

## When will you need to broadcast an event?

Check this example, with traditional EventEmitter, when open the URL in a 
browser, you will only get data updated in one process, and the other three will
still holds the old data.

```javascript
import { EventEmitter } from "events";
import * as cluster from "cluster";
import * as os from "os";
import * as express from "express";

if (cluster.isMaster) {
    for (let i=0; i < os.cpus().length; i++) {
        cluster.fork();
    }
} else {
    var data = { counter: 0 };
    var emitter = new EventEmitter();
    var app = express();

    emitter.on("updateCounter", () => {
        data.counter++;
    });

    express.get("/update-counter", (req, res) => {
        // Only one process will emit this event and increase the counter.
        emitter.emit("updateCounter");
        res.send("OK");
    }).get("/get-counter", (req, res) => {
        // If there are 4 CPU cores, you have 3/4 of chance to get `0` and only
        // 1/4 of chance to get 1.
        res.send(data.counter);
    });

    express.listen(80);
}
```

Now let's use *cluster-events* to do the same job and compare.

```javascript
import { EventEmitter } from "cluster-events";
import * as cluster from "cluster";
import * as os from "os";
import * as express from "express";

if (cluster.isMaster) {
    for (let i=0; i < os.cpus().length; i++) {
        cluster.fork();
    }
} else {
    var data = { counter: 0 };
    var emitter = new EventEmitter("my-emitter"); // provide an unique ID
    var app = express();

    emitter.on("updateCounter", () => {
        data.counter++;
    });

    express.get("/update-counter", (req, res) => {
        // All processes will emit this event and increase the counter.
        emitter.emit("updateCounter");
        res.send("OK");
    }).get("/get-counter", (req, res) => {
        // No matter how many CPU cores are there, you will only get `1`.
        res.send(data.counter);
    });

    express.listen(80);
}
```

The only difference of usage is that EventEmitter of *cluster-events* requires 
an unique ID to identify the instance among all potential instances, and all 
other details are just the same, however your event will be emitted to all the 
listeners in all worker processes.

## Limits

Although this module allows you broadcasting the event, however, because the 
limitation of IPC communication, when you emit an event with some data, you can 
only pass the data that can be serialized via `JSON.stringify()`, any other 
types of data will be lost while transmission (Also, event names only 
accept strings in this module).

So it's your decision to use this module or the traditional NodeJS EventEmitter,
based on your needs.

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