{"id":19077891,"url":"https://github.com/backendstack21/realtime-pubsub-client","last_synced_at":"2026-02-22T14:19:15.101Z","repository":{"id":257780627,"uuid":"860061465","full_name":"BackendStack21/realtime-pubsub-client","owner":"BackendStack21","description":"The official Realtime Pub/Sub client for JavaScript/TypeScript","archived":false,"fork":false,"pushed_at":"2024-12-20T10:57:13.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-25T12:06:55.886Z","etag":null,"topics":["client","javascript","messaging","publish-subscribe","realtime","typescript","websocket"],"latest_commit_sha":null,"homepage":"https://realtime.21no.de/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BackendStack21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://www.paypal.me/kyberneees"}},"created_at":"2024-09-19T18:45:45.000Z","updated_at":"2024-12-20T10:57:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"e2bc3697-5aa2-469e-b365-2705287a3865","html_url":"https://github.com/BackendStack21/realtime-pubsub-client","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"bce7173ec19ad44122647acf5b91727e7660ee20"},"previous_names":["backendstack21/realtime-pubsub-client"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Frealtime-pubsub-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Frealtime-pubsub-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Frealtime-pubsub-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BackendStack21%2Frealtime-pubsub-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BackendStack21","download_url":"https://codeload.github.com/BackendStack21/realtime-pubsub-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251643273,"owners_count":21620463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","javascript","messaging","publish-subscribe","realtime","typescript","websocket"],"created_at":"2024-11-09T02:03:51.438Z","updated_at":"2025-10-20T05:59:08.548Z","avatar_url":"https://github.com/BackendStack21.png","language":"TypeScript","funding_links":["https://www.paypal.me/kyberneees"],"categories":[],"sub_categories":[],"readme":"# Realtime Pub/Sub Client\n\nThe `realtime-pubsub-client` is a JavaScript client library for interacting with [Realtime Pub/Sub](https://realtime.21no.de) applications. It enables developers to manage real-time WebSocket connections, handle subscriptions, and process messages efficiently. The library provides a simple and flexible API to interact with realtime applications, supporting features like publishing/sending messages, subscribing to topics, handling acknowledgements, and waiting for replies with timeout support.\n\n## Features\n\n- **WebSocket Connection Management**: Seamlessly connect and disconnect from the Realtime Pub/Sub service with automatic reconnection support.\n- **Topic Subscription**: Subscribe and unsubscribe to topics for receiving messages.\n- **Topic Publishing**: [Publish](https://realtime.21no.de/documentation/#publishers) messages to specific topics with optional message types and compression.\n- **Message Sending**: [Send](https://realtime.21no.de/documentation/#websocket-inbound-messaging) messages to backend applications with optional message types and compression.\n- **Event Handling**: Handle incoming messages with custom event listeners.\n- **Acknowledgements and Replies**: Wait for gateway acknowledgements or replies to messages with timeout support.\n- **Error Handling**: Robust error handling and logging capabilities.\n- **TypeScript Support**: Strongly typed classes for better development experience.\n\n## Installation\n\nInstall the `realtime-pubsub-client` library via npm:\n\n```bash\nnpm install realtime-pubsub-client\n```\n\nOr via yarn:\n\n```bash\nyarn add realtime-pubsub-client\n```\n\n## Getting Started\n\nThis guide will help you set up and use the `realtime-pubsub-client` library in your TypeScript or JavaScript project.\n\n### Connecting to the Server\n\nFirst, import the `RealtimeClient` class and create a new instance with the required configuration:\n\n```typescript\nimport {\n  RealtimeClient,\n  ClientOptions,\n  ConnectionInfo,\n} from 'realtime-pubsub-client'\n\nconst APP_ID = 'your-app-id'\n\nconst clientOptions: ClientOptions = {\n  websocketOptions: {\n    // https://www.npmjs.com/package/reconnecting-websocket#available-options\n    maxRetries: 10,\n    urlProvider: async () =\u003e {\n      // Implement getAuthToken according to your auth mechanism\n      const ACCESS_TOKEN = await getAuthToken()\n\n      return `wss://genesis.r7.21no.de/apps/${APP_ID}?access_token=${ACCESS_TOKEN}`\n    },\n  },\n  // Optional: Pass a custom logger implementing the Logger interface\n  logger: console,\n}\n\nconst client = new RealtimeClient(clientOptions)\n```\n\nConnecting to the server and handling the `session.started` event:\n\n```typescript\nclient.on('session.started', (connectionInfo: ConnectionInfo) =\u003e {\n  console.log('Connection ID:', connectionInfo.id)\n\n  // subscribe to topics here\n  client.subscribeRemoteTopic('topic1')\n  client.subscribeRemoteTopic('topic2')\n  // ...\n})\n\nawait client.connect()\nawait client.waitFor('session.started')\n```\n\n### Subscribing to incoming messages\n\nYou can handle messages for specific topics and message types:\n\n\u003e Note: The topic and message type are separated by a dot (.) in the event name.\n\n```typescript\nclient.on('topic1.action1', (message: IncomingMessage) =\u003e {\n  // message handling logic here\n  console.log('Received message:', message.data.payload)\n})\n```\n\nWildcard subscriptions are also supported:\n\n```typescript\nclient.on('topic1.*', (message: IncomingMessage) =\u003e {\n  // ...\n})\n```\n\n### Publishing Messages\n\nPublish messages to a topic:\n\n```typescript\nclient.publish('topic1', 'Hello, world!', {\n  messageType: 'text-message',\n})\n```\n\n### Responding to Incoming Messages\n\nSet up event listeners to handle incoming messages:\n\n```typescript\nclient.on(\n  'topic1.text-message',\n  (message: IncomingMessage, reply: ReplyFunction) =\u003e {\n    // ...\n\n    // sending a reply\n    reply('Message received!', 'ok')\n  },\n)\n```\n\n### Waiting for Acknowledgements and Replies\n\n- **waitForAck(timeout?: number)**: Waits for an acknowledgement of the message, with an optional timeout in milliseconds.\n- **waitForReply(timeout?: number)**: Waits for a reply to the message, with an optional timeout in milliseconds.\n\nWait for the Realtime Gateway acknowledgement after publishing a message:\n\n```typescript\nawait client\n  .publish('secure/peer-to-peer1', 'Hi', {\n    messageType: 'greeting',\n  })\n  .waitForAck()\n```\n\nWait for the Realtime Gateway acknowledgement after sending a message:\n\n```typescript\nawait client\n  .send(\n    {\n      /*...*/\n    },\n    {\n      messageType: 'create',\n    },\n  )\n  .waitForAck()\n```\n\nWait for a reply with a timeout:\n\n```typescript\nawait client\n  .send(\n    {\n      /*...*/\n    },\n    {\n      messageType: 'create',\n    },\n  )\n  .waitForReply(5000) // Wait for up to 5 seconds\n```\n\n### Error Handling\n\nHandle errors and disconnections:\n\n```typescript\nclient.on('error', (error: Error) =\u003e {\n  console.error('WebSocket error:', error)\n})\n\nclient.on('close', (event: CloseEvent) =\u003e {\n  console.log('WebSocket closed:', event.reason)\n})\n```\n\n## API Reference\n\n### RealtimeClient\n\n#### Constructor\n\n```typescript\nnew RealtimeClient(config: ClientOptions);\n```\n\nCreates a new `RealtimeClient` instance.\n\n- **config**: Configuration options for the client.\n\n#### Methods\n\n- **connect()**: Connects client to the WebSocket Messaging Gateway.\n\n  ```typescript\n  async connect(): Promise\u003cvoid\u003e;\n  ```\n\n  Returns a promise that resolves when the connection is established.\n\n- **disconnect()**: Terminates the WebSocket connection.\n\n  ```typescript\n  disconnect(): RealtimeClient;\n  ```\n\n  Returns the `RealtimeClient` instance.\n\n- **subscribeRemoteTopic(topic: string)**: [Subscribes](https://realtime.21no.de/documentation/#subscribers) connection to a remote topic.\n\n  ```typescript\n  subscribeRemoteTopic(topic: string): RealtimeClient;\n  ```\n\n  Returns the `RealtimeClient` instance.\n\n- **unsubscribeRemoteTopic(topic: string)**: [Unsubscribes](https://realtime.21no.de/documentation/#subscribers) connection from a remote topic.\n\n  ```typescript\n  unsubscribeRemoteTopic(topic: string): RealtimeClient;\n  ```\n\n  Returns the `RealtimeClient` instance.\n\n- **publish(topic: string, payload: string | Record\u003cstring, any\u003e, options?: MessageOptions)**: Publishes a message to a topic.\n\n  ```typescript\n  publish(topic: string, payload: string | Record\u003cstring, any\u003e, options?: MessageOptions): WaitForFactory;\n  ```\n\n  Returns a `WaitForFactory` instance to wait for acknowledgements or replies.\n\n- **send(payload: string | Record\u003cstring, any\u003e, options?: MessageOptions)**: Sends a message to the server.\n\n  ```typescript\n  send(payload: string | Record\u003cstring, any\u003e, options?: MessageOptions): WaitForFactory;\n  ```\n\n  Returns a `WaitForFactory` instance to wait for acknowledgements or replies.\n\n- **wait(ms: number)**: Waits for a specified duration. Utility function for waiting in async functions.\n\n  ```typescript\n  wait(ms: number): Promise\u003cvoid\u003e;\n  ```\n\n  Returns a promise that resolves after the specified time.\n\n#### Events\n\n- **'session.started'**: Emitted when the session starts.\n\n  ```typescript\n  client.on('session.started', (connectionInfo: ConnectionInfo) =\u003e { ... });\n  ```\n\n- **'error'**: Emitted on WebSocket errors.\n\n  ```typescript\n  client.on('error', (error: Error) =\u003e { ... });\n  ```\n\n- **'close'**: Emitted when the WebSocket connection closes.\n\n  ```typescript\n  client.on('close', (event: CloseEvent) =\u003e { ... });\n  ```\n\n- **Custom Events**: Handle custom events based on topic and message type.\n\n  ```typescript\n  client.on('TOPIC_NAME.MESSAGE_TYPE', (message: IncomingMessage, reply: ReplyFunction) =\u003e { ... });\n  ```\n\n  \u003e Wildcard subscriptions are also supported. See:\n\n## License\n\nThis library is licensed under the MIT License.\n\n---\n\nFor more detailed examples and advanced configurations, please refer to the [documentation](https://realtime.21no.de/docs).\n\n## Notes\n\n- Ensure that you have an account and an app set up with [Realtime Pub/Sub](https://realtime.21no.de).\n- Customize the `urlProvider` function to retrieve the access token for connecting to your realtime application.\n- Implement the `getAuthToken` function according to your authentication mechanism.\n- Optionally use the `logger` option to integrate with your application's logging system.\n- Handle errors and disconnections gracefully to improve the robustness of your application.\n- Make sure to handle timeouts when waiting for replies to avoid hanging operations.\n\n---\n\nFeel free to contribute to this project by submitting issues or pull requests on [GitHub](https://github.com/BackendStack21/realtime-pubsub-client).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackendstack21%2Frealtime-pubsub-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackendstack21%2Frealtime-pubsub-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackendstack21%2Frealtime-pubsub-client/lists"}