npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

realtime-pubsub-client

v1.0.0

Published

Realtime PubSub client for JavaScript/TypeScript

Downloads

4

Readme

Realtime Pub/Sub Client

The realtime-pubsub-client is a JavaScript client library for interacting with Realtime Pub/Sub 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.

Features

  • WebSocket Connection Management: Seamlessly connect and disconnect from the Realtime Pub/Sub service with automatic reconnection support.
  • Topic Subscription: Subscribe and unsubscribe to topics for receiving messages.
  • Topic Publishing: Publish messages to specific topics with optional message types and compression.
  • Message Sending: Send messages to backend applications with optional message types and compression.
  • Event Handling: Handle incoming messages with custom event listeners.
  • Acknowledgements and Replies: Wait for gateway acknowledgements or replies to messages with timeout support.
  • Error Handling: Robust error handling and logging capabilities.
  • TypeScript Support: Strongly typed classes for better development experience.

Installation

Install the realtime-pubsub-client library via npm:

npm install realtime-pubsub-client

Or via yarn:

yarn add realtime-pubsub-client

Getting Started

This guide will help you set up and use the realtime-pubsub-client library in your TypeScript or JavaScript project.

Connecting to the Server

First, import the RealtimeClient class and create a new instance with the required configuration:

import {
  RealtimeClient,
  ClientOptions,
  ConnectionInfo,
} from 'realtime-pubsub-client'

const APP_ID = 'your-app-id'

const clientOptions: ClientOptions = {
  websocketOptions: {
    // https://www.npmjs.com/package/reconnecting-websocket#available-options
    maxRetries: 10,
    urlProvider: async () => {
      // Implement getAuthToken according to your auth mechanism
      const ACCESS_TOKEN = await getAuthToken()

      return `wss://genesis.r7.21no.de/apps/${APP_ID}?access_token=${ACCESS_TOKEN}`
    },
  },
  // Optional: Pass a custom logger implementing the Logger interface
  logger: console,
}

const client = new RealtimeClient(clientOptions)

Connecting to the server and handling the session.started event:

client.on('session.started', (connectionInfo: ConnectionInfo) => {
  console.log('Connection ID:', connectionInfo.id)

  // subscribe to topics here
  client.subscribeRemoteTopic('topic1')
  client.subscribeRemoteTopic('topic2')
  // ...
})

await client.connect()
await client.waitFor('session.started')

Subscribing to incoming messages

You can handle messages for specific topics and message types:

Note: The topic and message type are separated by a dot (.) in the event name.

client.on('topic1.action1', (message: IncomingMessage) => {
  // message handling logic here
  console.log('Received message:', message.data.payload)
})

Wildcard subscriptions are also supported:

client.on('topic1.*', (message: IncomingMessage) => {
  // ...
})

Publishing Messages

Publish messages to a topic:

client.publish('topic1', 'Hello, world!', {
  messageType: 'text-message',
})

Responding to Incoming Messages

Set up event listeners to handle incoming messages:

client.on(
  'topic1.text-message',
  (message: IncomingMessage, reply: ReplyFunction) => {
    // ...

    // sending a reply
    reply('Message received!', 'ok')
  },
)

Waiting for Acknowledgements and Replies

  • waitForAck(timeout?: number): Waits for an acknowledgement of the message, with an optional timeout in milliseconds.
  • waitForReply(timeout?: number): Waits for a reply to the message, with an optional timeout in milliseconds.

Wait for the Realtime Gateway acknowledgement after publishing a message:

await client
  .publish('secure/peer-to-peer1', 'Hi', {
    messageType: 'greeting',
  })
  .waitForAck()

Wait for the Realtime Gateway acknowledgement after sending a message:

await client
  .send(
    {
      /*...*/
    },
    {
      messageType: 'create',
    },
  )
  .waitForAck()

Wait for a reply with a timeout:

await client
  .send(
    {
      /*...*/
    },
    {
      messageType: 'create',
    },
  )
  .waitForReply(5000) // Wait for up to 5 seconds

Error Handling

Handle errors and disconnections:

client.on('error', (error: Error) => {
  console.error('WebSocket error:', error)
})

client.on('close', (event: CloseEvent) => {
  console.log('WebSocket closed:', event.reason)
})

API Reference

RealtimeClient

Constructor

new RealtimeClient(config: ClientOptions);

Creates a new RealtimeClient instance.

  • config: Configuration options for the client.

Methods

  • connect(): Connects client to the WebSocket Messaging Gateway.

    async connect(): Promise<void>;

    Returns a promise that resolves when the connection is established.

  • disconnect(): Terminates the WebSocket connection.

    disconnect(): RealtimeClient;

    Returns the RealtimeClient instance.

  • subscribeRemoteTopic(topic: string): Subscribes connection to a remote topic.

    subscribeRemoteTopic(topic: string): RealtimeClient;

    Returns the RealtimeClient instance.

  • unsubscribeRemoteTopic(topic: string): Unsubscribes connection from a remote topic.

    unsubscribeRemoteTopic(topic: string): RealtimeClient;

    Returns the RealtimeClient instance.

  • publish(topic: string, payload: string | Record<string, any>, options?: MessageOptions): Publishes a message to a topic.

    publish(topic: string, payload: string | Record<string, any>, options?: MessageOptions): WaitForFactory;

    Returns a WaitForFactory instance to wait for acknowledgements or replies.

  • send(payload: string | Record<string, any>, options?: MessageOptions): Sends a message to the server.

    send(payload: string | Record<string, any>, options?: MessageOptions): WaitForFactory;

    Returns a WaitForFactory instance to wait for acknowledgements or replies.

  • wait(ms: number): Waits for a specified duration. Utility function for waiting in async functions.

    wait(ms: number): Promise<void>;

    Returns a promise that resolves after the specified time.

Events

  • 'session.started': Emitted when the session starts.

    client.on('session.started', (connectionInfo: ConnectionInfo) => { ... });
  • 'error': Emitted on WebSocket errors.

    client.on('error', (error: Error) => { ... });
  • 'close': Emitted when the WebSocket connection closes.

    client.on('close', (event: CloseEvent) => { ... });
  • Custom Events: Handle custom events based on topic and message type.

    client.on('TOPIC_NAME.MESSAGE_TYPE', (message: IncomingMessage, reply: ReplyFunction) => { ... });

    Wildcard subscriptions are also supported. See:

License

This library is licensed under the MIT License.


For more detailed examples and advanced configurations, please refer to the documentation.

Notes

  • Ensure that you have an account and an app set up with Realtime Pub/Sub.
  • Customize the urlProvider function to retrieve the access token for connecting to your realtime application.
  • Implement the getAuthToken function according to your authentication mechanism.
  • Optionally use the logger option to integrate with your application's logging system.
  • Handle errors and disconnections gracefully to improve the robustness of your application.
  • Make sure to handle timeouts when waiting for replies to avoid hanging operations.

Feel free to contribute to this project by submitting issues or pull requests on GitHub.