Hamok

https://www.hamok.dev

View project on GitHub

User Manual

Hamok / HamokEmitter / HamokMap / HamokQueue / HamokRecord / HamokRemoteMap

Table of Contents

Overview

HamokEmitter is a class that provides a mechanism for managing distributed event subscriptions and publishing events across multiple nodes in a distributed system. It integrates with HamokConnection for communication and uses EventEmitter for event handling.

Create a HamokEmitter instance

To create a HamokEmitter instance, you need a Hamok instance. Here is how you can create a HamokEmitter instance:

const emitter = hamok.createEmitter<MyEventMap>({
  emitterId: "exampleEmitter",
});

Configuration

type MyEventMap = {
  myEvent: [string, number];
};
const emitter = hamok.createEmitter<MyEventMap>({
  /**
   * The unique identifier for the emitter.
   */
  emitterId: "exampleEmitter",

  /**
   * Optional. The timeout duration in milliseconds for requests.
   *
   * DEFAULT: 5000
   */
  requestTimeoutInMs: 5000,

  /**
   * Optional. The maximum number of keys allowed in request or response messages.
   *
   * DEFAULT: 0 means infinity
   */
  maxOutboundMessageKeys: 1000,

  /**
   * Optional. The maximum number of values allowed in request or response messages.
   *
   * DEFAULT: 0 means infinity
   */
  maxOutboundMessageValues: 100,

  /**
   * Optional. A map of payload codecs for encoding and decoding event payloads.
   * The key is an event type, and the value is a codec for that event type.
   *
   * DEFAULT: JSON codec
   */
  payloadsCodec: Map<
    keyof MyEventMap,
    {
      encode: (...args: unknown[]) => string;
      decode: (data: string) => unknown[];
    }
  >,
});

API Reference

HamokEmitter<T extends HamokEmitterEventMap> Class

A class for managing events and subscriptions in a distributed system.

Properties

  • id: string - The unique identifier of the emitter.
  • closed: boolean - Indicates whether the emitter is closed.
  • connection: HamokConnection<string, string> - The connection used by the emitter.
  • payloadsCodec: Map<keyof T, { encode: (...args: unknown[]) => string, decode: (data: string) => unknown[] }> - Optional codec for encoding and decoding payloads.
  • ready: Promise<void> - A promise that resolves when the emitter is initialized and ready to use.

Methods

  • close(): void - Closes the emitter and releases any held resources.
  • subscribe(`event: K`, `listener: (...args: T[K]) => void`): `Promise` - Subscribes a listener to an event.
  • unsubscribe(`event: K`, `listener: (...args: T[K]) => void`): `Promise` - Unsubscribes a listener from an event.
  • clear(): void - Clears all subscriptions and listeners.
  • publish(`event: K`, `...args: T[K]`): `Promise<string[]>` - Publishes an event to all subscribed listeners.
  • notify(`event: K`, `...args: T[K]`): `void` - Notifies all subscribed listeners of an event.
  • export(): HamokEmitterSnapshot - Exports the current state of the emitter.
  • import(snapshot: HamokEmitterSnapshot): void - Imports the state from a snapshot.

Events

  • InsertEntriesRequest: Manages subscription and adds the source endpoint to the list.
  • RemoveEntriesRequest: Manages subscription and removes the source endpoint from the list.
  • UpdateEntriesRequest: Emits events with decoded payloads.
  • UpdateEntriesNotification: Emits events with decoded payloads.
  • ClearEntriesNotification: Manages subscription and removes the source endpoint from the list.
  • remote-peer-removed: Removes the remote peer from all subscriptions.
  • close: Closes the emitter and removes all listeners.

Example Usage

const emitter = new HamokEmitter(connection, payloadsCodec);

emitter.subscribe("event", (data) => {
  console.log(`Received data: ${data}`);
});

emitter.publish("event", "sample data").then((peerIds) => {
  console.log(`Event published to peers: ${peerIds}`);
});

emitter.unsubscribe("event", (data) => {
  console.log(`Unsubscribed from event`);
});

emitter.close();

Examples

FAQ

How do I create a HamokEmitter instance?

To create a HamokEmitter instance, you need a HamokConnection. Here is an example:

const connection = new HamokConnection("my-storage-id");
const emitter = new HamokEmitter<MyEventMap>(connection);

What configuration options are available for HamokEmitter?

When creating a HamokEmitter instance, you can optionally pass a payloadsCodec for encoding and decoding event payloads. The payloadsCodec is a map where each event key maps to an object with encode and decode functions.

What events does HamokEmitter emit?

HamokEmitter extends EventEmitter and emits events based on the event keys defined in the HamokEmitterEventMap. Each event will pass the arguments defined in the event map to its listeners.

How can I listen to HamokEmitter events?

You can listen to HamokEmitter events using the on method. Here is an example:

emitter.on("myEvent", (message, count) => {
  console.log(`Received: ${message} - ${count}`);
});

What properties are available in HamokEmitter?

  • id: string - The unique identifier for the HamokEmitter instance.
  • closed: boolean - Indicates whether the emitter is closed.

How do I close a HamokEmitter instance?

To close a HamokEmitter instance, use the close method:

emitter.close();

How do I clear all event subscriptions in a HamokEmitter?

To clear all event subscriptions in a HamokEmitter, use the clear method:

emitter.clear();

How do I subscribe to an event?

To subscribe to an event, use the subscribe method:

await emitter.subscribe("myEvent", (message, count) => {
  console.log(`Received: ${message} - ${count}`);
});

How do I unsubscribe from an event?

To unsubscribe from an event, use the unsubscribe method:

await emitter.unsubscribe("myEvent", (message, count) => {
  console.log(`Received: ${message} - ${count}`);
});

How do I publish an event?

To publish an event, use the publish method:

emitter.publish("myEvent", "Hello, world!", 42);

What is the difference between the publish and notify methods?

The publish method publishes an event to all subscribed listeners and waits for the event to be published on remote peers. then return a promise that resolves when the event is published on all remote peers subscribed to this event.

The notify method notifies all subscribed listeners of an event without waiting for the event to be published on remote peers.

In short use notify for fire and forget messages, and use publish for messages that need to be checked if it is delivered to the target remote peers.

How many subscribers can a HamokEmitter have for one event?

A HamokEmitter can have an unlimited number of subscribers for each event on any peer. The underlying EventEmitter implementation used in HamokEmitter has no limit on the number of listeners for an event. To distribute the event to the remote peers subscribed to the event, the HamokEmitter uses the Raft consensus algorithm to ensure that the subscription is consistent across all peers.

What is the payloadsCodec for?

The payloadsCodec is a map of payload codecs for encoding and decoding event payloads. The key is an event type, and the value is a codec for that event type. This is useful for customizing the encoding and decoding of event payloads, if you are for example unsatisfied with the default JSON encoding/decoding.