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 theHamokEmitter
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.