Simple Topics

Overview

This project is a lightweight TypeScript library that implements an event-driven architecture inspired by RxJS concepts. The central concept revolves around topics and listeners that allow for the effective handling of events, errors, and communication between different parts of an application.

| Class Name | Description | RxJS equivalent | |-------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------| | Reaction | A empty callback function to react when Topics end. | Complete callback | | EventReaction<T> | A callback function to react over facts or errors. | Next/Error callback | | Listener<T> | Responsible for reacting to events of type T, handling errors, and executing final actions. | Observer | | Topic<T> | A simple read-only Topic in which listeners can only wait for facts and errors as espectators. | Observable | | Attention<T> | Bounds the Topic and Listener in a common object. Can be used to make a Listener to leave the Topic. | Subscription | | CasualTopic<T> | A specific implementation of a topic that allows continuous information sharing until dismissed. | Subject | | LongTopic<T> | A specialized CasualTopic to keep a history of facts recapitulated to new Listeners when joining. | ReplaySubject(MAX) | | LimitedTopic<T> | A specialized LongTopic that enforces a limit on the number of facts retained for recapitulation. | ReplaySubject(x) | | SimpleTopic<T> | A basic LimitedTopic that retains for recapitulation only one fact. | ReplaySubject(1) | | InitialTopic<T> | A basic LimitedTopic that retains for recapitulation only one initialized fact. | BehaviorSubject | | TopicChain<T> | A class that takes a given Topic and, upon receiving facts, transform them into another fact or even another Topic. | Observable.pipe() | | Topic.toPromise() | Converts a given topic into a promise and takes the first told fact to resolve it. | firstValueFrom() | | TopicUtil.trust() | Converts a given promise into a topic and takes the first fact to tell through it. | from() | | TopicUtil.meeting() | Takes a list of topics of the same type and reacts to all united facts when all topics are dismissed. | forkJoin() |

Usage

Here's a sample usage demonstrating how to set up listeners and topics:

const myTopic: CasualTopic<string> = new CasualTopic<string>();
const attention: Attention<string> = myTopic.listen(
	(fact: string) => console.log(`Received fact: ${fact}`), // mandatory
	(error) => console.error(`Error: ${error.message}`), // optional
	() => console.log('No more facts to share.') // optional
);
myTopic.tell('This is my first fact.');
myTopic.alert(new Error('This is an error.'));
myTopic.tellAtLast('This is the last fact.');
/*
Results:

Received fact: This is my first fact.
Error: This is an error.
Received fact: This is the last fact.
No more facts to share.
*/

Buffering

Facts and errors are buffered inside a Topic before being redistributed to listeners. Nested tell(), alert(), tellAtLast() and alertAtLast() calls into Listener callbacks are put on wait queue since there's already a listener update going on. Beware that some uses of nested telling/alerting can lead to infinite loops.

Error Handling

To handle errors gracefully, listeners can provide a recovery callback during registration. This allows the topic to notify the listener of any issues that arise during normal operations.

Errors are not throw, neither do they stop the app flow.

• Like facts, errors are buffered before redistribution to listeners
• Unlike facts, errors are not kept in a history in LongTopic and its derived classes.