@equinor/fusion-framework-module-signalr 14.0.0 → 14.0.1

package/src/SignalRConfigurator.ts

@@ -1,66 +0,0 @@
-import type { ModuleInitializerArgs } from '@equinor/fusion-framework-module';
-
-import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
-
-import {
-  type ISignalRConfigurator,
-  SignalRModuleConfigBuilder,
-  type SignalRConfig,
-  type SignalRHubConfig,
-  type SignalRModuleConfigBuilderCallback,
-} from './SignalRModuleConfigBuilder';
-
-/**
- * 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 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;
-  }
-
-  /**
-   * Register a configuration builder callback that will run during
-   * {@link SignalRConfigurator.createConfig}.
-   *
-   * @param cb - Callback receiving a {@link SignalRModuleConfigBuilder}
-   * @template T - Type of module dependencies made available to the builder callback
-   */
-  public onCreateConfig<T>(cb: SignalRModuleConfigBuilderCallback<T>): void {
-    this.#builderCallbacks.push(cb);
-  }
-
-  /**
-   * 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]>,
-  ): Promise<SignalRConfig> {
-    /** trigger all builder callbacks */
-    for (const cb of this.#builderCallbacks) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const builder = new SignalRModuleConfigBuilder<[ServiceDiscoveryModule]>(init, this);
-      await Promise.resolve(cb(builder));
-    }
-
-    return { hubs: this.#hubs };
-  }
-}

package/src/SignalRModule.ts

@@ -1,55 +0,0 @@
-import type { Module } from '@equinor/fusion-framework-module';
-import type { ISignalRConfigurator } from './SignalRModuleConfigBuilder';
-import { SignalRConfigurator } from './SignalRConfigurator';
-
-import { type ISignalRProvider, SignalRModuleProvider } from './SignalRModuleProvider';
-
-/** String literal key used to register the SignalR module in the Fusion Framework module system. */
-export type SignalRModuleKey = 'signalR';
-
-/** Module registration key for the SignalR module (`'signalR'`). */
-export const moduleKey: SignalRModuleKey = 'signalR';
-
-/**
- * Module type definition for the SignalR module.
- *
- * Binds the module key, provider interface ({@link ISignalRProvider}), and
- * configurator interface ({@link ISignalRConfigurator}) together for the
- * Fusion Framework module system.
- */
-export type SignalRModule = Module<SignalRModuleKey, ISignalRProvider, ISignalRConfigurator>;
-
-/**
- * SignalR module instance that can be registered with a Fusion Framework configurator.
- *
- * During the `configure` phase, a {@link SignalRConfigurator} is created.
- * During the `initialize` phase, the configurator builds its {@link SignalRConfig}
- * and produces a {@link SignalRModuleProvider}.
- *
- * @example
- * ```ts
- * import { ModuleConfigurator } from '@equinor/fusion-framework-module';
- * import signalR from '@equinor/fusion-framework-module-signalr';
- *
- * configurator.addConfig({ module: signalR });
- * ```
- */
-// Deliberately co-located with the `moduleKey` constant it references
-// fusion-lint-disable-next-line single-export-per-file
-export const module: SignalRModule = {
-  name: moduleKey,
-  configure: () => new SignalRConfigurator(),
-  initialize: async (init) => {
-    const config = await (init.config as SignalRConfigurator).createConfig(init);
-    return new SignalRModuleProvider(config);
-  },
-};
-
-export default module;
-
-/** Augments the global `Modules` interface so that `'signalR'` is a known module key. */
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    signalR: SignalRModule;
-  }
-}

package/src/SignalRModuleConfigBuilder.ts

@@ -1,112 +0,0 @@
-import { type AnyModule, ModuleConfigBuilder } from '@equinor/fusion-framework-module';
-
-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 {
-  /**
-   * 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;
-
-  /**
-   * 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;
-}
-
-/**
- * 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 a single SignalR hub connection.
- *
- * Defines the endpoint URL, transport options, reconnection behavior,
- * and logging level for a `@microsoft/signalr` `HubConnection`.
- */
-export type SignalRHubConfig = {
-  /** Absolute URL of the SignalR hub endpoint. */
-  url: string;
-
-  /**
-   * 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'>;
-
-  /**
-   * 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;
-};
-
-/**
- * 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 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(#5096): 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);
-  }
-}

package/src/SignalRModuleProvider.ts

@@ -1,142 +0,0 @@
-import { HubConnectionBuilder, type HubConnection, AbortError } from '@microsoft/signalr';
-import { Observable, shareReplay } from 'rxjs';
-
-import type { SignalRConfig } from './SignalRModuleConfigBuilder';
-
-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 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>(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;
-
-    // Reuse an already-established connection observable for this hub
-    if (hubId in this.#hubConnections) {
-      return this.#hubConnections[hubId];
-    }
-    const config = this.#config.hubs[hubId];
-    // Fail loudly when the hub was never registered with the configurator
-    if (!config) {
-      throw Error(`could not find any configuration for hub [${hubId}]`);
-    }
-
-    this.#hubConnections[hubId] = new Observable<HubConnection>((observer) => {
-      const builder = new HubConnectionBuilder().withUrl(config.url, {
-        ...config.options,
-      });
-
-      config.automaticReconnect && builder.withAutomaticReconnect();
-
-      builder.configureLogging(config.logLevel || LOG_LEVEL_CRITICAL);
-
-      const connection = builder.build();
-
-      connection
-        .start()
-        .then(() => {
-          observer.next(connection);
-        })
-        .catch((error: unknown) => {
-          // Swallow expected teardown aborts; re-throw anything else
-          if (error instanceof 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();
-        delete this.#hubConnections[hubId];
-      };
-
-      return teardown;
-    })
-      // Share a single connection across subscribers and tear it down when unused
-      .pipe(
-        shareReplay({
-          /** only emit last connection when new subscriber connects */
-          bufferSize: 1,
-          /** when no subscribers, teardown observable */
-          refCount: true,
-        }),
-      );
-
-    return this.#hubConnections[hubId];
-  }
-}
-
-export default SignalRModuleProvider;

package/src/index.ts

@@ -1,31 +0,0 @@
-/**
- * @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,
-  SignalRConfig,
-  SignalRHubConfig,
-  SignalRModuleConfigBuilder,
-  SignalRModuleConfigBuilderCallback,
-} from './SignalRModuleConfigBuilder';
-
-export { SignalRConfigurator } from './SignalRConfigurator';
-
-export { ISignalRProvider, SignalRModuleProvider } from './SignalRModuleProvider';
-
-export { Topic } from './lib/Topic';
-
-export { enableSignalR } from './lib/utils/enable-signalr';
-
-export { default, module, moduleKey, SignalRModule, SignalRModuleKey } from './SignalRModule';

package/src/lib/Topic.ts

@@ -1,79 +0,0 @@
-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>,
-  ) {
-    super((subscriber) => {
-      const hubConnectionSubscription = hubConnection.subscribe((connection) => {
-        const cb = subscriber.next.bind(subscriber);
-        connection.on(topic, cb);
-        subscriber.add(() => connection.off(topic, cb));
-        this.connection = connection;
-      });
-      subscriber.add(() => {
-        hubConnectionSubscription.unsubscribe();
-      });
-    });
-  }
-
-  /**
-   * 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
-   */
-  public send(...args: unknown[]): void {
-    // A connection must have been established before sending is possible
-    if (!this.connection) {
-      throw new Error('No hub connection awaitable');
-    }
-    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
-   */
-  public invoke<T>(...args: unknown[]): Promise<T> {
-    // A connection must have been established before invoking is possible
-    if (!this.connection) {
-      throw new Error('No hub connection awaitable');
-    }
-    return this.connection?.invoke(this.topic, args);
-  }
-}

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

@@ -1,47 +0,0 @@
-import type { MsalModule } from '@equinor/fusion-framework-module-msal';
-import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
-
-import type { SignalRModuleConfigBuilder } from '../../SignalRModuleConfigBuilder';
-
-/**
- * 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]>,
-) => {
-  const authProvider = await builder.requireInstance('auth');
-  const serviceDiscovery = await builder.requireInstance('serviceDiscovery');
-  const service = await serviceDiscovery.resolveService(args.name);
-  builder.addHub(args.name, {
-    url: new URL(args.path, service.uri).toString(),
-    options: {
-      accessTokenFactory: async () => {
-        // Scopes are required to acquire a token for this service
-        if (!service.scopes) {
-          throw Error(
-            `service [${service.name}] does not have authentication scopes, please configure an endpoint with scopes`,
-          );
-        }
-        const token = await authProvider.acquireAccessToken({
-          request: { scopes: service.scopes ?? service.defaultScopes },
-        });
-        // Fail loudly rather than connecting the hub without a valid token
-        if (!token) {
-          throw Error('failed to acquire access token');
-        }
-        return token;
-      },
-    },
-    automaticReconnect: true,
-  });
-};

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

@@ -1,95 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-import type { SignalRModuleConfigBuilderCallback } from '../../SignalRModuleConfigBuilder';
-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
-   */
-  (
-    // biome-ignore lint/suspicious/noExplicitAny: IModulesConfigurator<any, any> widens to accept a configurator for any concrete module set
-    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
-   */
-  (
-    // biome-ignore lint/suspicious/noExplicitAny: IModulesConfigurator<any, any> widens to accept a configurator for any concrete module set
-    configurator: IModulesConfigurator<any, any>,
-    name: string,
-    options: { service: string; path: string },
-  ): void;
-}
-
-/**
- * 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 } 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(
-  // biome-ignore lint/suspicious/noExplicitAny: IModulesConfigurator<any, any> widens to accept a configurator for any concrete module set
-  configurator: IModulesConfigurator<any, any>,
-  name: string,
-  optionsOrCallback: SignalRModuleConfigBuilderCallback | { service: string; path: string },
-) {
-  // Callback form configures the hub directly against the resolved builder
-  if (typeof optionsOrCallback === 'function') {
-    configurator.addConfig({
-      module,
-      configure: (signalRConfigurator) => {
-        signalRConfigurator.onCreateConfig(optionsOrCallback);
-      },
-    });
-  } else {
-    configurator.addConfig({
-      module,
-      configure: (signalRConfigurator) => {
-        signalRConfigurator.onCreateConfig((builder) =>
-          configureFromFramework({ name, ...optionsOrCallback }, builder),
-        );
-      },
-    });
-  }
-}

package/src/version.ts

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

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist/esm",
-    "rootDir": "src",
-    "declarationDir": "./dist/types"
-  },
-  "references": [
-    {
-      "path": "../module"
-    },
-    {
-      "path": "../services"
-    },
-    {
-      "path": "../event"
-    }
-  ],
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}