Skip to content

xenoken/hermes

Repository files navigation

Messaging library for Dart. Nimble and efficient like the messenger of the Gods.

What is it

Hermes is a simple but powerful way to send and receive messages across a Dart App. For those who are experienced Publish/subscribe messaging and event subscriptions, Hermes's mechanism will look very familiar. One cool thing about Hermes is the ability to setup a pub\sub architecture with only two lines of code. Divine.

Hermes encapsulates the idea of event or signal (concept found in other messaging or eventing systems) with the loose concept of Message.

You can send a message from any position in your code. Hermes handles the task of carrying the message to all recipients that are waiting for the message.

In the same way you can send a Message from anywhere, You are able to receive a message sent from anywhere too.

For Hermes any object can act as a Message. Primitives, Functions, Built-in Types, Custom Types...Anything.

Hermes doesn't have the concept of registration. Everything is handled transparently. The moment your code wants to fetch a message, it automatically registers itself to receive it.

How to Use it

To send a message just call the send function.

Hermes.send<T>(message);
// or
Hermes.send(T message);

To receive a message just call the fetch function.

Hermes.fetch<T>(message, (T message){ });
// or
Hermes.fetch(T message, (T message){ });

Note that fetch acts like a transparent registration mechanism: when You call fetch the specified handler function will be called whenever a new message of type T arrives.

From version 3.0.0 fetch returns a FetchOperation instance. this object can be used to 'unfetch' and release resources:

Hermes.unfetch(FetchOperation op);

A simple usage example:

import 'package:hermes/hermes.dart';

class Message {
  final String content;
  Message(this.content);
}

main() {
  // registers a callback that is called when the message is received.
  var fetchOp = Hermes.fetch((Message message) {
    print("Message received. it says: '${message.content}'");
  });

  // send a message
  Hermes.send(Message("Hello World!"));
  
  // ... some code here...
  
  // unfetch the message if not required anymore.
  Hermes.unfetch(fetchOp);
}

Remarks

  • Hermes.send and Hermes.fetch are synchronous functions, but the message handler can be async.
  • Hermes.unfetch is an async function.

Features and bugs

Please file feature requests and bugs at the issue tracker.

Releases

No releases published

Packages

No packages published

Languages