TypedBus (tB)

TypedBus

TypedBus (tB) and TypedBusEvents (tBE) provide a powerful, type-safe event bus for Dart applications. With TypedBus, you can publish and subscribe to strongly-typed events, ensuring safe communication between system components.

This library offers compile-time and runtime safety, allowing developers to write clean and predictable event-driven code.

Features

  • 🎯 Type-Safe Event Handling: Events are tied to specific data types, ensuring only valid payloads are passed.
  • ⚡ Dynamic Event Registration: Register new events and their types dynamically using TBE.
  • 🔔 Subscription Management: Subscribe to events and listen to typed data.
  • 📤 Publish Events: Publish strongly-typed events globally.
  • 🛡️ Error Handling: Protects against mismatched event types during publishing and subscribing.

Installation

Add the package to your pubspec.yaml:

dependencies:
  typed_bus: ^0.0.8

Then fetch the package:

flutter pub get

Getting Started

1. Register Events

Before publishing or subscribing, register events and their expected payload types using tBE.registerEvent:

tBE.registerEvent<String>('event1');

2. Subscribe to Events

Use tB.subscribe to listen for specific events. Subscribers receive only the payloads of the registered type:

tB.subscribe<String>('event1').listen((String data) {
  print('Received Event 1: $data');
});

3. Publish Events

Use tB.publish<T> to send events globally with their corresponding payloads:

tB.publish<String>('event1', "Hello world!");

4. Error Handling

If you attempt to publish or subscribe with mismatched types, the library will throw a runtime exception. Be cautious with types, especially when using generics like Map.

Example of a Mismatched Type

tB.publish<String>('action3', SomethingCrazy(
  options: {},
  option1: true,
  option2: false,
  option3: true,
  option4: false,
));
// Throws an exception: Type mismatch

API Reference

TypedBusEvents (TBE)

Register an Event

tBE.registerEvent<T>(String event);
  • Registers a new event with the specified payload type <T>.

Example

tBE.registerEvent<String>('my_event');

TypedBus (TB)

Subscribe to an Event

Stream<T> tB.subscribe<T>(String event);
  • Subscribes to an event and listens for payloads of type <T>.

Publish an Event

void tB.publish<T>(String event, T data);
  • Publishes an event globally with the given payload.

Example Usage

import 'package:typed_bus/typed_bus.dart';


void main() {
  // Register events
  tBE.registerEvent<String>('eventName');

  // Subscribe to events
  tB.subscribe<String>('eventName').listen((data) {
    print('Received eventName: $data');
  });

  tB.publish<String>('eventName', 'Hello world!');  
}

Advanced Usage

Custom Types

For events with a custom type, just use it.

Define your custom type

class TodoItem {
  String description;
  bool isDone;

  TodoItem({required this.description, required this.isDone});

  @override
  String toString() {
    return 'TodoItem(description: $description, isDone: $isDone)';
  }
}

Use your custom type


tBE.registerEvent<TodoItem>("toggle");

tB.subscribe<TodoItem>('toggle').listen((TodoItem item) {
  // do something with the item
  toggleItem(item);
});

tB.publish<TodoItem>(
    'toggle', TodoItem(description: "Publish Toggle Event", isDone: false));

Dynamic Payloads

For events where the payload type isn’t fixed, you can use dynamic:

tBE.registerEvent<dynamic>('dynamic_event');

tB.subscribe<dynamic>('dynamic_event').listen((data) {
  print('Dynamic event received: $data');
});

tB.publish<dynamic>('dynamic_event', {'key': 'value'});
tB.publish<dynamic>('dynamic_event', 12345);

License

This project is licensed under the MIT License.

Conclusion

TypedBus and TypedBusEvents provide a robust way to handle event-driven communication in Dart applications. The library’s focus on type safety ensures your events are predictable and easy to debug.

For questions or contributions, feel free to open an issue or create a pull request!

Libraries

typed_bus
typed_bus/typed_bus
typed_bus/typed_bus_events