From 43186807e97692b219338414b6bfaae173846994 Mon Sep 17 00:00:00 2001 From: SrGooglo Date: Wed, 26 Mar 2025 14:49:27 +0000 Subject: [PATCH] move docs --- docs/Server.md | 1 - docs/{Client.md => client/rtengine/client.md} | 133 ++---------------- docs/client/rtengine/topic-controller.md | 101 +++++++++++++ 3 files changed, 115 insertions(+), 120 deletions(-) delete mode 100644 docs/Server.md rename docs/{Client.md => client/rtengine/client.md} (61%) create mode 100644 docs/client/rtengine/topic-controller.md diff --git a/docs/Server.md b/docs/Server.md deleted file mode 100644 index 76ac08d..0000000 --- a/docs/Server.md +++ /dev/null @@ -1 +0,0 @@ -# Server diff --git a/docs/Client.md b/docs/client/rtengine/client.md similarity index 61% rename from docs/Client.md rename to docs/client/rtengine/client.md index 6d0a6d5..f079af8 100644 --- a/docs/Client.md +++ b/docs/client/rtengine/client.md @@ -1,12 +1,9 @@ -# Client - - [RTEngineClient](#rteenginclient) - -## RTEngineClient -### Overview +# RTEngineClient +## Overview `RTEngineClient` is a WebSocket client for real-time communication with backend services. It provides connection management, automatic reconnection, heartbeat monitoring, event handling, and topic-based subscriptions. -### API Reference -#### Constructor +## API Reference +### Constructor ```javascript const client = new RTEngineClient({ refName: "main", @@ -25,14 +22,14 @@ const client = new RTEngineClient({ | params.maxConnectRetries | number | Infinity | Maximum number of reconnection attempts | | params.heartbeat | boolean | true | Whether to use heartbeat to monitor connection health | -#### Static Properties +### Static Properties | Property | Type | Description | |----------|------|-------------| | version | string | Client library version | | heartbeatTimeout | number | Timeout for heartbeat checks (10000ms) | | reconnectTimeout | number | Delay between reconnection attempts (5000ms) | -#### State Object +### State Object The client state can be accessed via `client.state`: | Property | Type | Description | @@ -46,9 +43,9 @@ The client state can be accessed via `client.state`: | reconnecting | boolean | Whether the client is attempting to reconnect | | connectionRetryCount | number | Number of reconnection attempts made | -#### Methods +### Methods -##### connect() +#### connect() Establishes a connection to the WebSocket server. @@ -60,7 +57,7 @@ await client.connect(); |---------|-------------| | Promise | Resolves when the connection is established | -##### disconnect() +#### disconnect() Closes the current WebSocket connection. @@ -72,7 +69,7 @@ await client.disconnect(); |---------|-------------| | Promise | Resolves to false if no connection exists, true otherwise | -##### on(event, handler) +#### on(event, handler) Registers an event handler. @@ -87,7 +84,7 @@ client.on('message', (data) => { | event | string | Event name to listen for | | handler | Function | Function to call when the event is received | -##### off(event, handler) +#### off(event, handler) Removes an event handler. @@ -100,7 +97,7 @@ client.off('message', messageHandler); | event | string | Event name to stop listening for | | handler | Function | Handler function to remove | -##### once(event, handler) +#### once(event, handler) Registers a one-time event handler. @@ -115,7 +112,7 @@ client.once('connected', () => { | event | string | Event name to listen for | | handler | Function | Function to call once when the event is received | -##### emit(event, data) +#### emit(event, data) Sends an event to the WebSocket server. @@ -129,7 +126,7 @@ await client.emit('chat:message', { text: 'Hello!' }); | data | any | Data to send with the event | | Returns | Promise | Promise that resolves when the event is sent, or null if not connected | -### Topic Management +## Topic Management The client includes a `TopicsController` instance accessible via `client.topics`. @@ -177,105 +174,3 @@ await client.emit('user:status', { status: 'online' }); // Disconnect when done await client.disconnect(); ``` - -## TopicsController -### Overview -`TopicsController` is a utility class for managing topic-based subscriptions in real-time applications. It handles subscribing to topics, listening for specific events, and managing subscription lifecycles. - -### API Reference -#### Constructor -```javascript -const topicsController = new TopicsController(client); -``` - -| Parameter | Type | Description | -|-----------|------|-------------| -| client | Object | RTEngine client | - -#### Properties - -| Property | Type | Description | -|----------|------|-------------| -| subscribed | Set | Stores currently subscribed topics | - -#### Methods - -##### on(topic, event, callback) - -Registers a callback for a specific event on a given topic. - -```javascript -topicsController.on('chat/room1', 'message', (data, payload) => { - console.log('Message received:', data); -}); -``` - -| Parameter | Type | Description | -|-----------|------|-------------| -| topic | string | Topic to associate the event with | -| event | string | Name of the event to listen for | -| callback | Function | Function to execute when the event occurs on the topic | - -##### subscribe(topic) - -Subscribes to a specific topic. - -```javascript -await topicsController.subscribe('chat/room1'); -``` - -| Parameter | Type | Description | -|-----------|------|-------------| -| topic | string | Topic to subscribe to | -| Returns | Promise | Resolves to true when subscription is complete | - -##### unsubscribe(topic) - -Unsubscribes from a specific topic. - -```javascript -await topicsController.unsubscribe('chat/room1'); -``` - -| Parameter | Type | Description | -|-----------|------|-------------| -| topic | string | Topic to unsubscribe from | -| Returns | Promise | Resolves to true when unsubscription is complete | - -##### unsubscribeAll() - -Unsubscribes from all currently subscribed topics. - -```javascript -await topicsController.unsubscribeAll(); -``` - -| Returns | Promise | Resolves to true when all unsubscriptions are complete | - -##### regenerate() - -Refreshes all current subscriptions by unsubscribing and resubscribing. - -```javascript -await topicsController.regenerate(); -``` - -| Returns | Promise | Resolves to true when regeneration is complete | - -### Basic Usage Example - -```javascript -// Initialize -const topicsController = new TopicsController(realTimeClient); - -// Subscribe to a topic -await topicsController.subscribe('notifications'); - -// Listen for events on that topic -topicsController.on('notifications', 'new', handleNewNotification); - -// Clean up when done -await topicsController.unsubscribe('notifications'); -// Or unsubscribe from everything -await topicsController.unsubscribeAll(); -``` diff --git a/docs/client/rtengine/topic-controller.md b/docs/client/rtengine/topic-controller.md new file mode 100644 index 0000000..1d01066 --- /dev/null +++ b/docs/client/rtengine/topic-controller.md @@ -0,0 +1,101 @@ +# TopicsController +## Overview +`TopicsController` is a utility class for managing topic-based subscriptions in real-time applications. It handles subscribing to topics, listening for specific events, and managing subscription lifecycles. + +## API Reference +### Constructor +```javascript +const topicsController = new TopicsController(client); +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| client | Object | RTEngine client | + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| subscribed | Set | Stores currently subscribed topics | + +### Methods + +#### on(topic, event, callback) + +Registers a callback for a specific event on a given topic. + +```javascript +topicsController.on('chat/room1', 'message', (data, payload) => { + console.log('Message received:', data); +}); +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| topic | string | Topic to associate the event with | +| event | string | Name of the event to listen for | +| callback | Function | Function to execute when the event occurs on the topic | + +#### subscribe(topic) + +Subscribes to a specific topic. + +```javascript +await topicsController.subscribe('chat/room1'); +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| topic | string | Topic to subscribe to | +| Returns | Promise | Resolves to true when subscription is complete | + +#### unsubscribe(topic) + +Unsubscribes from a specific topic. + +```javascript +await topicsController.unsubscribe('chat/room1'); +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| topic | string | Topic to unsubscribe from | +| Returns | Promise | Resolves to true when unsubscription is complete | + +#### unsubscribeAll() + +Unsubscribes from all currently subscribed topics. + +```javascript +await topicsController.unsubscribeAll(); +``` + +| Returns | Promise | Resolves to true when all unsubscriptions are complete | + +#### regenerate() + +Refreshes all current subscriptions by unsubscribing and resubscribing. + +```javascript +await topicsController.regenerate(); +``` + +| Returns | Promise | Resolves to true when regeneration is complete | + +## Basic Usage Example + +```javascript +// Initialize +const topicsController = new TopicsController(realTimeClient); + +// Subscribe to a topic +await topicsController.subscribe('notifications'); + +// Listen for events on that topic +topicsController.on('notifications', 'new', handleNewNotification); + +// Clean up when done +await topicsController.unsubscribe('notifications'); +// Or unsubscribe from everything +await topicsController.unsubscribeAll(); +```