@equinor/fusion-framework-module-http 5.2.3 → 6.0.1

package/src/lib/operators/types.ts

@@ -1,12 +1,18 @@
 import type { Observable } from 'rxjs';
 import type { FetchRequest } from '../client';
 
-export type ProcessOperator<T, R = T> = (request: T) => R | void | Promise<R | void>;
-
 /**
- * Container for sync/async operators.
- * Pipes each operator sequential
+ * A process operator that takes a request of type `T` and returns a transformed request of type `R`, or `void`, or a Promise that resolves to `R` or `void`.
+ *
+ * Process operators are used to transform or modify requests in a sequential pipeline before they are processed by an `IHttpRequestHandler`.
+ *
+ * @template T The type of the input request.
+ * @template R The type of the output request. Defaults to `T` if not specified.
+ * @param request The input request to be processed.
+ * @returns The transformed request, `void`, or a Promise that resolves to the transformed request or `void`.
  */
+export type ProcessOperator<T, R = T> = (request: T) => R | void | Promise<R | void>;
+
 /**
  * Represents a collection of process operators.
  * @template T The type of the request being processed.
@@ -49,6 +55,12 @@ export interface IProcessOperators<T> {
     process(request: T): Observable<T>;
 }
 
+/**
+ * Represents an HTTP request handler that extends the `IProcessOperators` interface.
+ * This interface provides methods to manage and process HTTP request operators.
+ *
+ * @template T - The type of the request being processed. Defaults to `FetchRequest`.
+ */
 export interface IHttpRequestHandler<T extends FetchRequest = FetchRequest>
     extends IProcessOperators<T> {
     /**
@@ -59,4 +71,10 @@ export interface IHttpRequestHandler<T extends FetchRequest = FetchRequest>
     setHeader(key: string, value: string): IHttpRequestHandler<T>;
 }
 
+/**
+ * Represents an HTTP response handler that extends the `IProcessOperators` interface.
+ * This interface provides methods to manage and process HTTP response operators.
+ *
+ * @template T - The type of the response being processed. Defaults to `Response`.
+ */
 export interface IHttpResponseHandler<T = Response> extends IProcessOperators<T> {}

package/src/lib/selectors/blob-selector.ts

@@ -1,17 +1,39 @@
-export const blobSelector = <TResponse extends Response = Response>(
+import type { ResponseSelector, BlobResult } from '../client/types';
+
+/**
+ * Extracts a blob and filename from a successful HTTP response.
+ *
+ * @param response - The HTTP response to extract the blob and filename from.
+ * @returns A promise that resolves to an object containing the extracted blob and filename.
+ * @throws {Error} If the response is not successful or if there is an error parsing the response.
+ */
+export const blobSelector: ResponseSelector = async <TResponse extends Response = Response>(
     response: TResponse,
-): Promise<Blob> => {
+): Promise<BlobResult> => {
     if (!response.ok) {
+        // Throw an error if the network response is not successful
         throw new Error('network response was not OK');
     }
-    //Status code 204 is no content
+
+    // Status code 204 indicates no content, so throw an error
     if (response.status === 204) {
         throw new Error('no content');
     }
 
+    // Extract the filename from the 'content-disposition' header
+    const filename = response.headers
+        .get('content-disposition')
+        ?.split(';')
+        .find((n) => n.includes('filename='))
+        ?.replace('filename=', '')
+        ?.trim();
+
     try {
-        return response.blob();
+        // Convert the response to a Blob and return the filename and Blob
+        const blob = await response.blob();
+        return { filename, blob };
     } catch (err) {
+        // Throw an error if there's a problem parsing the response
         throw Error('failed to parse response');
     }
 };

package/src/lib/selectors/index.ts

@@ -1,2 +1,4 @@
 export { jsonSelector } from './json-selector';
 export { blobSelector } from './blob-selector';
+
+export type { ResponseSelector } from '../client/types';

package/src/lib/selectors/json-selector.ts

@@ -1,30 +1,50 @@
+import type { ResponseSelector } from '../client/types';
 import { HttpJsonResponseError } from '../../errors';
 
 /**
- * Converts the JSON response from an HTTP request into the specified type.
- * If the response is not OK or if there is an error parsing the response, an error is thrown.
- * If the response has a status code of 204 (No Content), a resolved Promise is returned.
+ * Asynchronously parses the JSON data from a given HTTP response.
  *
- * @param response The HTTP response object.
- * @returns A Promise that resolves to the parsed JSON data.
- * @throws {Error} If the network response is not OK.
- * @throws {HttpJsonResponseError} If there is an error parsing the response.
+ * If the response has a status code of 204 (No Content), this function will resolve with `undefined`.
+ *
+ * If the response is not successful (i.e. `response.ok` is `false`), this function will throw an `HttpJsonResponseError` with the response details and the parsed data (if any).
+ *
+ * If there is an error parsing the JSON data, this function will throw an `HttpJsonResponseError` with the parsing error and the original response.
+ *
+ * @template TType - The expected type of the parsed JSON data.
+ * @template TResponse - The type of the HTTP response object.
+ * @param response - The HTTP response to parse.
+ * @returns A promise that resolves with the parsed JSON data, or rejects with an `HttpJsonResponseError`.
  */
-export const jsonSelector = async <TType = unknown, TResponse extends Response = Response>(
+export const jsonSelector: ResponseSelector = async <
+    TType = unknown,
+    TResponse extends Response = Response,
+>(
     response: TResponse,
 ): Promise<TType> => {
-    /** Status code 204 is no content */
+    /** Status code 204 indicates no content in the response */
     if (response.status === 204) {
         return Promise.resolve() as Promise<TType>;
     }
 
     try {
+        // Parse the response JSON data
         const data = await response.json();
+
+        // Check if the response was successful
         if (!response.ok) {
+            // Throw an error with the response details
             throw new HttpJsonResponseError('network response was not OK', response, { data });
         }
+
+        // Return the parsed data
         return data;
     } catch (cause) {
+        // If the cause is an HttpJsonResponseError, rethrow it
+        if (cause instanceof HttpJsonResponseError) {
+            throw cause;
+        }
+
+        // Otherwise, throw a new HttpJsonResponseError with the parsing error
         throw new HttpJsonResponseError('failed to parse response', response, { cause });
     }
 };

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 = '5.2.3';
+export const version = '6.0.1';