Signally

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

🚧 Warning: experimental package in pre-release phase (v0.0.x), breaking changes may occur! 🚧

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

   npm install signally

2. Add an event listener to your app

   import { addListener } from "signally";
   
   addListener("hello", message => {
     console.log("Received message:", message);
   });

3. Run your app
4. Send an event with Signally CLI command

   npx signally hello world

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

addListener(eventName: 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:

// 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);
});

Also creates a buffer directory (.signally) to the package root of the calling package.

removeListeners

removeListeners(eventName: string)

Removes all listeners added for given event name and removes the event's buffer directory.

Throws an error, if the given event name is not listened to.

removeAllListeners

removeAllListeners()

Removes all existing Signally listeners and removes up the entire buffer directory.

send

send(eventName: string, ...messages: string[])

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

Throws an error, if the given event name is not listened to.

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]

Signally CLI takes one or more arguments:

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

• Add .signally (buffer directory) to your .gitignore
• Signally has a package specific buffer directory, so installing it globally won't work
• 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 its buffer directory