@equinor/fusion-framework-module-signalr 10.0.1 → 11.0.0

package/src/SignalRModuleProvider.ts

@@ -5,26 +5,79 @@ import type { SignalRConfig } from './SignalRModuleConfigurator';
 
 import { Topic } from './lib/Topic';
 
+/**
+ * Public interface for the SignalR module provider.
+ *
+ * Use {@link ISignalRProvider.connect} to subscribe to a named hub method
+ * through an RxJS-based {@link Topic}. Connections are reference-counted
+ * and automatically torn down when all subscribers unsubscribe.
+ */
 export interface ISignalRProvider {
   /**
-   * connect to SignalR hub
-   * re-use existing connections and close connection when nobody is listening
+   * Connect to a SignalR hub method and return an observable {@link Topic}.
+   *
+   * Existing hub connections are reused (shared via `shareReplay` with
+   * `refCount`). When the last subscriber unsubscribes, the underlying
+   * `HubConnection` is stopped automatically.
+   *
+   * @template T - Type of messages received from the hub method
+   * @param hubId - Name of the hub as registered in the configurator
+   * @param methodName - Server-side method name to listen on
+   * @returns A {@link Topic} observable that emits messages from the hub method
+   *
+   * @example
+   * ```ts
+   * const provider = modules.signalR;
+   * const topic = provider.connect<MyMessage>('notifications', 'OnNewMessage');
+   * topic.subscribe((msg) => console.log('Received:', msg));
+   * ```
    */
-  connect<T>(ubId: string, methodName: string): Topic<T>;
+  connect<T>(hubId: string, methodName: string): Topic<T>;
 }
 
+/**
+ * Default {@link ISignalRProvider} implementation.
+ *
+ * Creates and manages `@microsoft/signalr` `HubConnection` instances based on
+ * the resolved {@link SignalRConfig}. Hub connections are lazily created on
+ * first subscription and shared across all callers via `shareReplay`.
+ */
 export class SignalRModuleProvider implements ISignalRProvider {
   #config: SignalRConfig;
   #hubConnections: Record<string, Observable<HubConnection>> = {};
 
+  /**
+   * @param config - Resolved SignalR configuration containing all registered hubs
+   */
   constructor(config: SignalRConfig) {
     this.#config = config;
   }
 
+  /**
+   * Connect to a named hub method and return an observable {@link Topic}.
+   *
+   * @template T - Type of messages received from the hub method
+   * @param hubId - Name of the hub as registered in the configurator
+   * @param methodName - Server-side method name to listen on
+   * @returns A {@link Topic} observable emitting hub messages
+   * @throws {Error} When no hub configuration exists for `hubId`
+   */
   public connect<T>(hubId: string, methodName: string): Topic<T> {
     return new Topic<T>(methodName, this._createHubConnection(hubId));
   }
 
+  /**
+   * Create or retrieve a shared `HubConnection` observable for the given hub.
+   *
+   * The connection is lazily built using `HubConnectionBuilder` and shared
+   * with `shareReplay({ bufferSize: 1, refCount: true })` so that:
+   * - New subscribers immediately receive the current connection.
+   * - The connection is stopped when the last subscriber unsubscribes.
+   *
+   * @param hubId - Name of the hub as registered in the configurator
+   * @returns Observable that emits the active `HubConnection`
+   * @throws {Error} When no hub configuration exists for `hubId`
+   */
   protected _createHubConnection(hubId: string): Observable<HubConnection> {
     const LOG_LEVEL_CRITICAL = 5;
 
@@ -54,12 +107,13 @@ export class SignalRModuleProvider implements ISignalRProvider {
         })
         .catch((error: unknown) => {
           if (error instanceof AbortError) {
-            // Omit AbortError
+            // AbortError is expected during teardown — safe to ignore
           } else {
             throw error;
           }
         });
 
+      // Stop the connection and clean up the cache entry on unsubscribe
       const teardown = () => {
         connection.stop();
         observer.complete();

package/src/index.ts

@@ -1,3 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * Fusion Framework module for real-time communication via
+ * [SignalR](https://learn.microsoft.com/aspnet/core/signalr/introduction).
+ *
+ * Provides an RxJS-based API for connecting to SignalR hubs, subscribing to
+ * server-side methods, and sending messages. Hub connections are reference-counted
+ * and automatically stopped when no subscribers remain.
+ *
+ * @see {@link enableSignalR} for the quickest way to register the module.
+ * @see {@link ISignalRProvider.connect} for subscribing to hub methods at runtime.
+ */
+
 export {
   ISignalRConfigurator,
   SignalRConfigurator,

package/src/lib/Topic.ts

@@ -1,9 +1,35 @@
 import type { HubConnection } from '@microsoft/signalr';
 import { Observable } from 'rxjs';
 
+/**
+ * RxJS Observable wrapper around a SignalR hub method.
+ *
+ * A `Topic` subscribes to a named method on a `HubConnection` and emits
+ * incoming messages as observable values. It also exposes {@link Topic.send}
+ * and {@link Topic.invoke} for sending messages back to the server.
+ *
+ * Created by {@link SignalRModuleProvider.connect} — consumers typically
+ * do not instantiate `Topic` directly.
+ *
+ * @template T - Type of messages received from the hub method
+ *
+ * @example
+ * ```ts
+ * const topic = provider.connect<ChatMessage>('chat', 'ReceiveMessage');
+ * topic.subscribe((msg) => console.log(msg.text));
+ *
+ * // Send a message to the server on the same method
+ * topic.send('Hello, world!');
+ * ```
+ */
 export class Topic<T> extends Observable<T> {
+  /** The active hub connection, set once the connection observable emits. */
   connection: HubConnection | undefined;
 
+  /**
+   * @param topic - Server-side method name to listen on and send to
+   * @param hubConnection - Observable that emits the active `HubConnection`
+   */
   constructor(
     public topic: string,
     public hubConnection: Observable<HubConnection>,
@@ -21,6 +47,12 @@ export class Topic<T> extends Observable<T> {
     });
   }
 
+  /**
+   * Send a fire-and-forget message to the server on this topic.
+   *
+   * @param args - Arguments forwarded to `HubConnection.send()`
+   * @throws {Error} When the hub connection has not been established yet
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public send(...args: any[]): void {
     if (!this.connection) {
@@ -29,6 +61,14 @@ export class Topic<T> extends Observable<T> {
     this.connection.send(this.topic, args);
   }
 
+  /**
+   * Invoke a server method on this topic and wait for a response.
+   *
+   * @template T - Expected return type from the server method
+   * @param args - Arguments forwarded to `HubConnection.invoke()`
+   * @returns Promise resolving with the server's response
+   * @throws {Error} When the hub connection has not been established yet
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public invoke<T>(...args: any[]): Promise<T> {
     if (!this.connection) {

package/src/lib/utils/configure-from-framework.ts

@@ -3,6 +3,18 @@ import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-se
 
 import type { SignalRModuleConfigBuilder } from '../../SignalRModuleConfigurator';
 
+/**
+ * Configure a SignalR hub connection using Fusion Framework service-discovery
+ * and MSAL authentication.
+ *
+ * Resolves the hub endpoint URL from the service registry and creates an
+ * `accessTokenFactory` that acquires tokens via the MSAL auth provider.
+ *
+ * @param args - Hub name, service identifier, and path to append to the resolved service URI
+ * @param builder - Module config builder with access to MSAL and service-discovery instances
+ *
+ * @internal
+ */
 export const configureFromFramework = async (
   args: { name: string; service: string; path: string },
   builder: SignalRModuleConfigBuilder<[MsalModule, ServiceDiscoveryModule]>,

package/src/lib/utils/enable-signalr.ts

@@ -3,13 +3,31 @@ import type { SignalRModuleConfigBuilderCallback } from '../../SignalRModuleConf
 import { module } from '../../SignalRModule';
 import { configureFromFramework } from './configure-from-framework';
 
+/**
+ * Call-signature overloads for {@link enableSignalR}.
+ */
 export interface enableSignalR {
+  /**
+   * Enable SignalR with a custom configuration builder callback.
+   *
+   * @param configurator - The module configurator instance
+   * @param name - Hub name identifier
+   * @param cb - Builder callback for manual hub configuration
+   */
   (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     configurator: IModulesConfigurator<any, any>,
     name: string,
     cb: SignalRModuleConfigBuilderCallback,
   ): void;
+
+  /**
+   * Enable SignalR using service-discovery to resolve the hub URL automatically.
+   *
+   * @param configurator - The module configurator instance
+   * @param name - Hub name identifier
+   * @param options - Service name and path used to resolve the hub endpoint
+   */
   (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     configurator: IModulesConfigurator<any, any>,
@@ -19,31 +37,36 @@ export interface enableSignalR {
 }
 
 /**
+ * Register the SignalR module on a Fusion Framework configurator and add hub
+ * configuration in a single call.
+ *
+ * Accepts either a manual builder callback or a service-discovery shorthand.
+ * When the shorthand form is used, the hub URL and authentication token are
+ * resolved automatically via the service-discovery and MSAL modules.
+ *
+ * @param configurator - The module configurator to register the SignalR module on
+ * @param name - Hub name identifier (used as key in the hub registry)
+ * @param optionsOrCallback - A builder callback for custom configuration, or
+ *   `{ service, path }` to resolve the hub endpoint through service-discovery
+ *
  * @example
- ```ts
- import { 
-    enableSignalR, 
-    configurePortalHub, 
-    configureNotificationHub 
- } from '@equinor/fusion-framework-module-signalr';
-
- export const configure = (configurator) => {
-    enableSignalR(configurator, { 
-        name: 'portal', 
-        service: 'portal', 
-        path: '/signalr/hubs/service-message'
-    });
-    enableSignalR(configurator, 'notifications');
-    // custom
-    enableSignalR(configurator, builder => {
-        builder.addHub('myHub', {
-            uri: 'https://foo.bar',
-            path: '/my_messages'
-            accessTokenFactory: () => makeToken(),
-        })
-    });
- }
- ```
+ * ```ts
+ * import { enableSignalR } from '@equinor/fusion-framework-module-signalr';
+ *
+ * // Using service-discovery shorthand
+ * enableSignalR(configurator, 'portal', {
+ *   service: 'portal',
+ *   path: '/signalr/hubs/service-message',
+ * });
+ *
+ * // Using a custom builder callback
+ * enableSignalR(configurator, 'custom', (builder) => {
+ *   builder.addHub('custom', {
+ *     url: 'https://my-service.example.com/hub',
+ *     options: { accessTokenFactory: () => getToken() },
+ *   });
+ * });
+ * ```
  */
 export function enableSignalR(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '10.0.1';
+export const version = '11.0.0';