# signally

> Send messages to running Node processes

Latest version **0.0.3** (published 2018-09-02) · ISC license · 0 weekly downloads

## Install

```sh
npm install signally
pnpm add signally
yarn add signally
bun add signally
```

Provides the command `signally`.

## Health

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

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

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2018-09-02 |
| First published | 2018-09-01 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Joona Laamanen |
| Maintainers | jlaamanen |
| Keywords | event, message, runtime, node |

## Links

- npm: https://www.npmjs.com/package/signally
- Repository: https://github.com/jlaamanen/signally
- Homepage: https://github.com/jlaamanen/signally#readme
- Issues: https://github.com/jlaamanen/signally/issues
- npm.io page: https://npm.io/package/signally

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

- 0.0.3 (latest) — 2018-09-02
- 0.0.2 — 2018-09-01
- 0.0.1 — 2018-09-01

## README

# Signally

Send messages to your Node process on the run with Signally! ⚡️

[![Published on npm](https://img.shields.io/npm/v/signally.svg)](https://www.npmjs.com/package/signally)

## Why?

Node doesn't offer a nice and simple way to send events or messages to running Node processes out-of-the-box.

## How?

1. Install Signally
    ```sh
    npm install signally
    ```
2. Add an event listener to your app
    ```ts
    import { addListener } from "signally";

    addListener("hello", message => {
      console.log("Received message:", message);
    });
    ```
3. Run your app
4. Send an event with Signally CLI command
    ```sh
    signally hello world
    ```
    ```sh
    # Node process output:
    Received message: world
    ```

## Under the hood

Signally uses a simple file watching message queue to watch for new events. Each new event from Signally CLI will be added as a new file in buffer directory. Whenever a new file appears in the directory while an app with registered listeners is running, it will be read and parsed by the file watcher. All the listeners attached to the event are handled, and after this, the file is removed.

## API

### addListener

```ts
addListener(event: string, callback: (...messages: string[]) => void)
```

Adds a listener for given event name. When an event with given name is received, the callback is invoked with the messages as arguments.

Example:
```ts
// event with one message
addListener("some-event", message => {
  console.log("Received a message:", message);
});

// event with two messages
addListener("another-event", (first, second) => {
  console.log("Received two messages:", first, second);
});

// handle all sent messages
addListener("exhaustive-event", (...messages) => {
  console.log("Received messages:", messages);
});
```

### send

```ts
send(event: string, ...messages: string[])
```

Send an event by adding a new file in the buffer directory.

Used by the CLI command, but can also be imported and invoked programmatically.

## CLI

You can use the Signally CLI via:
* npm scripts in `package.json`
* `npx signally [arguments]`
* installing globally with `npm i -g signally` (not recommended)

Signally CLI takes one or more arguments:
```sh
signally <event> [<message1> <message2> ...]
```
* **event** (required)
  * type: string
  * describes the event name
* **messages**
  * each of type string
  * the actual payload of the event

## Tips & tricks

* To avoid having to install Signally globally, prefer `npx` or npm scripts
* Remember to wrap messages in quotation marks when needed (depending on your terminal)
* To allow Signally to clean up properly, call `process.exit()` on signals like `SIGINT` (Ctrl + C)
  * Signally contains a handler for the `exit` event for clearing up and removing the `.signally` buffer directory

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