@equinor/fusion-framework-module-signalr 10.0.2-next.0 → 11.0.0

package/src/SignalRModuleConfigurator.ts

@@ -7,77 +7,154 @@ import {
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 import type { IHttpConnectionOptions, LogLevel } from '@microsoft/signalr';
 
+/**
+ * Public configuration interface for the SignalR module.
+ *
+ * Consumers use this interface to register hub connections and configuration
+ * callbacks during the module `configure` phase.
+ */
 export interface ISignalRConfigurator {
-  /** add configuration for hub connection */
+  /**
+   * Register a named SignalR hub connection.
+   *
+   * @param name - Unique identifier for the hub (used later with {@link ISignalRProvider.connect})
+   * @param config - Hub connection configuration or a promise that resolves to one
+   */
   addHub(name: string, config: SignalRHubConfig | Promise<SignalRHubConfig>): void;
 
-  /** add callback for building config on init */
+  /**
+   * Register a callback that will run during the module initialization phase
+   * to build configuration using a {@link SignalRModuleConfigBuilder}.
+   *
+   * Use this when hub configuration depends on resolved module dependencies
+   * such as service-discovery or authentication.
+   *
+   * @param cb - Callback that receives a {@link SignalRModuleConfigBuilder}
+   */
   onCreateConfig(cb: SignalRModuleConfigBuilderCallback): void;
 }
 
-/** configuration callback */
+/**
+ * Callback invoked during module initialization to configure SignalR hubs.
+ *
+ * Receives a {@link SignalRModuleConfigBuilder} that provides access to
+ * resolved module dependencies, allowing dynamic hub registration.
+ *
+ * @template TDeps - Tuple of module dependencies available through the builder
+ */
 export type SignalRModuleConfigBuilderCallback<TDeps = unknown> = (
   builder: SignalRModuleConfigBuilder<TDeps>,
 ) => void | Promise<void>;
 
 /**
- * Configuration for hub connection
+ * Configuration for a single SignalR hub connection.
+ *
+ * Defines the endpoint URL, transport options, reconnection behavior,
+ * and logging level for a `@microsoft/signalr` `HubConnection`.
  */
 export type SignalRHubConfig = {
-  /** connection endpoint */
+  /** Absolute URL of the SignalR hub endpoint. */
   url: string;
 
-  /** connection options */
+  /**
+   * Transport and authentication options forwarded to the underlying
+   * `HubConnectionBuilder.withUrl()` call.
+   *
+   * The `httpClient` option is excluded because the module manages the
+   * HTTP client internally.
+   */
   options: Omit<IHttpConnectionOptions, 'httpClient'>;
 
-  /** reconnect when connection lost */
+  /**
+   * When `true`, the connection will automatically attempt to reconnect
+   * after an unintentional disconnection.
+   *
+   * @defaultValue `undefined` (no automatic reconnect)
+   */
   automaticReconnect?: boolean;
+
+  /**
+   * Minimum log level for the SignalR connection logger.
+   *
+   * @defaultValue `LogLevel.Critical` (5) when omitted
+   */
   logLevel?: LogLevel;
 };
 
 /**
- * Configuration for creating SignalR provider
+ * Resolved configuration used to create a {@link SignalRModuleProvider}.
+ *
+ * Contains all registered hub configurations keyed by hub name.
  */
 export type SignalRConfig = {
+  /** Map of hub name to its {@link SignalRHubConfig}. */
   hubs: Record<string, SignalRHubConfig>;
 };
 
 /**
- * builder utility class for generating configuration
+ * Builder utility for registering SignalR hub configurations during
+ * module initialization.
+ *
+ * Extends {@link ModuleConfigBuilder} to provide access to resolved
+ * module dependencies (e.g., service-discovery, authentication) so that
+ * hub URLs and access-token factories can be built dynamically.
+ *
+ * @template TDeps - Tuple of module dependencies available through the builder
  */
 export class SignalRModuleConfigBuilder<
   TDeps extends AnyModule[] | unknown = unknown,
   // TODO - use BaseConfigBuilder
 > extends ModuleConfigBuilder<TDeps, ISignalRConfigurator> {
+  /**
+   * Register a named hub connection through the underlying configurator.
+   *
+   * @param name - Unique hub identifier
+   * @param config - Hub connection configuration
+   */
   async addHub(name: string, config: SignalRHubConfig) {
     this._config.addHub(name, config);
   }
 }
 
+/**
+ * Default {@link ISignalRConfigurator} implementation.
+ *
+ * Collects hub registrations and builder callbacks, then produces a
+ * {@link SignalRConfig} during the module initialization phase.
+ */
 export class SignalRConfigurator implements ISignalRConfigurator {
   #builderCallbacks: Array<SignalRModuleConfigBuilderCallback> = [];
 
   #hubs: Record<string, SignalRHubConfig> = {};
 
   /**
-   * register SignalR hub configuration.
+   * Register a named SignalR hub connection.
+   *
+   * @param name - Unique identifier for the hub
+   * @param config - Hub connection configuration
    */
   public addHub(name: string, config: SignalRHubConfig) {
     this.#hubs[name] = config;
   }
 
   /**
-   * add callback for building config on when configurator is creating config.
-   * {@link SignalRConfigurator.createConfig}
+   * Register a configuration builder callback that will run during
+   * {@link SignalRConfigurator.createConfig}.
+   *
+   * @param cb - Callback receiving a {@link SignalRModuleConfigBuilder}
    */
   public onCreateConfig<T>(cb: SignalRModuleConfigBuilderCallback<T>): void {
     this.#builderCallbacks.push(cb);
   }
 
   /**
-   * normally executed in `init` phase of module, which creates configuration to the module provider.
-   * cycles threw all registered configuration builders.
-   * await all registered hub configurations.
+   * Build the final {@link SignalRConfig} by executing all registered
+   * builder callbacks and collecting hub configurations.
+   *
+   * Normally called during the module `initialize` phase.
+   *
+   * @param init - Module initializer arguments providing access to resolved dependencies
+   * @returns Resolved configuration containing all registered hubs
    */
   public async createConfig(
     init: ModuleInitializerArgs<ISignalRConfigurator, [ServiceDiscoveryModule]>,

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.2-next.0';
+export const version = '11.0.0';