@equinor/fusion-framework-module-http 6.0.0 → 6.0.2

package/src/module.ts

@@ -11,8 +11,23 @@ import type {
 
 import { MsalModule } from '@equinor/fusion-framework-module-msal';
 
+/**
+ * Defines the type for the HTTP module, which includes:
+ * - The module name: 'http'
+ * - The type of the HTTP client provider, which is `IHttpClientProvider`
+ * - The type of the HTTP client configurator, which is `IHttpClientConfigurator`
+ */
 export type HttpModule = Module<'http', IHttpClientProvider, IHttpClientConfigurator>;
 
+/**
+ * Defines the type for the HTTP module with MSAL authentication.
+ *
+ * This type represents the module configuration for the HTTP module, which includes:
+ * - The module name: 'http'
+ * - The type of the HTTP client provider, which is `IHttpClientProvider<HttpClientMsal>`
+ * - The type of the HTTP client configurator, which is `IHttpClientConfigurator<HttpClientMsal>`
+ * - The list of required modules, which includes the `MsalModule`
+ */
 export type HttpMsalModule = Module<
     'http',
     IHttpClientProvider<HttpClientMsal>,
@@ -21,11 +36,33 @@ export type HttpMsalModule = Module<
 >;
 
 /**
- *  Configure http-client
+ * HTTP module with MSAL authentication.
  */
 export const module: HttpMsalModule = {
     name: 'http',
+    /**
+     * Configures the HTTP module with MSAL authentication.
+     *
+     * This function creates a new `HttpClientConfigurator` instance using the `HttpClientMsal` class.
+     * The `HttpClientConfigurator` is responsible for configuring the HTTP client with the necessary options,
+     * such as the base URL, request headers, and other settings.
+     *
+     * @returns A new `HttpClientConfigurator` instance configured for MSAL authentication.
+     */
     configure: () => new HttpClientConfigurator(HttpClientMsal),
+
+    /**
+     * Initializes the HTTP client provider with MSAL authentication.
+     *
+     * This function is responsible for setting up the default HTTP request handler
+     * to acquire an access token from MSAL and attach it to the request headers
+     * when the request includes scopes.
+     *
+     * @param config - The module configuration.
+     * @param hasModule - A function to check if a module is available.
+     * @param requireInstance - A function to get an instance of a module.
+     * @returns A promise that resolves to the HTTP client provider.
+     */
     initialize: async ({
         config,
         hasModule,
@@ -53,14 +90,27 @@ export const module: HttpMsalModule = {
     },
 };
 
+/**
+ * Configures the HTTP module with MSAL authentication.
+ */
 export const configureHttp = <TRef = unknown>(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     configure: (config: ModuleConfigType<HttpMsalModule>, ref?: TRef) => void,
 ): IModuleConfigurator<HttpMsalModule, TRef> => ({
     module,
     configure,
 });
 
+/**
+ * Configures the HTTP client with MSAL authentication.
+ *
+ * This function creates a module configurator that can be used to configure the HTTP module
+ * with MSAL authentication. The configurator takes a name and a set of HTTP client options,
+ * and returns a module configurator that can be used to configure the HTTP module.
+ *
+ * @param name - The name of the HTTP client configuration.
+ * @param args - The HTTP client options, including the MSAL configuration.
+ * @returns A module configurator that can be used to configure the HTTP module.
+ */
 export const configureHttpClient = <TRef = unknown>(
     name: string,
     args: HttpClientOptions<HttpClientMsal>,
@@ -71,6 +121,9 @@ export const configureHttpClient = <TRef = unknown>(
     },
 });
 
+/**
+ * Declares a module named '@equinor/fusion-framework-module' that contains an interface named 'Modules' with a property 'http' of type 'HttpMsalModule'.
+ */
 declare module '@equinor/fusion-framework-module' {
     interface Modules {
         http: HttpMsalModule;

package/src/provider.ts

@@ -15,12 +15,27 @@ export class ClientNotFoundException extends Error {
 }
 
 export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient> {
+    /**
+     * The default HTTP request handler used by the HttpClientProvider.
+     * This handler is responsible for executing HTTP requests using the configured HttpClient.
+     */
     readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
-    /** check if a client is configured */
+
+    /**
+     * Checks if a client is configured with the given key.
+     * @param key - The key of the client to check.
+     * @returns `true` if a client is configured with the given key, `false` otherwise.
+     */
     hasClient(key: string): boolean;
-    /** create a new http client */
+
+    /**
+     * Creates a new HTTP client instance with the specified key.
+     * @param key - The key of the HTTP client to create.
+     * @returns The created HTTP client instance.
+     */
     createClient(key: string): TClient;
     createClient(key: HttpClientOptions<TClient>): TClient;
+
     /**
      * Class cast creation of custom client
      * @example
@@ -33,6 +48,11 @@ export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient>
     createCustomClient<T extends HttpClient>(key: string): T;
 }
 
+/**
+ * Checks if a given string is a valid URL.
+ * @param url - The string to check for a valid URL.
+ * @returns `true` if the input string is a valid URL, `false` otherwise.
+ */
 const isURL = (url: string) => {
     const pattern = new RegExp(
         '^(https?:\\/\\/)?' + // protocol
@@ -46,19 +66,52 @@ const isURL = (url: string) => {
     return pattern.test(url);
 };
 
+/**
+ * The `HttpClientProvider` class is responsible for managing HTTP client instances and their configuration.
+ * It provides methods to check if a client is configured, create new client instances, and create custom client instances.
+ */
 export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
     implements IHttpClientProvider<TClient>
 {
+    /**
+     * Gets the default HTTP request handler for the HTTP client provider.
+     * @returns The default HTTP request handler.
+     */
     get defaultHttpRequestHandler(): IHttpRequestHandler<HttpClientRequestInitType<TClient>> {
         return this.config.defaultHttpRequestHandler;
     }
 
     constructor(protected config: IHttpClientConfigurator<TClient>) {}
 
+    /**
+     * Checks if a client with the given key is configured in the `HttpClientProvider`.
+     * @param key - The key of the HTTP client to check.
+     * @returns `true` if a client with the given key is configured, `false` otherwise.
+     */
     public hasClient(key: string): boolean {
         return Object.keys(this.config.clients).includes(key);
     }
 
+    /**
+     * Creates a new HTTP client instance with the specified configuration.
+     *
+     * @param keyOrConfig - The key or configuration object for the HTTP client.
+     * @returns The created HTTP client instance.
+     *
+     * @remarks
+     * This method resolves the configuration for the HTTP client based on the provided `keyOrConfig` parameter.
+     * If a string is provided, it is treated as the key for a pre-configured client in the `HttpClientProvider`.
+     * If an `HttpClientOptions` object is provided, it is used as the configuration for the new client instance.
+     *
+     * The method sets up the HTTP client with the following options:
+     * - `baseUri`: The base URI for the HTTP client.
+     * - `defaultScopes`: The default scopes to be used for authentication.
+     * - `onCreate`: An optional callback function that is called when the client instance is created.
+     * - `ctor`: The constructor function for the HTTP client, defaulting to the configured `defaultHttpClientCtor`.
+     * - `requestHandler`: The HTTP request handler to be used by the client, defaulting to the `defaultHttpRequestHandler`.
+     *
+     * The created HTTP client instance is returned.
+     */
     public createClient(keyOrConfig: string | HttpClientOptions<TClient>): TClient {
         const config = this._resolveConfig(keyOrConfig);
         const {
@@ -75,10 +128,31 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
         return instance as TClient;
     }
 
+    /**
+     * Creates a new HTTP client instance with the specified configuration.
+     *
+     * @param key - The key of the pre-configured HTTP client to create.
+     * @returns The created HTTP client instance, cast to the specified type `T`.
+     *
+     * @remarks
+     * This method delegates to the `createClient` method, but casts the returned
+     * instance to the specified type `T`. This can be useful when you need to
+     * work with a specific HTTP client implementation, but the `HttpClientProvider`
+     * is configured to use a different implementation.
+     */
     public createCustomClient<T extends HttpClient>(key: string): T {
         return this.createClient(key) as unknown as T;
     }
 
+    /**
+     * Resolves the configuration for an HTTP client based on the provided `keyOrConfig` parameter.
+     *
+     * If a string is provided, it is treated as the key for a pre-configured client in the `HttpClientProvider`.
+     * If an `HttpClientOptions` object is provided, it is used as the configuration for the new client instance.
+     *
+     * @param keyOrConfig - The key or configuration object for the HTTP client.
+     * @returns The resolved HTTP client configuration.
+     */
     protected _resolveConfig(
         keyOrConfig: string | HttpClientOptions<TClient>,
     ): HttpClientOptions<TClient> {

package/src/version.ts

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