KinsonDigital.Carbonate 1.0.0-preview.16

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 as well as separating cross cutting concerns. You can chose if you want data to flow out with the push notification, if data can be returned from a notification, both out and returned in one notification or no data being sent out or returned. 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 increasing it's testability. 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:

• Send push notifications with no data
• Send push notifications with data only going out
• Send push notifications with data only being returned
• Send push notifications with data going out and and being returned
• Interfaces and abstractions are provided for custom implementations and to provide testability Benefits:
• Increases decoupling
• Increases testability
• Works well with dependency injection
• Sends data and events without needing to change the public API of your library/project
• 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, you can use the PushReactable class. You subscribe using the Subscribe() method by sending in the subscription object. The term non-directional means that no data is being sent 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 subId = Guid.NewGuid(); // This is the ID used to identify the event
// Subscribe to the event to receive messages
IDisposable unsubscriber = messenger.Subscribe(new ReceiveSubscription(
id: subId,
onReceive: () => Console.WriteLine("Received a message!"),
name: "my-subscription",
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
messenger.Push(subId); // 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 with each subscription to ignore some notifications and accept others.

Note 💡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 Reactable object. All reactable objects return this object for unsubscribing at a later time.

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

Note Some notes about exceptions and unsubscribing**

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

One way push notifications

To facilitate one way data transfer through push notifications, you can employ the PushReactable<TIn> type for sending data, while subscribers utilize the ReceiveSubscription<TIn> 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 subId = Guid.NewGuid(); // This is the ID used to identify the event
// Subscribe to the event to receive messages
IDisposable unsubscriber = messenger.Subscribe(new ReceiveSubscription<string>(
id: subId,
onReceive: (msg) => Console.WriteLine(msg),
name: "my-subscription",
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
messenger.Push("hello world!", subId); // Will invoke all onReceive 'Actions'
messenger.Unsubscribe(subId); // Will invoke all onUnsubscribe 'Actions'

Two way push notifications

To enable two way push notifications, allowing data to be sent out and returned, you can employ the PushPullReactable<TIn, TOut> type. Subscribers, on the other hand, utilize the RespondSubscription<TIn, TOut> 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 favoriteMessenger = new PushPullReactable<string, string>();
var subId = Guid.NewGuid(); // This is the ID used to identify the event
var unsubscriber = favoriteMessenger.Subscribe(new RespondSubscription<string, string>(
respondId: subId,
onRespond: (data) => data switch
{
"prog-lang" => "C#",
"food" => "scotch eggs",
"past-time" => "game development",
"music" => "hard rock/metal",
},
name: "favorites",
onUnsubscribe: () => Console.WriteLine("Unsubscribed from notifications!"),
onError: (ex) => Console.WriteLine($"Error: {ex.Message}")
));
Console.WriteLine($"Favorite Language: {favoriteMessenger.Pull("prog-lang", subId)}");
Console.WriteLine($"Favorite Food: {favoriteMessenger.Pull("food", subId)}");
Console.WriteLine($"Favorite Past Time: {favoriteMessenger.Pull("past-time", subId)}");
Console.WriteLine($"Favorite Music: {favoriteMessenger.Pull("music", subId)}");

Note The difference between one way and two way notifications is that one way notifications enable data travel in one direction whereas two way notifications enable data exchange in both directions which sends data out. The terms 'Push' and 'Pull' should give a clue as to the direction of travel of the data. Note 💡TIP💡 Most of the time, the PushReactable, PushReactable<TIn>, and PullReactable<TIn, TOut> types will suit your needs. However, if you have any requirements that these can't provide, you can always create your own custom 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 - Project Management, Documentation, 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.