pubsub-api

pubsub-api is a type-safe topic-based Publish-Subscribe (PubSub) pattern implementation for TypeScript. Its lightweight design coupled with a simple API facilitates clean, decoupled architecture, allowing seamless communication across your application.

Features

• ⚡ Performance: Efficient subscription and unsubscription with minimal overhead.
• 🧩 Modularity: Seamlessly define, reuse, and extend your topics and message types across your application.
• ✨ Simple API: Straightforward and intuitive API for publishing and subscribing to topics.
• ✅ Type Safety: Strongly-typed topics and messages to ensure contract adherence and catch issues at compile-time.
• 🪶 Lightweight: Minimal footprint on your project's bundle size.
• ♻️ Zero Dependencies: Standalone library with no external dependencies.

Installation

Install pubsub-api via npm:

npm install pubsub-api --save

Or via yarn:

yarn add pubsub-api

Quick Start

// Import the pubSub function from the library
import { pubSub } from "pubsub-api";

// Create a PubSub instance
const pub = pubSub();

// Define a topic for like events
const likeTopic = pub.topic("like");

// Subscribe to the like topic to log like events
const unsubscribe = likeTopic.sub((likeData) => {
  console.log(`Post ID: ${likeData.postId}, was liked!`);
});

// Simulate a like event by publishing a message to the like topic
likeTopic.pub({ postId: "abc123" });

// Optionally unsubscribe later
unsubscribe();

This basic flow demonstrates the core functionalities of pubsub-api, helping you to set up a simple real-time messaging mechanism.

Usage

Defining Message and Topics Interfaces

In this section, we define interfaces for different types of notification events and create a PubSub instance for managing these events.

// Import the necessary functions from the library
import { pubSub } from "pubsub-api";

// Define the topics interface
interface Topics {
  newContact: string;
  newMessage: (message: string, sender: string, timestamp: number) => void;
  messageDeletion: [messageId: string];
}

// Create a PubSub instance for notification events
const notifier = pubSub<Topics>();

Subscribing to Topics

Here we demonstrate how to subscribe to different topics to receive and handle notification events.

// Subscribe to new message events to update UI
notifier.topic("newMessage").sub((message, sender, timestamp) => {
  console.log(
    `New message from ${sender} at ${new Date(timestamp)}: ${message}`,
  );
});

// Subscribe to new contact events to update UI
notifier.topic("newContact").sub((contactName) => {
  console.log(`New contact added: ${contactName}`);
});

// Subscribe to message deletion events to update UI
notifier.topic("messageDeletion").sub((messageId) => {
  console.log(`Message with ID ${messageId} was deleted.`);
});

Publishing to Topics

In this section, we simulate user interactions by publishing realistic events to the topics.

// Simulate user interactions by publishing events
notifier
  .topic("newMessage")
  .pub("Hey, are you coming to the meeting?", "Alice", Date.now());
notifier.topic("newContact").pub("Bob Johnson");
notifier.topic("messageDeletion").pub("msg1234567890");

Unsubscribing All Subscribers

You have the ability to unsubscribe all subscribers from a specific topic or from all topics in a PubSub instance using the unSubAll method.

// Unsubscribe all subscribers from a specific topic
notifier.topic("newMessage").unSubAll();
notifier.topic("newContact").unSubAll();
notifier.topic("messageDeletion").unSubAll();

// Unsubscribe all subscribers from all topics in the PubSub instance
notifier.unSubAll();

Advanced Usage

Creating Topics Separately

You can also create topics separately from the PubSub instance, either with or without specifying a type.

In this example, we create a topic for handling new group creation events, demonstrating how you can manage topics separately from a PubSub instance.

// Import the topic function from the library
import { topic } from "pubsub-api";

// Create a topic for new group events
const groups = topic<[groupName: string]>();

// Subscribe to new group events to update UI
groups.sub((groupName) => {
  console.log(`New group created: ${groupName}`);
});

// Simulate a new group creation event by publishing to the topic
groups.pub("Project Discussion");

Using Context with Subscribers

You can provide a context object when subscribing to a topic, which will be used as the this value when the subscriber function is called.

interface User {
    name: string;
}

const user: User = {
    name: 'Alice',
};

notifier.topic('newMessage').sub(function (message, sender, timestamp) {
    console.log(`${this.name} received a new message from ${sender} at ${new Date(timestamp)}: ${message}`);
}, user);

// Simulate user interactions by publishing events
notifier.topic('newMessage').pub('Hey, are you coming to the meeting?', 'Bob', Date.now());

One-Time Subscriptions

You can create a one-time subscription to a topic using the once method. The subscription will be automatically removed after the first message is received.

// Subscribe to new message events for a one-time notification
notifier.topic('newMessage').once((message, sender, timestamp) => {
    console.log(`One-time notification: New message from ${sender} at ${new Date(timestamp)}: ${message}`);
});

// Simulate user interactions by publishing events
notifier.topic('newMessage').pub('Hey, are you coming to the meeting?', 'Bob', Date.now());

Documentation

Currently, the documentation is being developed. However, you can find a couple of examples for each module within the library to get started. More comprehensive documentation will be provided in the near future.