hermes 3.0.0

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.

3.0.0 #

  • Added FetchOperation.
  • Breaking change : Hermes.fetch - returns a FetchOperation instance now.

2.0.0 #

  • Breaking change : Hermes.send - return type changed from bool to void.

1.0.4 #

  • regression fix

1.0.3 #

  • Minor changes.

1.0.2 #

  • Minor fixes.

1.0.1 #

  • New implementation.

1.0.0 #

  • Initial version.

example/hermes_example.dart

/*
 * BSD 3-Clause License
 *
 * Copyright (c) 2019, Kennedy Tochukwu Ekeoha All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

import 'dart:cli' as cli;

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 op = Hermes.fetch<Message>((message) {
    print("Message received. it says: '${message.content}'");
  });

  // send a message
  Hermes.send<Message>(Message("Hello World!"));

  cli.waitFor(Future.delayed(Duration(seconds: 5)));

  Hermes.unfetch(op);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  hermes: ^3.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:hermes/hermes.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
45
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
72
Learn more about scoring.

We analyzed this package on Aug 18, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:hermes/hermes.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
Dev dependencies
pedantic ^1.0.0
test ^1.0.0