events 0.1.2+1

A library for event handling in Dart.

Event handling library for Dart.

This project introduces a class to be used as a mixin to allow a class to act as an event emitter to which others can subscribe. Several event-related projects existed, but none of them offered the flexibility and simplicity that I wanted, so I created events.

Events uses built-in classes from dart:async to handle synchronicity. Event streams are represented as Stream objects and subscriptions as StreamSubscriptions. This allows users to perform additional operations like filtering or mapping on the incoming events.

Event type and data schemes

Several different schemes exist for event emitting, based on Java's or Node's most popular packages. This library supports several different options, without adding overhead to the use of it.

Firstly, events allows to use objects as events and subscribe based on the type of object emitted:

// to emit:
emitter.emit(new SuccessEvent());
// to subscribe:
emitter.on(SuccessEvent).listen((SuccessEvent e) => doStuff(e));

Secondly, you can also use objects or strings as event types, and provide additional data separately:

// to emit:
emitter.emit("success", new Result());
// to subscribe:
emitter.on("success").listen((Result r) => doStuff(r));

Thirdly, events provides a class EventType, that can be used to define custom event types and define the type of data that accompany the events (know that every object can be used as an event type, so this class is only indicative):

EventType Success = new EventType<Result>();
// to emit:
emitter.emit(Success, new Result());
// to subscribe:
emitter.on(Success).listen((Result r) => doStuff(r));

Shorthand notation

Because many libraries in other languages use a different, shorter notation, events provides this notation as well. Following statements are pairwise equivalent:

// subscribing
emitter.on(Success).listen(eventHandler);
emitter.on(Success, eventHandler);
// subscribing only to the first next event
emitter.once(Success).then(eventHandler);
emitter.once(Success, eventHandler);

You can also subscribe to all events from an event emitter as follows:

emitter.on().listen(eventHandler);

Unsubscribing and event streams

The on() subscription method normally returns a Stream object that contains all incoming events. You listen to it using the listen() method. listen() returns a StreamSubscription that is required to unsubscribe later.

Stream successStream = emitter.on(Success);
StreamSubscription successSubscription = successStream.listen((e) => handleSuccess(e));
// to cancel subscription:
successSubscription.cancel();

Using the shorthand notation, the on() method returns the StreamSubscription directly:

var sub = emitter.on(Success, (e) => handleSuccess(e));
// unsub:
sub.cancel();

One-time subscriptions return Future objects and are not cancellable.

Future onSuccess = emitter.once(Success);
onSuccess.then((e) => handleSuccess(e));
// or shorter:
Future f = emitter.once(Success, (e) => handleSuccess(e));
// the Future onSuccess and f above are the same future