KinsonDigital.Carbonate 1.0.0-preview.15

Carbonate

!! NOTICE !!

This library is still under development and is not at v1.0.0 yet!! However, all of the major features are available, so we encourage you to use the library and provide feedback. That is what open source is all about. 🥳

📖 About Carbonate 📖

Carbonate is a messaging library built on the observable pattern, empowering seamless and dependable push-and-pull message handling across various parts or systems within an application. This fosters decoupling among different components, enhancing your application's overall testability. For a real-world example, check out the Velaptor code base which is an open source 2D game development framework. This library has been vital for decoupling the different sub-systems and making Velaptor testable. Go here for information on the observer pattern. This design pattern has been extensively covered in various tutorials and examples across the web, making it well-documented, widely recognized, and a highly popular programming pattern.

Note Click here to view all of the sample projects.

✨ Features & Benefits ✨

Features:

• Sends notifications of events with no data
• Sends notifications of events with data
• Sends notifications of events with data and returns data
• Interfaces and abstractions are provided for custom implementations and to provide testability Benefits:
• Increases decoupling
• Increases testability
• Sends data and events without needing to change the public API
• Promotes the Open/Closed Principle

💡 Examples 💡

Below are some examples to demonstrate some basic uses of Carbonate. This library is very flexible but how you use it depends on the needs of your application.

Non-directional push notifications

To send a non-directional push notification of something that has occurred, you can use the PushReactable type. The subscriber will use the ReceiveReactor type for subscriptions. The term Non-directional means that no data is being pushed out or returned from the notification call stack. This is great for sending a notification that an event has occurred when no data is needed.

var messenger = new PushReactable(); // Create the messenger object to push notifications
var msgEventId = Guid.NewGuid(); // This is the ID used to identify the event
// Subscribe to the event to receive messages
IDisposable unsubscriber = messenger.Subscribe(new ReceiveReactor(
eventId: msgEventId,
name: "my-subscription",
onReceive: () => Console.WriteLine("Received a message!"),
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
messenger.Push(msgEventId); // Will invoke all onReceive 'Actions'
unsubscriber.Dispose(); // Will only unsubscribe from this subscription

Every notification sent out contains a unique ID, which subscribers must use to receive the intended notification, ensuring its exclusivity and eliminating the need for additional logic with other subscriptions.

💡TIP💡 If you want to receive a single notification, unsubscribe from further notifications by calling the Dispose() method on the IDisposable object returned by the PushReactable object. All reactable objects return this object for unsubscribing at a later time.

new ReceiveReactor(
    eventId: msgEventId,
    onReceive: () =>
    {
       // Processing other required logic here . . .
       unsubscriber.Dispose(); // Will unsubscribe itself when receiving the notification
    });

Some notes about exceptions and unsubscribing

• Throwing an exception in the 'onReceive' action implementation will invoke the 'onError' action for ALL subscriptions.
• Invoking messenger.Dispose() will invoke the onUnsubscribe action for ALL subscriptions.
• You can unsubscribe from a single subscription by calling the Dispose() method on the IDisposable object returned by the reactable's Subscribe() method.

Uni-directional push notifications

To facilitate one-directional data transfer through push notifications, you can employ the PushReactable<T> type for sending data, while subscribers utilize the ReceiveReactor<T> type for their subscriptions. Setting up and using this approach follows the same steps as in the previous example. In this context, the term one-directional signifies that data exclusively flows outward with the push notification.

Note The ONLY difference with this example is that your sending some data WITH your notification. The generic parameter T is the type of data you are sending out. All other behaviors are the same.

var messenger = new PushReactable<string>(); // Create the messenger object to push notifications
var msgEventId = Guid.NewGuid(); // This is the ID used to identify the event
// Subscribe to the event to receive messages
IDisposable unsubscriber = messenger.Subscribe(new ReceiveReactor<string>(
eventId: msgEventId,
name: "my-subscription",
onReceiveData: (msg) => Console.WriteLine(msg),
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
messenger.Push("hello world!", msgEventId); // Will invoke all onReceive 'Actions'
messenger.Unsubscribe(msgEventId); // Will invoke all onUnsubscribe 'Actions'

Bi-directional push notifications

To enable bi-directional push notifications, allowing data to be sent out and received back, you can employ the PullReactable<T, T> type. Subscribers, on the other hand, utilize the RespondReactor<T, T> for their notification subscriptions. This approach proves useful when you need to send a push notification with data required by the receiver, who then responds with data back to the original caller that initiated the notification.

var favoriteGetter = new PullReactable<string, string>();
var msgEventId = Guid.NewGuid(); // This is the ID used to identify the event
var unsubscriber = favoriteGetter.Subscribe(new RespondReactor<string, string>(
respondId: msgEventId,
name: "adder",
onRespondData: (data) => data switch
{
"prog-lang" => "C#",
"food" => "scotch eggs",
"past-time" => "game development",
"music" => "hard rock/metal",
},
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
Console.WriteLine($"Favorite Language: {favoriteGetter.Pull("prog-lang", msgEventId)}");
Console.WriteLine($"Favorite Food: {favoriteGetter.Pull("food", msgEventId)}");
Console.WriteLine($"Favorite Past Time: {favoriteGetter.Pull("past-time", msgEventId)}");
Console.WriteLine($"Favorite Music: {favoriteGetter.Pull("music", msgEventId)}");

Note The difference between bi-directional and uni-directional notifications is that bi-directional notifications enable data exchange in both directions whereas uni-directional notifications enable data exchange in one direction which sends data out and does not expect data to be returned. 💡TIP💡 Most of the time, the PushReactable, PushReactable<T>, and PullReactable<string, string> types will suit your needs. However, But if you have any requirements that these can't provide, you can always create implementations of the interfaces provided.

🙏🏼 Contributing 🙏🏼

Interested in contributing? If so, click here to learn how to contribute your time or here if you are interested in contributing your funds via a one-time or recurring donation.

🔧 Maintainers 🔧

Calvin Wilkinson (KinsonDigital GitHub Organization - Owner) Kristen Wilkinson (KinsonDigital GitHub Organization - Documentation Maintainer & Tester)

🚔 Licensing and Governance 🚔

This software is distributed under the very permissive MIT license and all dependencies are distributed under MIT-compatible licenses. This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.