docs

docs/_config.yml

@@ -1,4 +1,4 @@
-remote_theme: pages-themes/minimal@v0.2.0
+remote_theme: pages-themes/architect@v0.2.0
 title: Hamok
 show_downloads: false
 plugins:

docs/emitter.md

@@ -0,0 +1,241 @@
+## User Manual
+[Hamok](./index.md) | HamokEmitter | [HamokMap](./map.md) | [HamokQueue](./queue.md) | [HamokRecord](./record.md)
+
+## Table of Contents
+* [Overview](#overview)
+* [API Reference](#api-reference)
+	* [Create a HamokEmitter instance](#create-a-hamokemitter-instance)
+	* [Configuration](#configuration)
+	* [Events](#events)
+	* [Properties](#properties)
+	* [Methods](#methods)
+* [Examples](#examples)
+* [FAQ](#faq)
+
+## 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.
+
+## API Reference `HamokEmitter<T extends HamokEmitterEventMap>`
+
+### Create a HamokEmitter instance
+
+To create a `HamokEmitter` instance, you need a `Hamok` instance. Here is how you can create a `HamokEmitter` instance:
+
+```typescript
+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.
+	 */
+	requestTimeoutInMs: 5000,
+
+	/**
+	 * Optional. The maximum waiting time in milliseconds for a message to be sent.
+	 * The storage holds back the message sending if Hamok is not connected to a grid or not part of a network.
+	 */
+	maxMessageWaitingTimeInMs: 50000,
+
+	/**
+	 * Optional. The maximum number of keys allowed in request or response messages.
+	 */
+	maxOutboundMessageKeys: 1000,
+
+	/**
+	 * Optional. The maximum number of values allowed in request or response messages.
+	 */
+	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.
+	 */
+	payloadsCodec?: Map<keyof T, { encode: (...args: unknown[]) => string, decode: (data: string) => unknown[] }>,
+});
+```
+
+### Configuration
+
+```typescript
+const emitter = hamok.createEmitter<MyEventMap>({
+	emitterId: 'exampleEmitter',
+});
+```
+
+### Events
+
+The `HamokEmitter` class emits event given the event keys defined in the `HamokEmitterEventMap`. Each event will pass the arguments defined in the event map to its listeners.
+
+```typescript
+await emitter.subscribe('myEvent', (message, count) => {
+  console.log(`Received: ${message} - ${count}`);
+});
+```
+
+### Properties
+
+- **id**: `string` - The unique identifier for the `HamokEmitter` instance.
+- **closed**: `boolean` - Indicates whether the emitter is closed.
+
+### Methods
+
+#### `close()`
+
+Closes the `HamokEmitter` instance, stopping all event subscriptions and communication.
+
+```typescript
+emitter.close();
+```
+
+#### `subscribe<K extends keyof T>(event: K, listener: (...args: T[K]) => void): Promise<void>`
+
+Subscribes a listener to an event.
+
+```typescript
+await emitter.subscribe('myEvent', (message, count) => {
+  console.log(`Received: ${message} - ${count}`);
+});
+```
+
+#### `unsubscribe<K extends keyof T>(event: K, listener: (...args: T[K]) => void): Promise<void>`
+
+Unsubscribes a listener from an event.
+
+```typescript
+await emitter.unsubscribe('myEvent', (message, count) => {
+  console.log(`Received: ${message} - ${count}`);
+});
+```
+
+#### `clear()`
+
+Clears all event subscriptions.
+
+```typescript
+emitter.clear();
+```
+
+#### `publish<K extends keyof T>(event: K, ...args: T[K]): void`
+
+Publishes an event to all subscribed listeners. 
+It returns a promise that resolves when the event is published on all remote peers subscribed to this event.
+
+```typescript
+await emitter.publish('myEvent', 'Hello, world!', 42);
+```
+
+#### `notify<K extends keyof T>(event: K, ...args: T[K]): void`
+
+Notifies all subscribed listeners of an event without waiting for the event to be published on remote peers.
+
+```typescript
+emitter.notify('myEvent', 'Hello, world!', 42);
+```
+
+
+#### `export(): HamokEmitterSnapshot`
+
+Exports the current state of the emitter, including all event subscriptions. (Used by the `Hamok` class to export the entire state of the Hamok instance.)
+
+```typescript
+const snapshot = emitter.export();
+console.log(snapshot);
+```
+
+#### `import(snapshot: HamokEmitterSnapshot): void`
+
+Imports a previously exported emitter state. (Used by the `Hamok` class to import the entire state of the Hamok instance.)
+
+```typescript
+emitter.import(snapshot);
+```
+
+## Examples
+
+ - [simple distributed emitter](../examples/src/emitter-example.ts)
+
+## FAQ
+
+### How do I create a HamokEmitter instance?
+
+To create a `HamokEmitter` instance, you need a `HamokConnection`. Here is an example:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+emitter.close();
+```
+
+### How do I clear all event subscriptions in a HamokEmitter?
+
+To clear all event subscriptions in a `HamokEmitter`, use the `clear` method:
+
+```typescript
+emitter.clear();
+```
+
+### How do I subscribe to an event?
+
+To subscribe to an event, use the `subscribe` method:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+emitter.publish('myEvent', 'Hello, world!', 42);
+```

docs/index.md

@@ -2,6 +2,7 @@
  Hamok | [HamokEmitter](./emitter.md) | [HamokMap](./map.md) | [HamokQueue](./queue.md) | [HamokRecord](./record.md)
 
 ## Table of Contents
+
 1. [Introduction](#introduction)
 2. [Installation](#installation)
 3. [Configuration](#configuration)

docs/map.md

@@ -260,8 +260,105 @@ map.import(snapshot);
 
 ## Examples
 
- - [use insert()]()
- - [use events]()
- - [use updateIf()]()
+ - [use insert](../examples/src/map-insert-get-example.ts)
+ - [use events](../examples/src/map-events-example.ts)
+ - [use updateIf](../examples/src/map-update-if-example.ts)
 
-## FAQ
+## FAQ
+
+## FAQ
+
+### How do I create a HamokMap instance?
+
+To create a HamokMap instance, you need a Hamok instance. Here is an example:
+
+```typescript
+const map = hamok.createMap<string, number>({
+	mapId: 'exampleMap',
+});
+```
+
+### What configuration options are available for HamokMap?
+
+When creating a HamokMap instance, you can configure various options, such as `mapId`, `requestTimeoutInMs`, `maxMessageWaitingTimeInMs`, `keyCodec`, `valueCodec`, `maxOutboundMessageKeys`, `maxOutboundMessageValues`, `baseMap`, and `equalValues`.
+
+### What events does HamokMap emit?
+
+HamokMap extends `EventEmitter` and emits the following events:
+
+- `insert`
+- `update`
+- `remove`
+- `clear`
+- `close`
+
+### How can I listen to HamokMap events?
+
+You can listen to HamokMap events using the `on` method. Here is an example:
+
+```typescript
+map.on('insert', (key, value) => console.log(`Inserted: ${key} -> ${value}`));
+map.on('update', (key, oldValue, newValue) => console.log(`Updated: ${key} from ${oldValue} to ${newValue}`));
+map.on('remove', (key, value) => console.log(`Removed: ${key} -> ${value}`));
+map.on('clear', () => console.log('Map cleared'));
+map.on('close', () => console.log('Map closed'));
+```
+
+### What properties are available in HamokMap?
+
+- **id**: `string` - The unique identifier for the HamokMap instance.
+- **closed**: `boolean` - Indicates whether the map is closed.
+- **size**: `number` - The number of entries in the map.
+- **isEmpty**: `boolean` - Indicates whether the map is empty.
+
+### How do I close a HamokMap instance?
+
+To close a HamokMap instance, use the `close` method:
+
+```typescript
+map.close();
+```
+
+### How do I clear all entries in a HamokMap?
+
+To clear all entries in a HamokMap, use the `clear` method:
+
+```typescript
+await map.clear();
+```
+
+### How do I retrieve a value for a given key?
+
+To retrieve a value for a given key, use the `get` method:
+
+```typescript
+const value = map.get('key1');
+console.log(value);
+```
+
+### How do I set a value for a given key?
+
+To set a value for a given key, use the `set` method:
+
+```typescript
+const oldValue = await map.set('key1', 'value1');
+console.log(oldValue);
+```
+
+### How do I insert a value for a given key?
+
+To insert a value for a given key, use the `insert` method:
+
+```typescript
+const existingValue = await map.insert('key1', 'value1');
+console.log(existingValue ? 'Insert failed, because the map already has a value for the key: ' + existingValue : 'Insert successful');
+```
+
+### How do I delete an entry for a given key?
+
+To delete an entry for a given key, use the `delete` method:
+
+```typescript
+const success = await map.delete('key1');
+console.log('Deleted', success ? 'successfully' : 'failed');
+```