@thefarce/ripple NPM

@thefarce/ripple

Drop something into the data pool and see its effects.

@thefarce/ripple is a flexible, lightweight pub/sub (publish-subscribe) module for Node.js, designed to facilitate event-driven programming by allowing components of your application to subscribe to events and react accordingly.

Features

Simple, intuitive API for publishing and subscribing to events.
Middleware support for pre-processing data in both publishing and subscribing pipelines.
Fully asynchronous, allowing for seamless integration with async/await patterns.
Lightweight with no external dependencies, perfect for small to medium-sized projects.

Installation

npm install @thefarce/ripple

Or, if you're using yarn:

yarn add @thefarce/ripple

Quick Start

Here's a quick example to get you started:

import { createPublisher, createSubscriber } from '@thefarce/ripple';

// Create a publisher for 'myNamespace'
const publisher = createPublisher('myNamespace');

// Create a subscriber for 'myNamespace'
const subscriber = createSubscriber('myNamespace');

// Define a callback function to handle events
const myCallback = (data) => {
  console.log('Event received:', data);
};

// Subscribe to the 'testEvent' with myCallback
subscriber('testEvent', [], myCallback);

// Publish an event
publisher('testEvent', { message: 'Hello World' });

Tutorial

Basic Usage

Publishing Events

To publish events, first create a publisher for a specific namespace:

const publisher = createPublisher('myNamespace');

Then, use this publisher to send events:

publisher('myEvent', { key: 'value' });

Subscribing to Events

Similarly, create a subscriber for a namespace:

const subscriber = createSubscriber('myNamespace');

Subscribe to events within this namespace:

subscriber('myEvent', [], (data) => {
  console.log('Event received:', data);
});

Advanced Usage

Using Middleware

Middleware functions can be used to pre-process data or perform actions at various stages of the event lifecycle.

const loggingMiddleware = async (ctx, next) => {
  console.log('Logging:', ctx.data);
  await next();
};

// Add middleware to publisher
const publisher = createPublisher('myNamespace', [loggingMiddleware]);

// Add middleware to subscriber
const subscriber = createSubscriber('myNamespace', [loggingMiddleware]);

Unsubscribing from Events

const unsubscribe = subscriber('myEvent', [], myCallback);

// Later, to unsubscribe:
unsubscribe();

Complex Scenarios

Describe more complex usage scenarios here, potentially including how to chain multiple middleware, error handling, or integration with other parts of a larger application.

Contributing

We welcome contributions to @thefarce/ripple!

Contribution guidelines: Commit clean code with full, good tests. Comment your code as needed.

License

This project is licensed under the Gratitude License, which states:

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

Any person and each member of any organization that distributes or uses the
software must continuously harbor, and occasionally feel, gratitude for it,
whether expressed or not.  Further, the object of that gratitude must be, at
least to a significant degree, the original developer of the software.